安装 Antora
安装前试用
如果只是评估 Antora，可以使用 npx 运行它，而无需先安装。
$ npx antora -v
Node.js 提供的 npx 命令可直接从本地或远程 npm 软件包运行命令。如果本地项目依赖关系中没有任何所需软件包，npx 会在运行命令前将其安装到缓存文件夹（通常为 $HOME/.npm/_npx）中。如果命令名称与提供该命令的软件包名称一致，则无需指定软件包名称。在这种情况下，捆绑了 CLI 和站点生成器的 antora 软件包提供了 antora 命令及其运行所需的依赖项。
在未安装任何软件包的情况下使用 npx 仅用于评估，且仅在单独使用 Antora 时有效。一旦你需要额外的软件包，就需要在运行 npx 之前与 Antora 一起安装。
稍后您将看到，我们建议您在本地安装 Antora 后使用 npx 命令运行 Antora。
本地与全球
本页面中的 "本地" 指的是播放列表项目（即站点播放列表文件所在的目录）或任何父文件夹。我们建议您在本地安装 Antora，尤其是在管理多个文档站点的情况下。在本地安装 Antora 可以更方便地管理 Antora 的版本，并确保 Antora 的版本与制作播放列表的版本一致。它还能避免在全局安装 Antora 时可能遇到的权限问题。
当我们在本页面上说 "全局" 时，并不一定是指整个系统。而是指安装 Node.js 的位置。如果您使用 nvm 安装 Node.js，该位置将位于您的主目录内（因此不需要提升权限）。只有当您熟悉 Antora 的工作原理并能适应这种设置时，我们才建议您全局安装 Antora。
在本地安装 Antora 是成功的最佳途径。至少，您应该从本地开始安装。
在本地安装 Antora
要在本地安装 Antora，首先切换到 playbook 项目的目录（必要时创建该目录）。我们假设该文件夹名为 docs-site。
$ cd docs-site
接下来，让我们在 playbook 项目中安装 CLI 软件包，以便使用 npx 运行 antora 命令。
$ node -e "fs.writeFileSync('package.json', '{}')"
$ npm i -D -E @antora/cli@3.1
除了第一条命令，你还可以使用 npm init -y。不过，npm init 增加了很多额外的键值，你可能并不需要。
@antora/cli 软件包及其依赖关系将被安装到 playbook 项目中的 node_modules 文件夹。可选的 -D 选项会告诉 npm 将软件包作为开发依赖保存在 package.json 中。可选的 -E 选项会告诉 npm 在 package.json 中保存确切的版本，而不是使用 semver 范围运算符作为前缀。
软件包名称开头的 @ 会告知 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.3 @antora/site-generator: not installed
npx 命令会查找安装在 playbook 项目或该项目父目录下的 antora 命令。如果提示安装 antora 软件包，则表示未找到 CLI。
如果使用 Bash，可以为 npx antora 创建一个名为 antora 的别名，以节省输入：
$ alias antora='npx antora'
现在，你可以运行 antora，而不必记得用 npx 作为前缀：
$ antora -v
您可以在命令前加上反斜杠，绕过这个别名，这样就可以在 PATH 中搜索 antora。
$ \antora -v
虽然 npx 找到了 antora 命令并报告了 CLI 版本，但我们仍然缺少站点生成器。接下来，在 playbook 项目中安装站点生成器软件包：
$ npm i -D -E @antora/site-generator@3.1
@antora/site-generator 软件包及其依赖项将被安装到 playbook 项目内的 node_modules 文件夹中。Antora 的 CLI 会先在该文件夹中查找站点生成器软件包，然后再查找全局安装文件夹。
现在，当你运行 npx antora -v 时，你应该能在终端中看到 Antora CLI 和网站生成器的版本。
@antora/cli: 3.1.3 @antora/site-generator: 3.1.3
如果打开 package.json，你会看到这些软件包的版本也作为开发依赖项列出。
{
"devDependencies": {
"@antora/cli": "3.1.3",
"@antora/site-generator": "3.1.3"
}
}你还会发现一个名为 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.3 @antora/site-generator: 3.1.3
全局安装 Antora 的好处是，无论您在哪个目录下，它都能在您的终端上运行。虽然一开始看起来很方便，但这种策略也有问题。您安装的 Antora 版本可能与文档网站的 Antora 版本不一致。而且 Antora 或文档网站也无法验证版本是否一致。因此，您最终可能会遇到一些深奥的问题，并发现自己在努力使它们保持同步。在本地安装 Antora 并使用 npx 运行，将为您带来最佳的成功机会和兼容性。
| 如果您使用的是由操作系统软件包管理器管理的全系统 Node.js 安装，在全局安装软件包时可能会遇到权限问题。在这种情况下，您需要直接 在项目仓库中安装 Antora。 |