macos 上用 rbenv 管理 ruby 的核心是绕开系统 ruby、建立用户级可切换环境；需先用 homebrew 安装 rbenv 和 ruby-build，正确初始化 shell（如写入 ~/.zshrc 并 source），再通过 ruby-build 编译安装指定版本（如 3.4.2），设为 global 或 local，默认调用 ~/.rbenv/shims/ruby；项目中必须用 bundle install 而非 gem install，确保依赖与 gemfile.lock 一致。
macos 上用 rbenv 管理 ruby，核心不是“装个工具就完事”，而是绕开系统 ruby（/usr/bin/ruby），建立用户级、可切换、受控的 ruby 运行时。它不碰 sip 保护区域，不污染系统，也避免 xcode 打包时误调旧版本导致构建失败。
rbenv 安装与 shell 初始化必须到位
rbenv 不是装完命令就能用——初始化没写进 shell 配置，终端里 which ruby 依然指向 /usr/bin/ruby。
- 用 Homebrew 安装：运行
brew install rbenv ruby-build - 执行
rbenv init -zsh，把输出的eval "$(rbenv init -zsh)"行粘贴到~/.zshrc末尾 - 运行
source ~/.zshrc生效；验证rbenv命令可用，且rbenv version不报错（初始为空）
安装 Ruby 版本要靠 ruby-build 编译
rbenv 本身不提供 Ruby，靠 ruby-build 插件下载源码并编译安装。Apple Silicon（M1/M2/M3/M4）无需额外参数，现代 Ruby（≥3.1）已原生支持 ARM 架构。
- 先确保 Xcode 命令行工具已装：
xcode-select --install - 查最新稳定版：
rbenv install -l | grep "^[0-9]" | tail -5（例如3.4.2） - 安装：
rbenv install 3.4.2（首次可能需几分钟） - 设为全局默认：
rbenv global 3.4.2 - 验证：
ruby -v和which ruby都应显示~/.rbenv/shims/ruby
项目级 Ruby 版本锁定更安全
不同项目常依赖不同 Ruby 版本。全局设置不够细粒度，容易出错。推荐在项目根目录执行：
cd my-project-
rbenv local 3.4.2（自动创建.ruby-version文件） - 进入该目录后，rbenv 自动切换到指定版本，
ruby -v即可见效 - 配合
Gemfile.lock中声明的RUBY VERSION校验兼容性，再运行bundle install
依赖管理必须走 bundle install
有 Gemfile 的项目，绝不能用 gem install xxx 全局安装。这会跳过锁文件，引发本地与 CI 环境不一致、版本漂移、甚至打包失败。
-
bundle install严格按Gemfile.lock还原依赖树，处理嵌套冲突 - 国内用户可加速：
bundle config set --local mirror.https://rubygems.org https://ruby.taobao.org - 遇到 native extension 编译失败（如
nokogiri）：bundle config build.nokogiri --use-system-libraries
