Ruby 入门指南 / 第 02 章：安装与环境配置

第 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 →