使用 Ruby 包安装

使用 Ruby 打包意味着使用 Ruby (gem 和 bundle) 提供的命令来安装 gem。Gem 是一个打包好的 Ruby 应用程序或库，通常从 RubyGems.org 获取。

使用 Ruby 打包安装 Asciidoctor 的好处是它的通用性。只要你正确配置了 Ruby，Ruby 打包在所有 Ruby 运行时和操作系统上都能以相同的方式工作。本页将介绍如何使用 Ruby 打包从 asciidoctor gem 安装 Asciidoctor。

除非你在容器（Docker、podman、OCI）中运行，否则切勿以 root 用户使用 gem install 安装 gem。这样做几乎肯定会干扰并可能损坏你系统上的 Ruby 安装。我们强烈建议你使用 Bundler 在项目（或 RVM gemset 以将安装范围限定在你的用户/主目录）中管理你的 gem。gem install 说明仅在你在容器中运行或使用 RVM（最好使用 gemset）时提供。

配置 Ruby 打包

如果你在使用 Linux，确保 Ruby 配置为使用 Ruby 打包的最佳方法是使用 Ruby 版本管理器安装 Ruby。我们建议你设置 RVM 并使用它在你的主目录（即用户空间）中安装 Ruby。完成后，你可以安全地使用 gem 或 bundle 命令来安装或更新 Asciidoctor gem，或任何其他 gem。使用 RVM 管理的 Ruby 时，gem 会安装在与系统隔离的位置（因此你不需要 root/管理员权限）。

如果你在使用 Windows，你可以使用 Chocolatey 或 RubyInstaller 来安装 Ruby。在使用 Windows 时，你将无法使用 RVM。

如果你在使用 macOS，你可以直接使用 Homebrew 来安装 Asciidoctor，但使用 RVM 也是一个选项。

gem install

安装 Ruby 后（如果使用 RVM，则已使用 rvm use 3.3 激活），打开终端并输入

$ gem install asciidoctor

如果 gem 安装成功，Asciidoctor 的 命令行界面 (CLI) 将在你的 PATH 中可用。要确认 Asciidoctor 可用，请执行

$ asciidoctor --version

你应该会在终端中看到关于 Asciidoctor 版本和你的 Ruby 环境的信息。

Asciidoctor 2.0.26 [https://asciidoctor.org.cn]
Runtime Environment (ruby 3.3.0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

安装预发布版本

要安装 Asciidoctor 的预发布版本（例如，发布候选版），请在运行 gem install 命令时包含 --pre 选项

$ gem install asciidoctor --pre

--pre 选项将选择 Asciidoctor 的预发布版本，而不是最新的稳定版本。请注意，如果当前没有可用的新预发布版本，预发布版本可能比最新的稳定版本旧。

Bundler

Bundler 创建一个虚拟环境，将 gem 的安装范围限定在当前项目。以下是如何使用它来安装和运行 Asciidoctor。

  1. 在项目的根文件夹（或当前目录）中创建一个 Gemfile

    $ bundle init

  2. 将 asciidoctor gem 添加到 Gemfile 的底部，如下所示

    gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '2.0.26'

  3. 保存 Gemfile

  4. 打开终端并使用以下命令安装 gem

    $ bundle

要升级 gem，请在 Gemfile 中指定新版本并再次运行 bundle。不推荐使用 bundle update（不指定 gem），因为它还会更新其他 gem，这可能不是期望的结果。

一旦使用 Bundler 安装，你就必须从 Gemfile 所在的目录运行 gem 提供的任何可执行文件（例如 asciidoctor），并且还必须在可执行文件名之前加上 bundle exec（例如 bundle exec asciidoctor）。bundle exec 前缀告诉 Ruby 使用 Gemfile 中定义的 gem。

如果你想更多地了解 Bundler 和 bundle exec 以及何时使用它们，请参阅文章 Understanding Bundler。

使用 gem update 升级

建议不要使用 gem update 命令来更新由包管理器管理的 gem。这样做会使系统处于不一致状态，因为包管理器无法再跟踪文件（这些文件安装在 /usr/local 下）。简单来说，系统 gem 只能由包管理器更新。

如果你想使用比包管理器安装的更新版本的 Asciidoctor，你应该使用 RVM 在你的主目录（即用户空间）中安装 Ruby。然后，你可以安全地使用 gem 命令来安装或更新 Asciidoctor gem。使用 RVM 时，gem 会安装在与系统隔离的位置。

你可以使用 gem update 命令升级 Asciidoctor

$ gem update asciidoctor

如果你不小心使用了 gem install 而不是 gem update，那么你将同时拥有两个版本。要删除旧版本，请使用以下 gem 命令

$ gem cleanup asciidoctor

使用 gem uninstall 卸载

你可以使用 gem uninstall 命令卸载 Asciidoctor

$ gem uninstall -x asciidoctor

-x 选项可以静默移除 asciidoctor 可执行文件的确认，而是自动移除它。换句话说，它启用了完全卸载。

如果你安装了多个 Asciidoctor 版本，系统会提示你指定要卸载哪个版本。

Select gem to uninstall:
 1. asciidoctor-2.0.15
 2. asciidoctor-2.0.16
 3. All versions
>

你可以卸载特定版本或所有版本。在提示符 (>) 处输入数字之一，然后按 Enter。