第 02 章：安装与环境配置

“工欲善其事，必先利其器。” —— 《论语·卫灵公》

2.1 安装方式概览

Ruby 有多种安装方式，推荐使用版本管理器以便在不同项目间切换 Ruby 版本。

方式	优点	缺点	推荐度
rbenv	轻量、不侵入系统	需要额外安装 ruby-build	⭐⭐⭐⭐⭐
RVM	功能丰富、自带 gemset	较重、修改 shell 环境	⭐⭐⭐⭐
系统包管理	简单直接	版本通常较旧	⭐⭐
源码编译	最新版本	步骤繁琐	⭐⭐⭐
Docker	隔离性好	有 Docker 学习成本	⭐⭐⭐⭐

2.2 使用 rbenv 安装（推荐）

2.2.1 安装 rbenv 和 ruby-build

macOS (Homebrew)：

# 安装 rbenv 和 ruby-build
brew install rbenv ruby-build

# 初始化 shell（添加到 ~/.zshrc 或 ~/.bashrc）
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
rbenv --version

Ubuntu / Debian：

# 安装依赖
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev libreadline-dev \
  zlib1g-dev libyaml-dev libffi-dev

# 安装 rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

# 安装 ruby-build 插件
git clone https://github.com/rbenv/ruby-build.git \
  "$(rbenv root)/plugins/ruby-build"

Arch Linux：

sudo pacman -S rbenv ruby-build
echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

2.2.2 安装 Ruby

# 查看可用版本
rbenv install --list          # 列出所有版本
rbenv install --list-all      # 列出所有版本（含预发布）

# 安装最新稳定版
rbenv install 3.3.0

# 设置全局默认版本
rbenv global 3.3.0

# 为特定项目设置版本
cd my_project
rbenv local 3.3.0     # 创建 .ruby-version 文件

# 验证
ruby --version          # => ruby 3.3.0 ...
which ruby              # => ~/.rbenv/shims/ruby

2.2.3 rbenv 常用命令

命令	说明
`rbenv install <version>`	安装指定版本 Ruby
`rbenv uninstall <version>`	卸载指定版本
`rbenv versions`	列出已安装版本
`rbenv version`	显示当前版本
`rbenv global <version>`	设置全局默认版本
`rbenv local <version>`	设置当前目录的版本
`rbenv shell <version>`	设置当前 shell 会话的版本
`rbenv rehash`	更新 shim 文件（安装新 gem 后）
`rbenv which <cmd>`	显示命令的实际路径

2.3 使用 RVM 安装

2.3.1 安装 RVM

# 安装 RVM
\curl -sSL https://get.rvm.io | bash -s stable

# 加载 RVM
source ~/.rvm/scripts/rvm

# 验证
rvm --version

2.3.2 安装 Ruby

# 查看可用版本
rvm list known

# 安装最新稳定版
rvm install 3.3.0

# 设置默认版本
rvm use 3.3.0 --default

# 验证
ruby --version

2.3.3 RVM Gemset 管理

RVM 独有的 gemset 功能可以隔离不同项目的 gem：

# 创建 gemset
rvm gemset create my_project

# 使用 gemset
rvm use 3.3.0@my_project

# 切换到项目目录时自动使用
echo "ruby-3.3.0" > .ruby-version
echo "my_project" > .ruby-gemset

# 列出 gemset
rvm gemset list

# 删除 gemset
rvm gemset delete my_project

2.3.4 rbenv vs RVM

特性	rbenv	RVM
安装方式	插件式、轻量	整体式、较重
Shell 修改	仅添加 shim 路径	修改较多环境变量
Gemset	不支持（用 Bundler 替代）	原生支持
切换速度	快	较快
社区活跃度	非常活跃	活跃
推荐场景	大多数项目	需要 gemset 隔离

2.4 系统包管理器安装

⚠️ 注意：系统包管理器的 Ruby 版本通常较旧，仅适合快速体验，不推荐用于开发。

macOS：

# macOS 自带 Ruby（通常版本较旧）
ruby --version

# 通过 Homebrew 安装
brew install ruby

Ubuntu / Debian：

sudo apt-get install ruby-full

Fedora / RHEL：

sudo dnf install ruby

Windows：

# 使用 Chocolatey
choco install ruby

# 或使用 RubyInstaller
# 下载地址：https://rubyinstaller.org/

2.5 源码编译安装

# 下载源码
wget https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.0.tar.gz
tar -xzf ruby-3.3.0.tar.gz
cd ruby-3.3.0

# 配置、编译、安装
./configure --prefix=$HOME/.local --disable-install-doc
make -j$(nproc)
make install

# 添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证
ruby --version

2.6 配置 Bundler

2.6.1 安装 Bundler

# Bundler 通常随 Ruby 一起安装
gem install bundler

# 验证
bundler --version  # => Bundler version 2.5.x

2.6.2 Bundler 基础用法

# 初始化 Gemfile
bundle init

# 添加 gem 到 Gemfile
bundle add sinatra
bundle add rspec --group test

# 安装所有依赖
bundle install

# 运行命令（在 bundle 环境下）
bundle exec ruby script.rb
bundle exec rspec

2.6.3 Gemfile 示例

# Gemfile
source "https://rubygems.org"

ruby "3.3.0"   # 指定 Ruby 版本

# 主要依赖
gem "rails", "~> 7.1"
gem "puma", "~> 6.0"
gem "pg", "~> 1.5"

# 特定分组
group :development, :test do
  gem "rspec-rails"
  gem "rubocop", require: false
end

group :test do
  gem "capybara"
  gem "selenium-webdriver"
end

# 从 Git 仓库
gem "my_gem", git: "https://github.com/user/my_gem.git"

# 本地路径
gem "my_local_gem", path: "../my_local_gem"

2.6.4 Gemfile.lock 说明

# Gemfile.lock 锁定所有依赖的精确版本
# 应该提交到版本控制系统

# 更新所有依赖
bundle update

# 更新特定 gem
bundle update rails

# 查看依赖树
bundle viz        # 需要安装 graphviz

# 检查过期的 gem
bundle outdated

2.7 配置 RubyGems

2.7.1 使用镜像源（国内加速）

# 查看当前源
gem sources -l

# 移除官方源
gem sources --remove https://rubygems.org/

# 添加国内镜像
gem sources --add https://gems.ruby-china.com/

# Bundler 镜像配置
bundle config mirror.https://rubygems.org https://gems.ruby-china.com

2.7.2 Gem 配置文件

# ~/.gemrc 文件配置
---
gem: --no-document          # 安装时不生成文档
install: --no-document
update: --no-document
:backtrace: false
:bulk_threshold: 1000
:update_sources: true
:verbose: true
:sources:
- https://gems.ruby-china.com/

2.8 编辑器配置

2.8.1 VS Code（推荐）

推荐安装以下扩展：

扩展	说明
Ruby LSP	官方推荐的语言服务器
Ruby	基础语法高亮
RuboCop	代码风格检查
endwise	自动补全 end 关键字
Ruby Test Explorer	测试运行器

// .vscode/settings.json
{
  "ruby.useLanguageServer": "ruby-lsp",
  "ruby.format": "rubocop",
  "ruby.lint": "rubocop",
  "editor.formatOnSave": true,
  "files.associations": {
    "Gemfile": "ruby",
    "Rakefile": "ruby",
    "*.gemspec": "ruby"
  }
}

2.8.2 RubyMine

JetBrains 的 RubyMine 是最强大的 Ruby IDE，功能全面但需要付费。

2.8.3 Vim / Neovim

" .vimrc 或 init.lua 相关配置
" 使用 vim-ruby 插件
Plug 'vim-ruby/vim-ruby'

" LSP 配置（使用 solargruby 或 ruby-lsp）
Plug 'neovim/nvim-lspconfig'

2.9 环境验证

创建一个脚本来验证环境是否正确配置：

# check_env.rb
puts "=" * 50
puts "Ruby 环境检查"
puts "=" * 50

# Ruby 版本
puts "Ruby 版本: #{RUBY_VERSION}"
puts "Ruby 引擎: #{RUBY_ENGINE}"
puts "平台:      #{RUBY_PLATFORM}"
puts "安装路径:  #{RbConfig.ruby}"

# Gem 信息
puts "\nGem 路径:"
Gem.path.each { |p| puts "  - #{p}" }

# Bundler
puts "\nBundler 版本: #{Bundler::VERSION}"

# 检查常用工具
tools = {
  "git"     => "Git 版本管理",
  "node"    => "Node.js（Rails Webpacker 需要）",
  "yarn"    => "Yarn（前端依赖管理）",
  "sqlite3" => "SQLite3（开发数据库）"
}

puts "\n工具检查:"
tools.each do |cmd, desc|
  version = `#{cmd} --version 2>/dev/null`.strip
  status = version.empty? ? "❌ 未安装" : "✅ #{version.split("\n").first}"
  puts "  #{desc}: #{status}"
end

puts "\n" + "=" * 50
puts "环境检查完成！"

ruby check_env.rb

2.10 常见问题

Q1: `ruby: command not found`

# 检查 rbenv 初始化是否正确
echo $PATH | tr ':' '\n' | grep rbenv

# 重新初始化
eval "$(rbenv init - bash)"  # 或 zsh

Q2: `gem install` 权限错误

# 不要使用 sudo 安装 gem！
# 正确做法是使用版本管理器

# 如果必须使用系统 Ruby，配置 gem 路径
echo 'export GEM_HOME="$HOME/.gem"' >> ~/.bashrc
echo 'export PATH="$HOME/.gem/bin:$PATH"' >> ~/.bashrc

Q3: OpenSSL 版本不兼容

# Ubuntu/Debian 安装依赖
sudo apt-get install libssl-dev

# macOS
brew install openssl@3
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@3)" \
  rbenv install 3.3.0

Q4: 安装速度慢

# 使用国内镜像
# ruby-build 使用镜像
RUBY_BUILD_MIRROR_URL=https://cache.ruby-china.com \
  rbenv install 3.3.0

2.11 动手练习

安装 rbenv：按照本章步骤安装 rbenv 和 Ruby
配置 Bundler：创建一个 Gemfile，添加几个 gem 并安装
配置镜像源：将 gem 源切换到国内镜像
验证环境：运行环境检查脚本

# 练习：创建一个测试项目
mkdir ruby_test && cd ruby_test
bundle init
echo 'gem "colorize"' >> Gemfile
bundle install
ruby -e 'require "colorize"; puts "Hello Ruby!".green'

2.12 本章小结

要点	说明
版本管理器	推荐 rbenv，轻量且高效
安装步骤	rbenv install → rbenv global → 验证
Bundler	项目依赖管理的核心工具
镜像源	国内使用 gems.ruby-china.com 加速
编辑器	VS Code + Ruby LSP 是不错的组合

📖 扩展阅读

上一章：← 第 01 章：Ruby 概述 下一章：第 03 章：Hello World →

强曰为道

第 02 章：安装与环境配置

第 02 章：安装与环境配置

2.1 安装方式概览

2.2 使用 rbenv 安装（推荐）

2.2.1 安装 rbenv 和 ruby-build

2.2.2 安装 Ruby

2.2.3 rbenv 常用命令

2.3 使用 RVM 安装

2.3.1 安装 RVM

2.3.2 安装 Ruby

2.3.3 RVM Gemset 管理

2.3.4 rbenv vs RVM

2.4 系统包管理器安装

2.5 源码编译安装

2.6 配置 Bundler

2.6.1 安装 Bundler

2.6.2 Bundler 基础用法

2.6.3 Gemfile 示例

2.6.4 Gemfile.lock 说明

2.7 配置 RubyGems

2.7.1 使用镜像源（国内加速）

2.7.2 Gem 配置文件

2.8 编辑器配置

2.8.1 VS Code（推荐）

2.8.2 RubyMine

2.8.3 Vim / Neovim

2.9 环境验证

2.10 常见问题

Q1: ruby: command not found

Q2: gem install 权限错误

Q3: OpenSSL 版本不兼容

Q4: 安装速度慢

2.11 动手练习

2.12 本章小结

📖 扩展阅读

Q1: `ruby: command not found`

Q2: `gem install` 权限错误