应使用 rbenv 管理 Ruby 版本并用 bundle install 还原依赖，避免系统自带 /usr/bin/ruby；需验证 which ruby、ruby -v 和 gem env home 路径一致且指向用户可写目录，确保 rbenv 初始化生效。
别用系统自带的 /usr/bin/ruby，它被 SIP 保护、版本老旧、无法写入 gem，所有依赖问题都源于此；正确做法是用 rbenv 管理 Ruby 版本，并始终通过 bundle install 还原项目依赖。
确认当前 Ruby 是不是系统自带的
先看真实环境归属，避免盲目重装：
-
which ruby—— 若输出/usr/bin/ruby，说明你正在用系统 Ruby，必须切换 -
ruby -v && gem env home—— 两者路径应一致且指向用户可写目录（如~/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0），否则 gem 安装会失败或错位 -
bundle -v—— 若报command not found，说明bundler没在当前 Ruby 下安装，不能靠全局gem install bundler补救
用 rbenv 安装并激活新版 Ruby
rbenv 比 rvm 更轻量、无 hook 干扰，适合多数项目场景：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用 Homebrew 安装：
brew install rbenv ruby-build - 初始化 shell（zsh 用户）：
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc && source ~/.zshrc - 安装指定版本（如 3.2.2）：
rbenv install 3.2.2（需先装 Xcode Command Line Tools：xcode-select --install） - 设为全局默认：
rbenv global 3.2.2，再验证：ruby -v应输出ruby 3.2.2，which ruby应指向~/.rbenv/shims/ruby
修复 Gem 依赖缺失：只认 bundle install
项目里有 Gemfile 就别碰 gem install —— 全局安装会绕过锁文件，引发版本错乱：
- 进项目目录后，先执行
rbenv local 3.2.2（确保 Ruby 版本与Gemfile.lock兼容） - 运行
bundle install—— 它会按Gemfile.lock精确还原，自动处理嵌套冲突 - 若报
Could not find gem 'xxx'，检查Gemfile中的source是否可用；国内用户建议加：bundle config set --local mirror.https://rubygems.org https://ruby.taobao.org - 若卡在 native extension（如
nokogiri编译失败），先确认已装 Xcode CLT，再重试；必要时加编译参数：bundle config build.nokogiri --use-system-libraries
理解 Gemfile.lock 和悲观锁的实际影响
版本锁定不是障碍，而是可重现性的保障；出错时别急着 bundle update：
- 打开
Gemfile.lock，找到报错 gem 的实际解析版本（如nokogiri (1.15.4)） - 对照
Gemfile中声明（如gem 'nokogiri', '~> 1.14'）——~>表示允许1.14.x，但不包括1.15.0及以上 - 若需升级，明确指定范围：
gem 'nokogiri', '~> 1.15'，再bundle update nokogiri，避免全量更新破坏其他依赖 - 修改
Gemfile后务必提交更新后的Gemfile.lock，否则协作时别人bundle install会失败
最常被忽略的一点：rbenv 的 shims 机制依赖 shell 初始化完整生效；如果 which ruby 显示路径不对，大概率是 source ~/.zshrc 没执行，或终端没重启。别跳过这步，它比重装 Ruby 耗时更少、效果更准。
