RubyGems 完全指南：查找、安装与管理 Ruby 包
RubyGems 是 Ruby 的官方包管理生态。本文讲解 gem 的查找评估、安装、版本约束语法、Bundler 依赖管理与 Gemfile.lock 的正确用法。
RubyGems（gem 命令）负责安装单个包，Bundler（Gemfile）负责管理项目依赖——项目开发永远用 Bundler：Gemfile 声明依赖与版本约束，bundle install 安装并锁定 Gemfile.lock，团队成员与生产环境凭 lock 文件获得完全一致的依赖。
gem 解决什么问题
需要 HTTP 客户端、认证、测试工具？不用自己造——Ruby 生态有超过 18 万个 gem，覆盖几乎所有常见需求。gem 命令随 Ruby 自带，是获取这些工具的入口。
安装与基本命令
gem install rails # 安装最新版
gem install rails -v 7.1.0 # 指定版本
gem list rails # 查看本地已装
gem outdated # 查看可更新的
gem uninstall rails # 卸载
gem info rails # 查看详情
全局 gem 适合装命令行工具（rubocop、pry）；项目依赖不要全局装——那是 Bundler 的领地。
版本约束语法
Gemfile 里的版本声明决定升级策略：
gem 'rails', '~> 7.1' # >= 7.1 且 < 8.0（悲观的约符）
gem 'pg', '~> 1.5.3' # >= 1.5.3 且 < 1.6.0
gem 'nokogiri', '>= 1.15' # 最低版本
gem 'puma' # 任意版本（不推荐）
~> 读作"允许最后一位数字升级"，是平衡稳定性与更新的标准写法。
Bundler：项目依赖的完整闭环
# Gemfile
source 'https://rubygems.org'
gem 'rails', '~> 7.1'
gem 'pg'
group :development, :test do
gem 'rspec-rails'
gem 'factory_bot_rails'
end
bundle install # 安装并生成/更新 Gemfile.lock
bundle exec rails s # 在锁定环境中执行命令
bundle update nokogiri # 升级单个 gem（连带其依赖）
Gemfile.lock 必须提交到仓库——它记录了每个 gem 的精确版本和传递依赖树，保证你的机器、同事的机器、CI、生产服务器跑的是同一套代码。bundle exec 前缀确保命令使用的是 lock 文件里的版本而非系统里碰巧装的新版本，"在我电脑上能跑"的绝症由此根治。
找到靠谱的 gem：评估五问
在 rubygems.org 和 ruby-toolbox.com 上评估候选 gem：
- 维护活性：最近一年有提交和发版吗？（死项目是安全债）
- 下载量与口碑：百万级下载的 gem 经过充分验证；
- issue 响应：维护者是否处理 issue 和 PR；
- 依赖数量：引入一个 gem 连带拖进二十个依赖要警惕；
- 文档质量：README 写不清楚的 gem，用起来只会更痛苦。
常见问题（FAQ）
Q：gem install 报权限错误怎么办？
不要用 sudo！那会把 gem 装进系统 Ruby 引发混乱。正确做法是用 rbenv/Mise 管理的 Ruby（用户目录下安装），或配置 gem install --user-install。
Q：bundle install 编译原生扩展失败（如 nokogiri、pg）？
缺系统依赖：Ubuntu 装 build-essential libpq-dev libxml2-dev 等，macOS 用 brew 装对应库。nokogiri 新版自带预编译包，升级通常能绕过编译。
Q：如何发布自己的 gem？
bundle gem my_tool 生成骨架，编写 gemspec（名称、版本、依赖），gem build 打包，gem push 发布到 rubygems.org。内部私有 gem 可搭 geminabox 或用 GitHub Packages 私有源。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
