安装与配置 #

安装概述 #

RubyGems 从 Ruby 1.9 开始已经成为 Ruby 的标准组成部分，通常无需单独安装。但了解安装和配置方法对于环境管理非常重要。

检查当前版本 #

bash

# 检查 Ruby 版本
ruby -v
# ruby 3.2.0 (2022-12-25 revision a528908271)

# 检查 RubyGems 版本
gem -v
# 3.4.0

# 检查 Bundler 版本
bundle -v
# Bundler version 2.4.0

安装 Ruby #

方式一：使用版本管理器（推荐） #

rbenv #

rbenv 是轻量级的 Ruby 版本管理器：

bash

# macOS (使用 Homebrew)
brew install rbenv ruby-build

# 配置 shell
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

# 安装 Ruby
rbenv install 3.2.0
rbenv global 3.2.0

# 验证
ruby -v
gem -v

rvm (Ruby Version Manager) #

rvm 是功能丰富的 Ruby 版本管理器：

bash

# 安装 GPG 密钥
gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3

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

# 安装 Ruby
rvm install 3.2.0
rvm use 3.2.0 --default

# 验证
ruby -v
gem -v

asdf #

asdf 是通用的版本管理器，支持多种语言：

bash

# 安装 asdf
brew install asdf

# 添加 Ruby 插件
asdf plugin add ruby

# 安装 Ruby
asdf install ruby 3.2.0
asdf global ruby 3.2.0

# 验证
ruby -v

方式二：系统包管理器 #

macOS (Homebrew) #

bash

# 安装 Ruby
brew install ruby

# 添加到 PATH
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Ubuntu/Debian #

bash

# 更新包列表
sudo apt update

# 安装 Ruby 和 RubyGems
sudo apt install ruby-full ruby-bundler

# 验证
ruby -v
gem -v

CentOS/RHEL #

bash

# 启用 EPEL 仓库
sudo yum install epel-release

# 安装 Ruby
sudo yum install ruby ruby-devel rubygems

# 验证
ruby -v
gem -v

方式三：官方安装包 #

从 Ruby 官网下载安装包：

Windows: 使用 RubyInstaller
macOS: 使用官方 pkg 安装包
Linux: 编译源码安装

bash

# 编译安装（Linux/macOS）
wget https://cache.ruby-lang.org/pub/ruby/3.2/ruby-3.2.0.tar.gz
tar -xzf ruby-3.2.0.tar.gz
cd ruby-3.2.0
./configure --prefix=/usr/local
make
sudo make install

安装 Bundler #

Bundler 是 Ruby 项目依赖管理的标准工具：

bash

# 安装 Bundler
gem install bundler

# 安装特定版本
gem install bundler -v 2.4.0

# 验证
bundle -v

更新 RubyGems #

更新到最新版本 #

bash

# 更新 RubyGems
gem update --system

# 更新到特定版本
gem update --system 3.4.0

# 验证版本
gem -v

更新 Bundler #

bash

# 更新 Bundler
gem update bundler

# 或者在项目中更新
bundle update --bundler

配置 RubyGems #

配置文件位置 #

RubyGems 的配置文件为 .gemrc，位于以下位置：

位置	优先级	描述
项目根目录	最高	项目级配置
`~/.gemrc`	中	用户级配置
`/etc/gemrc`	低	系统级配置

基本配置 #

yaml

# ~/.gemrc
:sources:
  - https://rubygems.org/
:backtrace: false
:bulk_threshold: 1000
:benchmark: false
:verbose: true
:update_sources: true

使用命令配置 #

bash

# 查看所有配置
gem env

# 查看特定配置
gem env gemdir

# 设置配置
gem config set verbose true

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

# 删除镜像源
gem sources --remove https://rubygems.org/

# 查看当前源
gem sources -l

镜像源配置 #

国内镜像源 #

由于网络原因，国内用户推荐使用镜像源：

bash

# 移除默认源
gem sources --remove https://rubygems.org/

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

# 查看当前源
gem sources -l
# *** CURRENT SOURCES ***
# https://gems.ruby-china.com/

常用镜像源 #

镜像源	地址
Ruby China	https://gems.ruby-china.com/
清华大学	https://mirrors.tuna.tsinghua.edu.cn/rubygems/
官方源	https://rubygems.org/

Bundler 镜像源配置 #

ruby

# Gemfile
source 'https://gems.ruby-china.com/'

gem 'rails'

或者使用配置文件：

bash

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

安装目录配置 #

查看安装路径 #

bash

# 查看 Gem 安装目录
gem env gemdir
# /usr/local/lib/ruby/gems/3.2.0

# 查看完整环境信息
gem env

用户级安装 #

避免权限问题，可以安装到用户目录：

bash

# 安装到用户目录
gem install mygem --user-install

# 配置默认用户安装
gem config set --global user-install true

项目级安装 #

使用 Bundler 安装到项目目录：

bash

# 安装到 vendor/bundle
bundle install --path vendor/bundle

# 后续安装会自动使用该路径
bundle install

代理配置 #

设置 HTTP 代理 #

bash

# 设置代理
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# 安装 Gem
gem install rails

在 .gemrc 中配置 #

yaml

# ~/.gemrc
:http_proxy: http://proxy.example.com:8080
:https_proxy: http://proxy.example.com:8080

Bundler 代理配置 #

bash

# 设置 Bundler 代理
bundle config proxy http://proxy.example.com:8080

SSL/TLS 配置 #

SSL 证书问题 #

如果遇到 SSL 证书问题：

bash

# 更新 RubyGems（包含更新的证书）
gem update --system

# 更新证书
gem install certifi

禁用 SSL 验证（不推荐） #

bash

# 临时禁用 SSL 验证
gem install mygem --source http://rubygems.org

# Bundler 禁用 SSL 验证
bundle config ssl_verify_mode 0

多版本 Ruby 管理 #

使用 rbenv #

bash

# 查看可安装版本
rbenv install -l

# 安装多个版本
rbenv install 3.1.0
rbenv install 3.2.0

# 切换版本
rbenv global 3.2.0    # 全局默认
rbenv local 3.1.0     # 当前目录

# 查看当前版本
rbenv version

使用 rvm #

bash

# 查看可安装版本
rvm list known

# 安装多个版本
rvm install 3.1.0
rvm install 3.2.0

# 切换版本
rvm use 3.2.0
rvm use 3.2.0 --default

# 查看已安装版本
rvm list

Gemset 管理（rvm） #

bash

# 创建 Gemset
rvm gemset create myproject

# 使用 Gemset
rvm gemset use myproject

# 列出所有 Gemset
rvm gemset list

# 删除 Gemset
rvm gemset delete myproject

环境变量 #

常用环境变量 #

变量	描述
`GEM_HOME`	Gem 安装目录
`GEM_PATH`	Gem 搜索路径
`GEMRC`	.gemrc 文件路径
`BUNDLE_PATH`	Bundler 安装路径

设置环境变量 #

bash

# 设置 GEM_HOME
export GEM_HOME=$HOME/.gem

# 添加到 PATH
export PATH=$GEM_HOME/bin:$PATH

# 添加到 shell 配置文件
echo 'export GEM_HOME=$HOME/.gem' >> ~/.zshrc
echo 'export PATH=$GEM_HOME/bin:$PATH' >> ~/.zshrc

Docker 环境配置 #

Dockerfile 示例 #

dockerfile

FROM ruby:3.2.0

WORKDIR /app

# 配置镜像源
RUN gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/

# 安装 Bundler
RUN gem install bundler

# 复制 Gemfile
COPY Gemfile Gemfile.lock ./

# 安装依赖
RUN bundle install --jobs 4 --retry 3

# 复制应用代码
COPY . .

# 启动命令
CMD ["rails", "server", "-b", "0.0.0.0"]

docker-compose.yml 示例 #

yaml

version: '3.8'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - bundle_cache:/usr/local/bundle
    environment:
      - RAILS_ENV=development

volumes:
  bundle_cache:

验证安装 #

检查环境 #

bash

# 检查 Ruby
ruby -v

# 检查 RubyGems
gem -v

# 检查 Bundler
bundle -v

# 检查环境信息
gem env

# 检查已安装的 Gems
gem list

测试安装 #

bash

# 安装测试 Gem
gem install minitest

# 创建测试文件
cat > test.rb << 'EOF'
require 'minitest/autorun'

class TestExample < Minitest::Test
  def test_truth
    assert true
  end
end
EOF

# 运行测试
ruby test.rb

常见问题 #

权限问题 #

bash

# 错误信息
# ERROR: While executing gem ... (Gem::FilePermissionError)

# 解决方案 1: 使用 sudo
sudo gem install mygem

# 解决方案 2: 安装到用户目录
gem install mygem --user-install

# 解决方案 3: 修改目录权限
sudo chown -R $(whoami) /usr/local/lib/ruby/gems

网络问题 #

bash

# 错误信息
# ERROR: Could not find a valid gem

# 解决方案 1: 使用镜像源
gem sources --add https://gems.ruby-china.com/

# 解决方案 2: 使用代理
export https_proxy=http://proxy.example.com:8080

# 解决方案 3: 增加超时时间
gem install mygem --timeout 300

版本冲突 #

bash

# 错误信息
# Gem::LoadError: You have already activated xxx

# 解决方案 1: 更新 Bundler
gem update bundler

# 解决方案 2: 使用 bundle exec
bundle exec ruby app.rb

# 解决方案 3: 清理旧版本
gem cleanup

原生扩展编译失败 #

bash

# 错误信息
# ERROR: Failed to build gem native extension

# 解决方案: 安装开发工具

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential ruby-dev

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install ruby-devel

下一步 #

现在你已经完成了 RubyGems 的安装和配置，接下来学习基本命令开始使用 RubyGems！