需用 rbenv 管理 macOS 多 Ruby 版本，推荐 Homebrew 安装 rbenv 和 ruby-build，配置 shell 初始化，再安装指定版本并设全局或项目级默认，最后排查 shell 集成问题。
如果您希望在 macOS 上灵活切换多个 Ruby 版本，避免系统 Ruby 被污染或项目间版本冲突，则需借助 rbenv 这类版本管理工具。以下是针对 macOS 系统的完整安装与配置操作流程：
一、使用 Homebrew 安装 rbenv 及 ruby-build 插件
Homebrew 是 macOS 上最主流的包管理器，通过它安装 rbenv 和配套插件最为稳定高效。该方式自动处理依赖并适配 Apple Silicon 与 Intel 架构。
1、确保已安装 Homebrew：在终端中执行 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"，按提示完成安装。
2、运行命令安装 rbenv 和 ruby-build：brew install rbenv ruby-build。
3、初始化 rbenv 并写入 shell 配置文件：执行 rbenv init - zsh（若使用 Zsh，默认 shell），复制输出中类似 eval "$(rbenv init - zsh)" 的行，粘贴至 ~/.zshrc 文件末尾。
4、重新加载配置：source ~/.zshrc。
二、通过 Git 克隆手动安装 rbenv
当无法使用 Homebrew（如受限环境或需最新开发版）时，可直接从 GitHub 源码安装。此方式完全可控，不依赖第三方包管理器。
1、克隆仓库到用户主目录：git clone https://github.com/rbenv/rbenv.git ~/.rbenv。
2、将 rbenv 可执行路径加入 PATH：echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc（Zsh 用户）或 echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile（Bash 用户）。
3、启用 rbenv 初始化脚本：echo 'eval "$(~/.rbenv/bin/rbenv init - zsh)"' >> ~/.zshrc。
4、安装 ruby-build 插件以支持 Ruby 编译安装：git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build。
5、重新加载 shell 配置：source ~/.zshrc。
三、安装指定 Ruby 版本并设为全局默认
rbenv 本身不提供 Ruby 编译能力，需依赖 ruby-build 插件下载源码并构建。安装后版本将存于 ~/.rbenv/versions/ 目录下，供后续调用。
1、列出所有可安装版本：rbenv install -l。
2、选择一个稳定版本安装（例如 3.1.4）：rbenv install 3.1.4（首次安装可能耗时数分钟，需确保已安装 Xcode Command Line Tools）。
3、设置为系统全局默认版本：rbenv global 3.1.4。
4、验证是否生效：ruby -v 应输出 ruby 3.1.4p223 类似内容。
四、为单个项目配置独立 Ruby 版本
项目级版本控制是 rbenv 的核心优势之一。通过在项目根目录生成 .ruby-version 文件，rbenv 可在进入该目录时自动切换 Ruby 解释器，无需手动干预。
1、进入目标项目目录：cd /path/to/your/project。
2、设定本地 Ruby 版本（例如 2.7.8）：rbenv local 2.7.8。
3、确认当前目录已生成 .ruby-version 文件：cat .ruby-version 应显示 2.7.8。
4、退出并重新进入该目录，执行 ruby -v，验证版本已切换。
五、修复常见 Shell 集成失效问题
rbenv 命令不可用或版本不切换，通常源于 shell 初始化未正确加载。该问题多见于终端重启后未生效、Zsh 与 Bash 混用、或配置文件路径错误等情况。
1、检查当前 shell 类型：echo $SHELL，确认是 /bin/zsh 还是 /bin/bash。
2、确认 rbenv init 输出的 eval 行已写入对应配置文件：cat ~/.zshrc | grep rbenv 或 cat ~/.bash_profile | grep rbenv。
3、若存在多行重复的 eval 初始化，仅保留一行，并删除其他冗余行。
4、强制重载配置并测试：source ~/.zshrc && rbenv version，应返回当前有效版本而非 “system”。
