在 devenv 中配置声明式 Ruby 开发环境:version、versionFile 与完整选项指南
在 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,示例truebundler.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 版本编译”:
对应的 gem 声明文件是 src/modules/lib/ruby-lsp/Gemfile(内容仅一行:lspEnv = pkgs.bundlerEnv { name = "solargraph-lsp"; ruby = cfg.package; gemdir = ../lib/ruby-lsp; };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 版本、依赖管理工具、语言服务器与文档支持,并将这套环境与项目一起版本化,实现真正可复现的开发体验。