Gemfile #

什么是 Gemfile? #

Gemfile 是 Bundler 的配置文件,用于声明 Ruby 项目的依赖关系。它描述了项目需要哪些 Gem 包、版本要求、以及从哪里获取这些包。

基本结构 #

ruby
# Gemfile
source 'https://rubygems.org'

ruby '3.2.0'

gem 'rails', '~> 7.0'
gem 'pg', '~> 1.4'

group :development do
  gem 'pry'
end

source 配置 #

指定 Gem 源 #

ruby
# 全局源
source 'https://rubygems.org'

# 使用国内镜像源
source 'https://gems.ruby-china.com'

# 多个源(按顺序尝试)
source 'https://rubygems.org'
source 'https://gems.ruby-china.com'

块级源 #

ruby
# 为特定 Gem 指定源
source 'https://rubygems.org' do
  gem 'rails'
  gem 'sinatra'
end

# 私有源
source 'https://gems.example.com' do
  gem 'my_private_gem'
end

Git 源 #

ruby
# 从 Git 仓库安装
gem 'rails', git: 'https://github.com/rails/rails.git'

# 指定分支
gem 'rails', git: 'https://github.com/rails/rails.git', branch: 'main'

# 指定标签
gem 'rails', git: 'https://github.com/rails/rails.git', tag: 'v7.0.4'

# 指定提交
gem 'rails', git: 'https://github.com/rails/rails.git', ref: 'abc123'

# 指定子目录
gem 'rails', git: 'https://github.com/rails/rails.git', glob: 'railties/*'

GitHub 源 #

ruby
# 简写形式
gem 'rails', github: 'rails/rails'

# 指定分支
gem 'rails', github: 'rails/rails', branch: 'main'

# 指定标签
gem 'rails', github: 'rails/rails', tag: 'v7.0.4'

本地路径 #

ruby
# 从本地路径加载
gem 'my_gem', path: '../my_gem'

# 绝对路径
gem 'my_gem', path: '/Users/dev/projects/my_gem'

ruby 指令 #

指定 Ruby 版本 #

ruby
# 指定精确版本
ruby '3.2.0'

# 指定版本范围
ruby '~> 3.2.0'

# 指定引擎
ruby '3.2.0', engine: 'jruby', engine_version: '9.4.0'

# 指定补丁级别
ruby '3.2.0', patchlevel: '0'

gem 指令 #

基本用法 #

ruby
# 最简形式
gem 'rails'

# 指定版本
gem 'rails', '7.0.4'

# 版本范围
gem 'rails', '~> 7.0'

# 多个版本约束
gem 'rails', '>= 7.0', '< 8.0'

版本约束语法 #

操作符 描述 示例
= 精确匹配 '7.0.4''= 7.0.4'
!= 不匹配 '!= 7.0.4'
> 大于 '> 7.0'
>= 大于等于 '>= 7.0'
< 小于 '< 8.0'
<= 小于等于 '<= 8.0'
~> 悲观约束 '~> 7.0'
>= ... < 范围 '>= 7.0', '< 8.0'

悲观版本约束 (~>) #

ruby
# 允许 patch 更新 (7.0.x)
gem 'rails', '~> 7.0.0'  # >= 7.0.0 且 < 7.1.0

# 允许 minor 更新 (7.x)
gem 'rails', '~> 7.0'    # >= 7.0.0 且 < 8.0.0

# 允许 major 更新
gem 'rails', '~> 7'      # >= 7.0.0 且 < 8.0.0

require 选项 #

ruby
# 自动 require(默认)
gem 'rails'

# 不自动 require
gem 'rails', require: false

# 自定义 require 文件
gem 'sidekiq', require: 'sidekiq/web'

# 多个 require 文件
gem 'rails', require: ['rails', 'rails/all']

# 条件 require
gem 'rails', require: ENV['RAILS_ENV'] == 'development' ? 'rails' : false

groups 选项 #

ruby
# 指定分组
gem 'rspec', group: :test

# 多个分组
gem 'pry', group: [:development, :test]

# 排除分组
gem 'puma', group: :production

platform 选项 #

ruby
# 指定平台
gem 'tzinfo-data', platform: :windows

# 多个平台
gem 'ffi', platform: [:mingw, :x64_mingw]

# 平台范围
gem 'pg', platform: :ruby
gem 'activerecord-jdbcpostgresql-adapter', platform: :jruby

平台类型 #

平台 描述
:ruby C Ruby (MRI)
:jruby JRuby
:truffleruby TruffleRuby
:windows Windows
:mingw Windows (32-bit)
:x64_mingw Windows (64-bit)
:linux Linux
:mac macOS

group 指令 #

基本用法 #

ruby
# 单个分组
group :development do
  gem 'pry'
  gem 'rubocop'
end

# 多个分组
group :development, :test do
  gem 'rspec'
  gem 'factory_bot'
end

# 生产分组
group :production do
  gem 'puma'
  gem 'sentry-ruby'
end

嵌套分组 #

ruby
group :development do
  gem 'pry'
  
  group :test do
    gem 'rspec'
  end
end

条件分组 #

ruby
# 根据环境变量
group :development do
  gem 'pry' if ENV['RACK_ENV'] == 'development'
end

# 根据平台
group :development do
  gem 'byebug' if RUBY_PLATFORM =~ /darwin/
end

git 指令 #

全局 Git 设置 #

ruby
# 设置 Git 源
git_source(:github) { |repo| "https://github.com/#{repo}.git" }
git_source(:gitlab) { |repo| "https://gitlab.com/#{repo}.git" }

# 使用自定义源
gem 'rails', github: 'rails/rails'
gem 'mygem', gitlab: 'myorg/mygem'

Git 选项 #

ruby
# 分支
gem 'rails', git: 'https://github.com/rails/rails.git', branch: 'main'

# 标签
gem 'rails', git: 'https://github.com/rails/rails.git', tag: 'v7.0.4'

# 引用(commit hash)
gem 'rails', git: 'https://github.com/rails/rails.git', ref: 'abc123def'

# 子模块
gem 'rails', git: 'https://github.com/rails/rails.git', submodules: true

gemspec 指令 #

从 gemspec 加载依赖 #

ruby
# 加载 gemspec 中的依赖
gemspec

# 指定 gemspec 文件
gemspec name: 'mygem'

# 指定路径
gemspec path: 'lib/mygem'

# 开发依赖分组
gemspec development_group: :development

# 只加载运行时依赖
gemspec runtime_only: true

完整 Gemfile 示例 #

Rails 项目 #

ruby
# frozen_string_literal: true

source 'https://rubygems.org'

ruby '3.2.0'

# Rails 框架
gem 'rails', '~> 7.0.4'

# 数据库
gem 'pg', '~> 1.4'

# Web 服务器
gem 'puma', '~> 6.0'

# 前端
gem 'jsbundling-rails'
gem 'cssbundling-rails'
gem 'turbo-rails'
gem 'stimulus-rails'

# 资产管理
gem 'image_processing', '~> 1.2'

# Redis
gem 'redis', '~> 5.0'

# 后台任务
gem 'sidekiq', '~> 7.0'

# 分页
gem 'kaminari', '~> 1.2'

# 搜索
gem 'ransack', '~> 3.2'

# 认证
gem 'devise', '~> 4.9'

# 授权
gem 'pundit', '~> 2.3'

# API
gem 'jbuilder', '~> 2.11'

group :development, :test do
  # 调试
  gem 'pry-rails'
  gem 'pry-byebug'
  
  # 测试
  gem 'rspec-rails', '~> 6.0'
  gem 'factory_bot_rails'
  gem 'capybara'
  gem 'selenium-webdriver'
  
  # 代码质量
  gem 'rubocop', require: false
  gem 'rubocop-rails', require: false
  gem 'rubocop-rspec', require: false
  
  # 安全检查
  gem 'brakeman', require: false
  gem 'bundler-audit', require: false
end

group :development do
  # 控制台
  gem 'awesome_print'
  
  # 文档
  gem 'yard'
  
  # 性能分析
  gem 'bullet'
  gem 'rack-mini-profiler'
  
  # 错误页面
  gem 'better_errors'
  gem 'binding_of_caller'
end

group :test do
  gem 'simplecov', require: false
  gem 'webmock'
  gem 'vcr'
end

group :production do
  # 监控
  gem 'sentry-ruby'
  gem 'sentry-rails'
  
  # 性能监控
  gem 'newrelic_rpm'
end

# Windows 平台
platforms :mingw, :x64_mingw, :mswin do
  gem 'tzinfo-data'
end

Gem 开发项目 #

ruby
# frozen_string_literal: true

source 'https://rubygems.org'

# 从 gemspec 加载依赖
gemspec

group :development, :test do
  gem 'rake', '~> 13.0'
  gem 'rspec', '~> 3.12'
  gem 'rubocop', '~> 1.50', require: false
end

group :development do
  gem 'yard', '~> 0.9'
  gem 'redcarpet', '~> 3.6'
end

Sinatra 项目 #

ruby
# frozen_string_literal: true

source 'https://rubygems.org'

ruby '3.2.0'

gem 'sinatra', '~> 3.0'
gem 'sinatra-contrib', '~> 3.0'
gem 'puma', '~> 6.0'
gem 'activerecord', '~> 7.0'
gem 'sqlite3', '~> 1.6'

group :development do
  gem 'pry'
  gem 'rerun'
end

group :test do
  gem 'rspec'
  gem 'rack-test'
end

Gemfile.lock #

什么是 Gemfile.lock? #

Gemfile.lock 是 Bundler 自动生成的文件,记录了实际安装的精确版本。

text
GEM
  remote: https://rubygems.org/
  specs:
    actionpack (7.0.4)
      actionview (= 7.0.4)
      activesupport (= 7.0.4)
    rails (7.0.4)
      actionpack (= 7.0.4)

PLATFORMS
  ruby

DEPENDENCIES
  rails (~> 7.0)

BUNDLED WITH
   2.4.0

为什么需要 Gemfile.lock? #

  1. 确定性构建:确保团队成员使用相同版本
  2. 生产一致性:开发和生产环境版本一致
  3. 问题排查:记录确切的依赖版本

Gemfile.lock 管理 #

bash
# 更新 Gemfile.lock
bundle install

# 更新特定 Gem
bundle update rails

# 更新所有 Gem
bundle update

# 检查 Gemfile.lock 是否最新
bundle check

高级用法 #

条件依赖 #

ruby
# 根据环境变量
if ENV['RAILS_ENV'] == 'development'
  gem 'pry'
end

# 根据 Ruby 版本
if RUBY_VERSION >= '3.0'
  gem 'syntax_suggest'
end

# 根据平台
if RUBY_PLATFORM =~ /darwin/
  gem 'fsevent'
end

环境变量 #

ruby
# 使用环境变量
gem 'mygem', version: ENV['MYGEM_VERSION']

# 条件安装
gem 'debug' if ENV['DEBUG'] == 'true'

评估 Ruby 代码 #

ruby
# 读取版本号
version = File.read('VERSION').strip
gem 'mygem', version

# 动态生成依赖
Dir['plugins/*'].each do |plugin|
  gem plugin, path: plugin
end

安装后钩子 #

ruby
# 在 .bundle/config 中配置
# BUNDLE_POST_INSTALL_BUNDLE_EXEC: "rake db:migrate"

最佳实践 #

版本约束建议 #

ruby
# 推荐:允许 minor 更新
gem 'rails', '~> 7.0'

# 不推荐:精确版本(除非必要)
gem 'rails', '7.0.4'

# 不推荐:无约束
gem 'rails'

分组建议 #

ruby
# 开发和测试工具放在一起
group :development, :test do
  gem 'pry'
  gem 'rspec'
end

# 生产专用工具单独分组
group :production do
  gem 'puma'
  gem 'sentry-ruby'
end

注释建议 #

ruby
# 清晰的注释
gem 'sidekiq', '~> 7.0'  # 后台任务处理
gem 'devise', '~> 4.9'   # 用户认证

# 分组注释
group :development do
  # 调试工具
  gem 'pry-rails'
  gem 'pry-byebug'
  
  # 代码质量
  gem 'rubocop'
end

常见问题 #

版本冲突 #

bash
# 查看依赖树
bundle viz

# 查看特定 Gem 依赖
bundle show rails

# 强制更新
bundle update rails --force

安装失败 #

bash
# 清理缓存
bundle clean --force

# 重新安装
rm -rf vendor/bundle
bundle install --path vendor/bundle

平台问题 #

ruby
# 使用平台条件
platforms :ruby do
  gem 'pg'
end

platforms :jruby do
  gem 'activerecord-jdbcpostgresql-adapter'
end

下一步 #

现在你已经掌握了 Gemfile 的详细用法,接下来学习 依赖管理 了解 Bundler 的依赖解析机制!

最后更新:2026-03-28