在 devenv 中配置声明式 Ruby 开发环境:version、versionFile 与完整选项指南

原创2026-09-27 19:37:141,929 阅读
文章标签:开发工具CLI

在 devenv 中配置声明式 Ruby 开发环境:version、versionFile 与完整选项指南

导读

languages.ruby 是 devenv 提供的 Ruby 语言支持模块,它让你通过 Nix 声明式地定义 Ruby 版本、Bundler、Solargraph LSP 与文档支持,并在进入 shell 时自动注入 RUBYLIB、GEM_HOME、GEM_PATH 等环境变量。本文以 devenv 官方文档(docs/src/content/docs/languages/ruby.md)为主体,结合模块源码(src/modules/languages/ruby.nix)与仓库内的示例、测试用例,逐项讲解全部配置选项及底层实现。读完本文,你将能快速搭建一个可复现的 Ruby 开发环境,并理解固定 Ruby 版本、从 .ruby-version 读取版本等机制的工作原理。

快速开始:添加 nixpkgs-ruby 输入

要使用 languages.ruby.version 或 languages.ruby.versionFile 固定 Ruby 版本,首先需要在 devenv 配置中注册 nixpkgs-ruby flake 输入:

devenv inputs add nixpkgs-ruby github:bobvanderlinden/nixpkgs-ruby --follows nixpkgs

该命令会向 devenv.yaml 写入如下输入声明(与仓库测试用例 tests/ruby-documentation/devenv.yaml 中的写法一致):

inputs:
  nixpkgs-ruby:
    url: github:bobvanderlinden/nixpkgs-ruby
    inputs:
      nixpkgs:
        follows: nixpkgs

--follows nixpkgs 表示让 nixpkgs-ruby 内部的 nixpkgs 跟随当前项目的 nixpkgs,避免引入两套互不匹配的 nixpkgs,保证 ruby-3.2.1 这类带版本号的包能稳定解析。从源码看,模块通过 src/modules/languages/ruby.nix 中的 config.lib.getInput 按名称 nixpkgs-ruby、URL github:bobvanderlinden/nixpkgs-ruby 拉取该输入,因此省略这一步直接配置 version 会解析失败。

如果你只需要 nixpkgs 自带的默认 Ruby(pkgs.ruby),则不需要添加该输入,直接配置 languages.ruby.enable = true 即可。

配置选项总览

languages.ruby 模块的全部选项及其类型、默认值如下表所示:

选项 类型 默认值 作用
languages.ruby.enable boolean false 是否启用 Ruby 开发工具
languages.ruby.package package pkgs.ruby 使用的 Ruby 包
languages.ruby.version null 或 string null 通过 nixpkgs-ruby 固定 Ruby 版本
languages.ruby.versionFile null 或 path null 从 .ruby-version 文件读取版本
languages.ruby.bundler.enable boolean false(启用 ruby 后默认 true) 是否启用 Bundler
languages.ruby.bundler.package package pkgs.bundler.override { ruby = cfg.package; } 使用的 Bundler 包
languages.ruby.documentation.enable boolean false 是否启用 Ruby 包文档支持(rdoc/ri)
languages.ruby.lsp.enable boolean true 是否启用 Ruby 语言服务器(Solargraph)
languages.ruby.lsp.package package pkgs.solargraph.override { ruby = cfg.package; } 使用的语言服务器包

各选项的完整声明位于 src/modules/languages/ruby.nix。下面逐一展开说明。

languages.ruby.enable:总开关

  • 类型:boolean
  • 默认值:false
  • 示例:true

启用后模块会向环境注入 Ruby 工具链,并自动开启 C 工具链(languages.c.enable = lib.mkDefault true,见 src/modules/languages/ruby.nix),这是因为 Ruby 的 native extension(如 nokogiri、pg)编译需要 C 编译器与头文件。如果确定不编译原生扩展,可在自己的配置中显式关闭:

languages.c.enable = false;

languages.ruby.package:底层 Ruby 包

  • 类型:package
  • 默认值:pkgs.ruby

默认使用 nixpkgs 中的 pkgs.ruby。绝大多数情况下你不需要直接改它——version 与 versionFile 会自动覆写 package。直接指定 package 适合固定 nixpkgs 本身版本即可满足需求的场景。

languages.ruby.version:固定 Ruby 版本

  • 类型:null 或 string
  • 默认值:null
  • 示例:"3.2.1"

指定形如 "3.2.1" 的版本号后,模块会自动把 languages.ruby.package 解析为 nixpkgs-ruby 中对应的 ruby-${version} 包:

{
  languages.ruby.enable = true;
  languages.ruby.version = "3.4.7";
}

从源码看,实际解析逻辑为 src/modules/languages/ruby.nix:

nixpkgs-ruby.packages.${pkgs.stdenv.system}."ruby-${cfg.version}".override {
  docSupport = cfg.documentation.enable;
};

即:按当前系统平台取 ruby-3.4.7 包,并依据 documentation.enable 决定是否构建文档支持。仓库测试 tests/ruby-documentation/devenv.nix 正是用 version = "3.4.7" 配合 documentation.enable = true 来验证 ri 文档可用的。

languages.ruby.versionFile:从 .ruby-version 读取版本

  • 类型:null 或绝对路径(path)
  • 默认值:null
  • 示例:./.ruby-version

如果你的项目已经使用 rbenv / ruby-build 约定,即项目根目录存在 .ruby-version 文件(内容例如 3.2.1),可以让 devenv 直接读取它,实现与现有 Ruby 版本管理工具的无缝衔接。文档给出的用法是:

languages.ruby.versionFile = ./.ruby-version;

这要求 .ruby-version 与 devenv 配置文件位于同一目录。源码中的解析逻辑为 src/modules/languages/ruby.nix:

(nixpkgs-ruby.lib.packageFromRubyVersionFile {
  file = cfg.versionFile;
  system = pkgs.stdenv.system;
}).override { docSupport = cfg.documentation.enable; };

仓库示例 examples/ruby/devenv.nix 展示了这一典型用法:

{ pkgs, lib, ... }:

{
  languages.ruby.enable = true;

  # Use a specific Ruby version.
  # languages.ruby.version = "3.4";

  # Use a specific Ruby version from a .ruby-version file, compatible with rbenv.
  languages.ruby.versionFile = ./.ruby-version;
}

互斥约束:version 与 versionFile 不能同时设置。模块在启用 ruby 时注册了一条断言(src/modules/languages/ruby.nix),若二者都非空会直接报错并提示“Only one of the two may be set. Remove one of the two options.”。

languages.ruby.bundler:Bundler 支持

  • bundler.enable:类型 boolean,默认 false,示例 true
  • bundler.package:类型 package,默认 pkgs.bundler.override { ruby = cfg.package; }

Bundler 的默认包通过对当前 Ruby 包执行 override 生成,确保 bundler 与所选 Ruby 版本严格配套。值得注意的是,虽然选项本身的默认值是 false,但模块在 languages.ruby.enable = true 时会将 bundler.enable 通过 lib.mkDefault 提升为 true(src/modules/languages/ruby.nix),因此只要启用了 Ruby,Bundler 默认就是可用的,无需额外配置。

启用后,bundler 命令会进入 PATH;bundle install 安装的 gem 会被写入项目状态目录,而不是散落到全局,详见下文“环境变量注入”。

languages.ruby.documentation:RDoc 文档支持

  • 类型:boolean
  • 默认值:false
  • 示例:true

开启后,构建 Ruby 包时会同时生成 RDoc 文档,使 ri 命令可用于查询标准库与 gem 文档。它的值会被传入上面 version / versionFile 的包解析逻辑中的 docSupport 参数。仓库测试 tests/ruby-documentation/devenv.nix 的验证方式是在 enterTest 中执行 ri Object >/dev/null,确认文档确实可查询。

languages.ruby.lsp:Solargraph 语言服务器

  • lsp.enable:类型 boolean,默认 true(这是模块中少数默认开启的选项之一)
  • lsp.package:类型 package,默认 pkgs.solargraph.override { ruby = cfg.package; }

LSP 默认启用,使 devenv 开箱即可为 Ruby 项目提供补全、跳转等编辑体验。LSP 包的构建方式与是否使用自定义 Ruby 版本密切相关,这是模块实现中较精细的部分:

  • 使用自定义版本(version 或 versionFile 任一非空)时,LSP 通过 bundlerEnv 以当前 Ruby 构建 Solargraph(src/modules/languages/ruby.nix),源码注释明确指出这样做的原因是“确保 native extensions 针对正确的 Ruby 版本编译”:
    lspEnv = pkgs.bundlerEnv {
      name = "solargraph-lsp";
      ruby = cfg.package;
      gemdir = ../lib/ruby-lsp;
    };
    
    对应的 gem 声明文件是 src/modules/lib/ruby-lsp/Gemfile(内容仅一行:gem 'solargraph')。
  • 使用默认 Ruby 时,直接使用 nixpkgs 预构建的 solargraph,并经过 wrapGemBin 包装(src/modules/languages/ruby.nix):只将 bin/ 下的可执行文件软链进环境,不传播其 gem 依赖,避免 solargraph 自身的 gem 依赖污染用户的 GEM_PATH 造成版本冲突。

需要关闭 LSP 时:

languages.ruby.lsp.enable = false;

测试 tests/ruby-documentation/devenv.nix 中就是因为 solargraph 引入的 nokogiri 在 aarch64-darwin 上构建失败而显式关闭了 LSP,这是实战中遇到平台构建问题时的合理降级手段。

从源码看模块实现原理

包的自动解析与合并

languages.ruby.package 的最终取值由 lib.mkMerge 合并而来(src/modules/languages/ruby.nix):

  • 若 version 非空,取 nixpkgs-ruby.packages.<system>."ruby-<version>";
  • 若 versionFile 非空,调 nixpkgs-ruby.lib.packageFromRubyVersionFile;
  • 两者都为空时,mkMerge 中无有效分支,回落为选项默认值 pkgs.ruby。

这是 devenv 通过 config.lib.getInput 与 lib.mkIf / lib.mkMerge 实现“配置驱动包选择”的典型例子:同一选项的不同来源可以并存,由模块系统按优先级合并。

环境变量注入

当 languages.ruby.enable = true 时,模块在 src/modules/languages/ruby.nix 中设置两组配置:

持久化环境变量:

env.BUNDLE_PATH = config.env.DEVENV_STATE + "/.bundle";
env.GEM_HOME = "${config.env.BUNDLE_PATH}/${cfg.package.rubyEngine}/${cfg.package.version.libDir}";

即 Bundler 与 gem 的统一安装位置为 devenv 状态目录下的 .bundle,并按 rubyEngine(如 ruby)与版本对应的 libDir(如 lib/ruby/3.4.0)分层,避免不同 Ruby 版本间的 gem 互相污染。

进入 shell 时的运行时导出(enterShell):

export RUBYLIB="$DEVENV_PROFILE/${libdir}:$DEVENV_PROFILE/lib/ruby/site_ruby:$DEVENV_PROFILE/lib/ruby/site_ruby/${libdir}:$DEVENV_PROFILE/lib/ruby/site_ruby/${libdir}/${pkgs.stdenv.system}:${RUBYLIB:-}"
export GEM_PATH="$GEM_HOME/gems:${GEM_PATH:-}"
export PATH="$GEM_HOME/bin:$PATH"

RUBYLIB 将 devenv profile 中 Ruby 的标准库与 site_ruby 目录挂载到加载路径(按架构区分平台特定目录),GEM_PATH 把 $GEM_HOME/gems 置于最前,PATH 加入 $GEM_HOME/bin,使 bundle install 出来的 gem 可执行文件立即可用。

加入环境的具体包集合

最终写入环境的 packages(src/modules/languages/ruby.nix)为:

packages = lib.optional cfg.bundler.enable cfg.bundler.package ++ [
  cfg.package
] ++ lib.optional cfg.lsp.enable lspPackage;

即:Ruby 本体 +(按需)Bundler +(按需,默认开启)LSP,三者都锚定在同一个 cfg.package 之上,保证版本一致性。

完整可运行示例

结合仓库示例 examples/ruby/devenv.nix,一个贴近真实项目的完整配置如下:

{ pkgs, lib, ... }:

{
  # 1. 启用 Ruby 工具链
  languages.ruby.enable = true;

  # 2. 方式一:固定具体版本(也可用 versionFile 从 .ruby-version 读取)
  # languages.ruby.version = "3.4";

  # 3. 开启 RDoc 文档支持(需在 devenv.yaml 中注册 nixpkgs-ruby 输入)
  # languages.ruby.documentation.enable = true;

  # 4. 若不需要编译 native extension,可显式关闭默认开启的 C 工具链
  # languages.c.enable = false;

  # 5. 进入 shell 时自动执行 bundler(会安装 Gemfile 中的依赖)
  enterShell = ''
    bundle
  '';

  # 6. 额外打包系统依赖
  packages = [
    pkgs.libyaml
  ]
  # macOS 下通常由 Xcode 命令行工具提供这些依赖;若缺失则需显式加入
  ++ lib.optionals pkgs.stdenv.hostPlatform.isDarwin [ pkgs.libllvm ];
}

配合 devenv.yaml 中的输入声明:

inputs:
  nixpkgs-ruby:
    url: github:bobvanderlinden/nixpkgs-ruby
    inputs:
      nixpkgs:
        follows: nixpkgs

运行 devenv shell(或 devenv up / direnv 自动加载)后,即可得到固定版本的 Ruby + Bundler + Solargraph 环境。每次进入 shell,enterShell 中的 bundle 会自动同步 Gemfile 依赖;若已存在 Gemfile,这等效于在每次进入环境时执行 bundle install。

测试用例与验证

仓库中的 tests/ruby-documentation 是针对本模块的回归测试目录,包含:

  • devenv.yaml:声明 nixpkgs-ruby 输入并 follows nixpkgs;
  • devenv.nix:配置 enable = true、version = "3.4.7"、documentation.enable = true、lsp.enable = false,并通过 enterTest 执行 ri Object >/dev/null 验证文档可用。

这个测试至少印证了三点:固定版本解析(version)能正常构建;documentation.enable 会真实生成 RDoc;以及 LSP 可在特定平台(如 aarch64-darwin 上 nokogiri 构建失败)被显式关闭而不影响其他能力。

常见问题与注意事项

  • 忘记注册 nixpkgs-ruby 输入:配置了 version / versionFile 却未执行 devenv inputs add nixpkgs-ruby github:bobvanderlinden/nixpkgs-ruby --follows nixpkgs,模块在 getInput 阶段会解析失败。
  • version 与 versionFile 同时设置:会触发模块断言错误,两者只能保留其一。
  • native extension 编译失败:先确认未关闭 C 工具链(languages.c.enable 默认随 ruby 开启);在 macOS 上还需补齐 Xcode 命令行工具或按示例显式加入 pkgs.libllvm。
  • LSP 与 gem 依赖冲突:默认 Ruby 场景下模块已通过 wrapGemBin 隔离 solargraph 的 gem 依赖;自定义版本场景下则通过 bundlerEnv 针对当前 Ruby 重新构建。若仍遇到平台构建问题(如 nokogiri),可临时 languages.ruby.lsp.enable = false。
  • gem 安装位置:所有 gem 统一写入 devenv 状态目录(DEVENV_STATE)下的 .bundle,跨项目隔离且不依赖全局 ~/.gem,也保证了可复现性。

通过以上配置,你可以在 devenv 中完全用声明式方式管理 Ruby 版本、依赖管理工具、语言服务器与文档支持,并将这套环境与项目一起版本化,实现真正可复现的开发体验。

登录后查看全文
devenv