Ruby Gem：包管理与安装

Ruby 的强大生态离不开 Gem——这是 Ruby 的官方包（库）格式。每个 Gem 封装了可复用的代码、命令行工具或框架功能。要高效开发 Ruby 项目，你必须掌握 Gem 的安装、管理和版本控制方法。

安装 Ruby 和 Gem 环境

绝大多数现代操作系统默认不预装 Ruby，因此第一步是确保环境就绪。

1. 检查 是否已安装 Ruby：在终端运行

   ruby -v

   如果返回类似 ruby 3.2.0p... 的信息，说明 Ruby 已安装；否则需先安装 Ruby。

2. 安装 Ruby（推荐使用版本管理工具）：

   • macOS 用户：安装 rbenv 或 rvm。以 rbenv 为例：

     brew install rbenv
     rbenv init

     按提示将初始化命令加入 shell 配置文件（如 ~/.zshrc），然后重启终端。

   • Linux 用户：可通过系统包管理器（如 apt）安装，但更推荐 rbenv 以避免权限问题。
   • Windows 用户：下载并安装 RubyInstaller，它自带 gem 命令。

3. 验证 gem 命令是否可用：

   gem -v

   若显示版本号（如 3.4.22），环境准备完成。

安装单个 Gem

最直接的方式是从 RubyGems.org（官方仓库）安装一个 Gem。

1. 打开 终端。
2. 执行 安装命令，格式为：

   gem install GEM_NAME

   例如安装流行 HTTP 客户端 httparty：

   gem install httparty

3. 等待 下载和编译完成。若看到 Successfully installed httparty-0.21.0，说明安装成功。
4. 测试 是否能加载：创建一个临时 Ruby 文件 test.rb，内容为：

   require 'httparty'
   puts "HTTParty loaded!"

   运行：

   ruby test.rb

   若输出 HTTParty loaded!，则 Gem 可正常使用。

注意：部分 Gem 含 C 扩展（如 nokogiri），可能需要额外安装系统依赖（如 libxml2-dev）。错误信息会明确提示缺失内容。

使用 Gemfile 管理项目依赖

真实项目通常依赖多个 Gem，且需固定版本以保证团队环境一致。此时应使用 bundler 工具配合 Gemfile。

1. 安装 bundler（若未安装）：

   gem install bundler

2. 进入 你的项目目录（若无，先创建）：

   mkdir my_ruby_app
   cd my_ruby_app

3. 生成 Gemfile：

   bundle init

   此命令创建一个包含基础配置的 Gemfile。

4. 编辑 Gemfile，添加所需 Gem。例如：

   # Gemfile
   source "https://rubygems.org"
   
   gem "sinatra", "~> 3.0"
   gem "dotenv", ">= 2.8"

5. 安装 所有依赖到项目本地（而非全局）：

   bundle install

   此命令会：

   • 读取 Gemfile
   • 解析依赖关系
   • 下载并安装所有 Gem
   • 生成 Gemfile.lock（锁定确切版本）

6. 运行 项目代码时，务必通过 bundle exec 加载正确环境：

   bundle exec ruby app.rb

   这确保程序使用 Gemfile.lock 中指定的版本，而非系统全局 Gem。

常用 Gem 管理命令

以下命令可高效维护 Gem 环境：

处理 Gem 安装失败

常见问题及解决方法：

1. 权限错误（如 You don't have write permissions）：

   • 原因：尝试向系统 Ruby 目录写入。
   • 解决：改用 rbenv/rvm 管理 Ruby 版本，或始终用 bundle install --path vendor/bundle 将依赖安装到项目内。

2. 编译错误（如 make failed）：

   • 原因：缺少构建工具或系统库。
   • 解决：
     • Ubuntu/Debian: 运行 sudo apt-get install build-essential libssl-dev libreadline-dev zlib1g-dev
     • macOS: 确保 Xcode 命令行工具已安装（xcode-select --install）

3. 网络超时：

   • 更换 Gem 源为国内镜像（如清华源）：

     gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/ --remove https://rubygems.org/

创建自己的 Gem

当你有通用代码需复用，可打包为 Gem 分享给他人。

1. 生成 Gem 脚手架：

   bundle gem my_utility

   此命令创建 my_utility 目录，含标准 Gem 结构。

2. 编辑 my_utility.gemspec，填写名称、版本、作者等元数据。

3. 编写 功能代码放入 lib/my_utility.rb。

4. 本地安装 测试：

   cd my_utility
   gem build my_utility.gemspec
   gem install ./my_utility-0.1.0.gem

5. 发布 到 RubyGems.org（需先注册账号）：

   gem push my_utility-0.1.0.gem

# 示例：一个极简 Gem 的核心文件 lib/my_utility.rb
module MyUtility
  def self.hello
    "Hello from MyUtility!"
  end
end

调用该 Gem 的方式与其他 Gem 一致：

require 'my_utility'
puts MyUtility.hello