rbenv 入门：轻量级 Ruby 版本管理完全指南
rbenv 用 shim 机制轻量管理多个 Ruby 版本。本文讲解 rbenv 安装、工作原理、版本安装与切换、gem 管理和 Bundler 协作，附常见问题排查。
rbenv 是最轻量的 Ruby 版本管理器：通过在 PATH 前插入 shims 垫片目录拦截 ruby 命令，按当前目录的 .ruby-version 转发到对应版本。安装 rbenv + ruby-build 后，rbenv install 3.3.0 装版本、rbenv local 锁定项目版本，全程不污染 Shell 环境。
为什么需要 rbenv
多项目并行时版本冲突是常态：老应用跑 Ruby 2.7，新项目要用 3.3 的新特性。rbenv 的解法极尽克制——不改 Shell 函数、不改 cd 钩子，只在 PATH 最前面放一层 shim。这种"用完即隐身"的设计让它十余年如一日地稳定。
安装 rbenv 与 ruby-build
macOS（Homebrew）：
brew install rbenv ruby-build
rbenv init # 按提示把 eval "$(rbenv init - zsh)" 加入 ~/.zshrc
Ubuntu/Debian 则用 git 方式安装两个仓库，或直接用发行版包管理器。重开终端后 rbenv versions 有输出即就绪。
工作原理：shim 机制
理解 shim 就理解了 rbenv 的一切：
rbenv init把~/.rbenv/shims放到 PATH 最前；- 执行
ruby时实际运行的是 shim 脚本； - shim 依次检查
RBENV_VERSION环境变量 → 当前目录向上的.ruby-version文件 → 全局~/.rbenv/version，确定目标版本； - 转发到
~/.rbenv/versions/<版本>/bin/ruby。
装了新的带可执行文件的 gem 后 shim 需要刷新：rbenv rehash（有 rbenv-gem-rehash 插件可自动完成）。
安装与切换 Ruby 版本
rbenv install -l # 列出可安装版本
rbenv install 3.3.0 # 编译安装（首次较慢）
rbenv versions # 查看已装版本
rbenv global 3.3.0 # 全局默认
rbenv local 3.2.2 # 当前项目（写入 .ruby-version）
rbenv shell 3.1.4 # 仅当前终端
把 .ruby-version 提交进 Git，团队成员 rbenv install 即可对齐环境。编译失败通常是缺依赖：macOS 装 openssl@3 readline libyaml，Ubuntu 装 build-essential libssl-dev libreadline-dev libyaml-dev。
gem 与 Bundler 的协作
每个 Ruby 版本的 gem 独立存放在 ~/.rbenv/versions/<版本>/lib/ruby/gems/ 下，切换版本即切换 gem 集，互不污染。项目级依赖交给 Bundler：
gem install bundler
bundle install
bundle exec rails server
bundle exec 确保使用的是 Gemfile.lock 锁定的 gem 版本——rbenv 管 Ruby 版本，Bundler 管 gem 版本，两者分工明确，永远不要 sudo gem install。
常见问题（FAQ）
Q：ruby -v 显示的还是系统版本怎么办？
九成是 shim 没进 PATH：检查 ~/.zshrc 里是否有 eval "$(rbenv init - zsh)"，重开终端；用 which ruby 确认指向 ~/.rbenv/shims/ruby。
Q：rbenv、RVM、asdf 怎么选？
rbenv 轻量专注只做 Ruby；RVM 功能多但侵入 Shell 较深；asdf/Mise 管多语言。只用 Ruby 选 rbenv 最省心，多语言栈选 Mise（asdf 的现代替代）。
Q：升级 rbenv 后 ruby-build 找不到新版本？
ruby-build 的版本列表随自身更新：brew upgrade ruby-build，或 git 安装的在 ~/.rbenv/plugins/ruby-build 里 git pull。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
