setup-ruby：实践指南

在项目中评估setup-ruby，可以先看清用途边界：下载预构建的 Ruby 并将其在 5 秒内添加到 PATH 的操作。从日常自动化的使用方式看，输入边界、依赖和失败处理如果不清楚就很难稳定复用是采用前必须回答的问题。我建议用一项范围明确的真实任务完成最小试跑，重点记录配置时间、输出质量、异常信息和维护痕迹，再与现有方案比较。编辑判断上，愿意先做小范围验证并复查原始文档的团队可以优先研究它；其他团队不必为了热门标签勉强接入。

安装红宝石

此操作会下载预构建的 ruby 并将其添加到 PATH。

它非常高效，大约需要 5 秒的时间来下载、提取并将给定的 Ruby 添加到 PATH。 无需安装额外的软件包。

重要提示：优先选择 ruby/setup-ruby@v1。 如果您固定到提交或发布，则只有提交时可用的 Ruby 版本 将可用，并且您需要更新它以使用较新的 Ruby 版本，请参阅 版本控制。

支持的版本

此操作目前支持以下版本的 MRI、JRuby 和 TruffleRuby：

口译员	版本
ruby	1.9.3、2.0.0、2.1.9、2.2、从 2.3.0 到 4.0.6 的所有版本、head、debug、mingw、mswin、ucrt
jruby	9.1.17.0 - 10.1.1.0，头
truffleruby	19.3.0 - 34.0.1，头
truffleruby+graalvm	21.2.0 - 34.0.1，头

ruby-debug 与 ruby-head 相同，但启用了断言 (-DRUBY_DEBUG=1)。

ruby-asan 与 ruby-head 相同，但启用了 AddressSanitizer (ASan)，有助于查找本机扩展中的内存问题。 使用 ruby-asan 时，本机扩展会自动使用 AddressSanitizer 进行编译。 ruby-asan 目前仅在 ubuntu-24.04 上可用。

asan-release 与 ruby-asan 类似，但由最新的稳定版本标签构建。 与ruby-asan一样，目前仅在ubuntu-24.04上可用。

关于 Windows ruby 主版本，mingw 是 MSYS2/MinGW 版本，head 和 ucrt 是 MSYS2/UCRT64 版本，mswin 是 MSVC/VS 2022 版本。

Ruby 的预览版和 RC 版本也可能在 Ubuntu 和 macOS 上提供（不适用于 Windows）。 但是，建议针对 ruby-head 进行测试，而不是预览， 因为它为 Ruby 核心团队和即将发生的更改提供了更有用的反馈。

仅发布 RubyInstaller 发布的版本 在 Windows 上可用。 因此，Ruby 2.2 在 Windows 上解析为 2.2.6，在 Windows 上解析为 2.2.10 在其他平台上。 Windows 上的 Ruby 2.3 仅具有 2.3.0、2.3.1 和 2.3.3 的版本。

请注意，Ruby ≤ 2.4 及其所需的 OpenSSL 版本 (1.0.2) 均已终止生命周期， 这意味着 Ruby ≤ 2.4 未维护并且被认为是不安全的。

支持的平台

该操作适用于这些 GitHub-hosted 跑步者 图像。尚不支持下面未列出的跑步者图像。 $OS-latest 只是这些图像之一的别名。

操作系统	支持
乌班图	ubuntu-22.04, ubuntu-24.04, ubuntu-26.04, ubuntu-22.04-arm, ubuntu-24.04-arm, ubuntu-26.04-arm
macOS	macos-14 及更新版本
窗户	windows-2022, windows-2025, windows-11-arm

并非所有运行程序图像和版本的组合都受支持。 可用的 Ruby 版本列表可以在 ruby-builder-versions.json for Ubuntu 和 macOS 中查看 （虽然有些组合不可用，请参阅 完整列表） 以及在 windows-versions.json for Windows 中。

预构建版本由 ruby-builder 生成 Windows 上为 RubyInstaller2。 mingw、ucrt 和 mswin 版本由 ruby-loco 生成。 ruby-head 由 ruby-dev-builder 生成， jruby-head 由 jruby-dev-builder 生成， truffleruby-head 和 truffleruby+graalvm-head 由 truffleruby-dev-builder 生成。

用途

单一工作

name: My workflow
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: ruby/setup-ruby@v1
      with:
        ruby-version: '4.0' # Not needed with a .ruby-version, .tool-versions or mise.toml
        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
    - run: bundle exec rake

Ruby 版本矩阵

该矩阵测试 Ubuntu 和 macOS 上的 MRI、JRuby 和 TruffleRuby 的所有稳定版本和 head 版本。

name: My workflow
on: [push, pull_request]
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'
        ruby: ['3.3', '3.4', '4.0', head, jruby, jruby-head, truffleruby, truffleruby-head]
    runs-on: ${{ matrix.os }}
    steps:
    - uses: actions/checkout@v6
    - uses: ruby/setup-ruby@v1
      with:
        ruby-version: ${{ matrix.ruby }}
        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
    - run: bundle exec rake

Gemfiles 矩阵

name: My workflow
on: [push, pull_request]
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        gemfile: [ rails7, rails8 ]
    runs-on: ubuntu-latest
    env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
    steps:
      - uses: actions/checkout@v6
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '4.0'
          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
      - run: bundle exec rake

有关更多详细信息，请参阅 GitHub 操作文档 工作流语法 以及 条件和表达式语法。

支持的版本语法

• 引擎版本，如 ruby-2.6.5 和 truffleruby-19.3.0
• 简短版本，如 '2.6'，自动使用与该版本匹配的最新版本 (2.6.10)
• 仅类似于 '2.6.5' 的版本，假设引擎为 MRI
• 仅像 ruby 和 truffleruby 那样的引擎，使用该实现的最新稳定版本
• .ruby-version 从项目的 .ruby-version 文件中读取
• .tool-versions 从项目的 .tool-versions 文件中读取
• mise.toml 从项目的 mise.toml 文件中读取
• 如果未指定 ruby-version 输入，则首先尝试 .ruby-version，然后是 .tool-versions，最后是 mise.toml

工作目录

working-directory 输入可设置为解析 .ruby-version、.tool-versions、mise.toml 和 Gemfile.lock 如果它们不在存储库的根目录中，请参阅 action.yml 了解详细信息。

RubyGems

默认情况下，使用每个 Ruby 附带的默认 RubyGems 版本。 但是，用户可以选择自定义他们想要的 RubyGems 版本 设置 rubygems 输入。

有关 rubygems 输入的更多详细信息，请参阅 action.yml。

如果您遇到“ArgumentError：参数数量错误（给定 4， 预期 1)堆栈跟踪错误包括 Psych 和 RubyGems 条目，您 应该能够通过设置rubygems: 3.0.0` 或更高版本来修复它们。

捆绑器

默认情况下，Bundler 安装如下：

• 如果存在带有 BUNDLED WITH 部分的 Gemfile.lock 文件（或 $BUNDLE_LOCKFILE、$BUNDLE_GEMFILE.lock 或 gems.locked）， 将安装并使用该版本的 Bundler。
• 如果 Ruby 附带 Bundler 2.2+（作为默认 gem），则使用该版本。
• 否则，将安装最新的兼容 Bundler 版本（Ruby >= 2.3 上的 Bundler 2，Ruby < 2.3 上的 Bundler 1）。

此行为可以自定义，有关 bundler 输入的更多详细信息，请参阅 action.yml。

自动缓存 bundle install

此操作提供了一种自动运行 bundle install 并缓存结果的方法：

    - uses: ruby/setup-ruby@v1
      with:
        bundler-cache: true

请注意，执行 bundle install（对于根 Gemfile）或 gem install bundler 的任何步骤都可以使用 bundler-cache: true 删除。

这种缓存显着加快了安装 gem 的速度，并避免了对 RubyGems.org 的过多请求。
它需要在working-directory下有一个Gemfile（或$BUNDLE_GEMFILE或gems.rb）。
如果存在 Gemfile.lock（或 $BUNDLE_LOCKFILE、$BUNDLE_GEMFILE.lock 或 gems.locked），则使用 bundle config --local deployment true。

要使用不在根目录或具有不同名称的 Gemfile，请在作业级别的 env 中设置 BUNDLE_GEMFILE 如 示例 所示。

捆绑配置

使用 bundler-cache: true 时，您可能会注意到没有合适的地方运行 bundle config ... 命令。 这些可以替换为 BUNDLE_* 环境变量，这也更快。 它们应在作业级别的 env 中设置，如 示例 中所示。 要查找正确的环境变量名称，请参阅 Bundler 文档 或在本地运行 bundle config --local KEY VALUE 后查看 .bundle/config。 如果 YAML 中的环境变量名称包含 / 等不常见字符，您可能需要在 "- 中引用该环境变量名称。

要执行缓存，此操作将使用 bundle config --local path $PWD/vendor/bundle。
因此，不应在工作流程中更改 Bundler path 以使缓存正常工作（无 bundle config path）。

它是如何运作的

当没有锁文件时，会使用 bundle lock 生成一个锁文件，这与 bundle install 在实际获取任何 gem 之前首先执行的操作相同。 换句话说，它的工作原理与 bundle install 完全相同。 然后将生成的锁定文件的哈希值用于缓存，这是唯一正确的方法。

处理损坏的缓存

在一些罕见的情况下（例如使用带有 C 扩展的 gem，其功能取决于系统上找到的库） 在构建 gem 时）可能需要忽略缓存的内容并重新获取并构建所有 gem。 为了实现此目的，请将 cache-version 选项设置为 0 以外的任何值（或将其更改为新的唯一值） 如果您之前已经使用过它。）

    - uses: ruby/setup-ruby@v1
      with:
        bundler-cache: true
        cache-version: 1

手动缓存 bundle install

也可以手动缓存 gem，但不建议这样做，因为它很冗长并且“非常困难”正确执行。 有很多问题意味着使用 actions/cache 永远不足以缓存 gem（e.g.、不完整的缓存密钥、从另一个密钥恢复时清理旧的 gem、如果未签入则正确散列锁定文件、OS 版本、ABI 对 ruby-head 的兼容性、等）。 因此，请改用 bundler-cache: true 并报告任何问题。

身份验证令牌

默认情况下，从 GitHub 下载 Ruby 发布资产时，此操作使用 ${{ github.token }} 进行身份验证。 这有助于避免速率限制问题。

如果您在 GitHub Enterprise Server (GHES) 实例上运行此操作，或者遇到速率限制， 您可以提供自定义令牌：

    - uses: ruby/setup-ruby@v1
      with:
        token: ${{ secrets.MY_GITHUB_TOKEN }}

在大多数情况下，您不需要设置此输入，因为默认值足以在 github.com 上使用。

窗户

请注意，如果您不太熟悉 Windows，那么在 Windows 上运行 CI 可能会非常具有挑战性。 建议在尝试 Windows 之前先让您的构建在 Ubuntu 和 macOS 上运行。

• 在 Windows 上使用 Bundler 2.2.18+（旧版本有 错误），方法是不设置 bundler: 输入并确保签入的 Gemfile.lock 中没有 BUNDLED WITH 1.x.y。
• Windows 上的默认 shell 不是 Bash，而是 PowerShell。 这可能会导致多行脚本 无法按预期 等问题。
• PATH 包含 多个编译器工具链。使用where.exe来调试使用哪个工具。
• 对于 Ruby ≥ 2.4，MSYS2 被添加到 Path 之前，类似于 RubyInstaller2 的做法。
• 对于 Ruby < 2.4，安装 DevKit MSYS 工具并将其添加到 Path 之前。
• 编译扩展代码时，请注意，使用 Windows 2022 时包含构建 Ruby 所需的软件包。可以使用 setup-ruby-pkgs 或通过 MSYS2 的 pacman 安装其他软件包。安装或更新 Ruby stdlib 扩展 gem 时可能需要这些包。

版本控制

强烈建议对此操作的版本使用 ruby/setup-ruby@v1。 这将通过自动获取错误修复、新的 Ruby 版本和新功能来提供最佳体验。

如果您选择特定版本 (v1.2.3) 或提交 sha，则不会自动修复错误，并且 每次该操作不再有效时，您都有责任进行更新。 在 GitHub 上报告问题之前，请确保始终使用最新版本。

此操作遵循移动 v1 分支的语义版本控制。 这遵循 GitHub 操作的 建议。

使用自托管运行器

此操作可能适用于 自托管运行器 如果 跑步者图像 与 GitHub 跑步者使用的图像非常相似。值得注意的是：

• 确保使用相同的操作系统和版本。
• 确保使用相同版本的 libssl。
• 确保操作系统已安装 libyaml-0 和 libgmp
• 默认工具缓存目录（Linux 上为 /opt/hostedtoolcache，/Users/runner/hostedtoolcache 上为 macOS， Windows 上的 C:/hostedtoolcache/windows）必须可由 runner 用户写入。 这是必要的，因为 Ruby 构建在构建时嵌入了安装路径并且无法移动。
• /home/runner 必须可由 runner 用户写入。

在其他情况下，您需要在运行程序工具缓存中安装 Ruby，如检测到这种情况时的操作所示 （运行它，它会告诉您安装 Ruby 的位置）。 您当然也可以不使用此操作和 e.g。使用系统包中的 Ruby 或使用 Docker 映像。

另请参见 self-hosted: 输入。 如果您想在自托管工具缓存中使用定制的 Rubies，而不是预构建的 Rubies，则可以将其设置为 true。

历史

此操作以前位于 eregon/use-ruby-action，现已移至 ruby 组织。 如果您正在使用eregon/use-ruby-action，请更新update。