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? #
- 确定性构建:确保团队成员使用相同版本
- 生产一致性:开发和生产环境版本一致
- 问题排查:记录确切的依赖版本
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