安装 Antora

要使用 Antora 生成和发布文档站点，您需要 Antora 命令行界面（CLI）和官方 Antora 站点生成器或自定义生成器。本页面解释了如何使用默认配置安装 Antora。

假设：

  • 您已在 Linux、Windows 或 macOS 机器上安装了活跃的 Node.js LTS 版本。

在本页面，您将学习到：

  • 如何在不安装的情况下运行 Antora。

  • 如何在本地安装 Antora（推荐）。

  • 如何全局安装 Antora CLI 和站点生成器包。

在安装之前尝试

如果您只是在评估 Antora，您可以使用 npx 在不安装的情况下运行它。

$ npx antora -v

npx 命令由 Node.js 提供，可以直接从本地或远程 npm 包运行命令。如果本地项目依赖中缺少任何必需的包，npx 将在运行命令之前将它们安装到缓存文件夹（通常是 $HOME/.npm/_npx）。如果命令的名称与提供它的包的名称匹配，您无需指定包名称。在这种情况下，打包了 CLI 和站点生成器的 antora 包提供了 antora 命令及其运行所需的依赖项。

仅用于评估时使用 npx 而不安装任何包，并且仅在单独使用 Antora 时有效。一旦需要额外的包，您需要在运行 npx 之前将它们与 Antora 一起安装。

稍后您将看到，我们建议在本地安装后使用 npx 命令运行 Antora。

本地 vs 全局

在本页面中提到的“本地”，指的是播放簿项目内（即站点播放簿文件所在的目录）或任何父文件夹内。我们建议特别是在管理多个文档站点时，在本地安装 Antora，这样更容易管理 Antora 的版本，并确保 Antora 的版本与播放簿制作时的版本匹配。这还可以避免在尝试全局安装 Antora 时可能遇到的任何权限问题。

在本页面中提到的“全局”，并不一定意味着系统范围。而是指 Node.js 安装的位置。如果您使用 nvm 安装 Node.js，则此位置将位于您的主目录内（因此不需要提升权限）。我们只建议在熟悉 Antora 工作原理并对此设置感到舒适时全局安装 Antora。

您成功的最佳机会是在本地安装 Antora。至少，您应该从那里开始。

在本地安装 Antora

要在本地安装 Antora，请首先切换到播放簿项目的目录（如有必要，创建该目录）。我们在这里假设该文件夹的名称为 docs-site。

$ cd docs-site

接下来，让我们在播放簿项目中安装 CLI 包，以便您可以使用 npx 运行 antora 命令。

$ node -e "fs.writeFileSync('package.json', '{}')"
$ npm i -D -E @antora/cli@3.1

作为第一个命令的替代方案，您可以使用 npm init -y。但是，npm init 会添加许多您可能不需要的额外键。

@antora/cli 包及其依赖项将安装到播放簿项目内的 node_modules 文件夹中。可选的 -D 选项告诉 npm 将该包保存为 package.json 中的开发依赖项。-E 选项告诉 npm 将确切的版本存储在 package.json 中，而不是用语义版本范围运算符进行前缀。

包名称开头的 @ 告诉 npm，cli 包位于 @antora 范围下。如果省略此字符，npm 将假定包名称是 GitHub 上的 git 存储库名称。
包名称中第二个 @ 指定请求的版本号的开始。除了预发布版本，您只能指定主要和次要段（例如，@3.1），这样可以确保获取最新的补丁版本。

当您在本地安装 Antora 时，antora 命令不会放置在您的 PATH 中。相反，您可以使用 npx 运行 antora 命令（即 npx antora）。

通过运行 npx antora -v 验证 antora 命令是否可通过 npx 使用。

$ npx antora -v

此命令应在终端中报告 Antora CLI 的版本。

@antora/cli: 3.1.7
@antora/site-generator: 未安装

npx 命令将查找播放簿项目内或播放簿项目的任何父目录中安装的 antora 命令。如果提示您安装 antora 包，则表示未找到 CLI。

如果您使用 Bash，可以通过为 npx antora 创建一个名为 antora 的别名来节省一些输入：

$ alias antora='npx antora'

现在，您可以运行 antora 而无需记住要在前面加上 npx：

$ antora -v

您可以通过在命令前加上反斜杠来绕过此别名，这将在您的 PATH 中搜索 antora：

$ \antora -v

尽管 npx 找到了 antora 命令并报告了 CLI 版本，但我们仍然缺少站点生成器。接下来，在播放簿项目内安装站点生成器包：

$ npm i -D -E @antora/site-generator@3.1

@antora/site-generator 包及其依赖项将安装到播放簿项目内的 node_modules 文件夹中。Antora 的 CLI 将首先在此文件夹中查找站点生成器包，然后再查找全局安装文件夹。

现在，当您运行 npx antora -v 时，您应该在终端中看到 Antora CLI 和站点生成器的版本。

@antora/cli: 3.1.7
@antora/site-generator: 3.1.7

如果您打开 package.json，您还会看到这些包的版本列在那里，作为开发依赖项。

{
  "devDependencies": {
    "@antora/cli": "3.1.7",
    "@antora/site-generator": "3.1.7"
  }
}

您还会注意到另一个名为 package-lock.json 的附加文件。该文件存储了所有包及其依赖项的解析版本。您可以选择在提交 package.json 时提交此文件。

如果要重新安装 Antora，最好先删除 node_modules 文件夹。如果还想获取每个依赖项的最新版本，还要删除 package-lock.json 文件。如果删除了 node_modules 文件夹，请确保重新安装 CLI 包。另一种选择是使用 npm ci，在重新安装时会自动删除 node_modules。

如果 antora 命令报告了 CLI 和站点生成器的版本，并且这些版本匹配，那就确认您已正确安装 Antora。

全局安装 Antora

您可以选择全局安装 Antora，这样 antora 命令就可以在您的 PATH 中使用。要全局安装 Antora，请在 npm i 命令中加入 -g 选项。

$ npm i -g @antora/cli@3.1 @antora/site-generator@3.1

通过运行以下命令验证 antora 命令是否在您的 PATH 中可用：

$ antora -v

如果安装成功，该命令应报告 Antora CLI 和站点生成器的版本。

$ antora -v
@antora/cli: 3.1.7
@antora/site-generator: 3.1.7

全局安装 Antora 的好处是，无论您在哪个目录中，它都始终在终端中可用。虽然这一开始看起来很方便，但这种策略存在问题。您安装的 Antora 版本可能与文档站点所需的 Antora 版本不匹配。而且 Antora 或文档站点无法验证它们是否相同。因此，您可能会遇到奇怪的问题，并发现自己在努力使它们同步。在本地安装 Antora 并使用 npx 运行将为您带来最佳的成功和兼容性机会。

如果您使用操作系统软件包管理器管理的系统范围 Node.js 安装，可能在全局安装软件包时遇到权限问题。在这种情况下，您需要直接在项目存储库中安装 Antora。

了解更多

现在 Antora 已安装完成，您可以：