MacOS Ruby 依赖问题根源在于系统 Ruby 受 SIP 保护、Homebrew Ruby 未激活或 Gemfile 版本约束过严；需理清 Ruby 运行时、Gem 源、Bundler 三层关系，推荐用 rbenv 管理版本并严格通过 bundle install 还原依赖。
MacOS 上 Ruby 的 Gem 依赖缺失和版本锁定问题，根源常在于系统 Ruby 被保护、Homebrew 安装的 Ruby 环境未正确激活，或 Gemfile 中版本约束过严导致解析失败。解决关键不是强行覆盖，而是理清 Ruby 运行时、Gem 源、Bundler 作用域三层关系。
确认当前 Ruby 和 Gem 实际归属
macOS 自带 Ruby（/usr/bin/ruby）被 SIP 保护，不可写入 gem，也不建议修改。运行以下命令检查真实环境：
-
which ruby—— 若输出/usr/bin/ruby，说明没切换到用户管理的 Ruby（如 rbenv/rvm/Homebrew） -
ruby -v && gem env home—— 查看 Ruby 版本和 gem 安装路径，二者应同属一个 Ruby 管理器 -
bundle -v—— Bundler 是否与当前 Ruby 绑定？若报错“command not found”，说明未用gem install bundler在当前 Ruby 下安装
用 rbenv 或 chruby 管理 Ruby 版本（推荐 rbenv）
避免 rvm 的全局 hook 和权限干扰，rbenv 更轻量透明：
- 用 Homebrew 安装：
brew install rbenv ruby-build - 初始化 shell（zsh 用户加到
~/.zshrc）：echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc && source ~/.zshrc - 安装指定 Ruby 版本：
rbenv install 3.2.2 && rbenv global 3.2.2 - 验证：
ruby -v应显示 3.2.2，且which ruby指向~/.rbenv/shims/ruby
修复 Gem 依赖缺失：从 Bundler 入手
不要直接 gem install xxx 全局安装，尤其当项目含 Gemfile 时：
- 进入项目目录后，先执行
rbenv local 3.2.2（确保 Ruby 版本与Gemfile.lock兼容） - 运行
bundle install—— Bundler 会按Gemfile.lock精确还原依赖树，自动处理嵌套版本冲突 - 若提示 “Could not find gem 'xxx' in any of the gem sources”，检查
source声明是否可用（如国内用户需设淘宝源：bundle config set --local mirror.https://rubygems.org https://ruby.taobao.org） - 若卡在某个 native extension 编译失败（如
nokogiri），先装 Xcode Command Line Tools：xcode-select --install，再重试
应对版本锁定冲突：读懂 Gemfile.lock 与悲观锁
版本锁定不是 bug，是保证可重现的关键。遇到 bundle update 失败或 bundle install 报版本不满足，按此排查：
- 打开
Gemfile.lock，查看报错 gem 的实际解析版本（如nokogiri (1.15.4)），再对照Gemfile中声明（如gem 'nokogiri', '~> 1.14'）——~>是悲观锁，1.15.4 不满足 1.14.x 范围，需放宽或降级 - 临时调试可运行
BUNDLE_IGNORE_CONFIG=1 bundle install --full-index忽略本地镜像配置，排除源同步问题 - 升级单个 gem 并更新 lock 文件：
bundle update nokogiri（注意：这会连带升级其传递依赖，可能引发新冲突） - 彻底重置依赖（慎用）：
rm Gemfile.lock && bundle install，但必须确认团队协作中 lock 文件变更已沟通
不复杂但容易忽略：MacOS 上 Ruby 环境问题 80% 出在「你以为在用 rbenv 的 Ruby，其实终端仍走系统路径」。每次新开 Terminal 后，务必用 which ruby 和 rbenv version 双重确认。
