---

name: skill-rails-upgrade description: "分析 Rails 应用并提供升级评估" risk: safe source: "https://github.com/robzolkos/skill-rails-upgrade" date_added: "2026-02-27"

何时使用此技能

分析 Rails 应用并提供升级评估

当需要分析 Rails 应用并提供升级评估时使用此技能。

Rails 升级分析器

分析当前 Rails 应用程序，提供全面的升级评估和选择性文件合并。

步骤 1：验证 Rails 应用程序

通过查找以下文件确认我们在一个 Rails 应用程序中：

• Gemfile（必须存在且包含 'rails'）
• config/application.rb（Rails 应用配置）
• config/environment.rb（Rails 环境）

如果缺少任何文件或不表明是 Rails 应用，停止并通知用户这似乎不是一个 Rails 应用程序。

步骤 2：获取当前 Rails 版本

从以下位置提取当前 Rails 版本：

1. 首先检查 Gemfile.lock 中的确切安装版本（查找 rails (x.y.z)）
2. 如果未找到，检查 Gemfile 中的版本约束

报告确切的当前版本（例如 7.1.3）。

步骤 3：查找最新 Rails 版本

使用 GitHub CLI 获取最新的 Rails 发布版本：

gh api repos/rails/rails/releases/latest --jq '.tag_name'

这将返回最新的稳定版本标签（例如 v8.0.1）。去掉 'v' 前缀进行比较。

同时检查最近的标签以了解发布情况：

gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'

步骤 4：确定升级类型

比较当前版本和最新版本以分类升级：

• 补丁升级：相同的主版本.次版本，不同的补丁号（例如 7.1.3 → 7.1.5）
• 次版本升级：相同的主版本，不同的次版本（例如 7.1.3 → 7.2.0）
• 主版本升级：不同的主版本号（例如 7.1.3 → 8.0.0）

步骤 5：获取升级指南

使用 WebFetch 获取官方 Rails 升级指南：

URL：https://guides.rubyonrails.org/upgrading_ruby_on_rails.html

查找与版本跳跃相关的部分。指南按目标版本组织，包含以下部分：

• "从 Rails X.Y 升级到 Rails X.Z"
• 破坏性变更
• 弃用警告
• 配置变更
• 必需的迁移

提取并总结与用户特定升级路径相关的部分。

步骤 6：获取 Rails 差异

使用 WebFetch 从 railsdiff.org 获取版本之间的差异：

URL：https://railsdiff.org/{current_version}/{target_version}

例如：https://railsdiff.org/7.1.3/8.0.0

这将显示：

• 默认配置文件的变更
• 需要添加的新文件
• 修改的初始化器
• 更新的依赖项
• bin/ 脚本的变更

总结关键文件变更。

步骤 7：检查 JavaScript 依赖

Rails 应用程序通常包含需要与 Rails 一起更新的 JavaScript 包。检查并报告这些依赖项。

7.1：识别 JS 包管理器

检查应用使用哪个包管理器：

# 检查 package.json (npm/yarn)
ls package.json 2>/dev/null

# 检查 importmap (Rails 7+)
ls config/importmap.rb 2>/dev/null

7.2：检查 Rails 相关 JS 包

如果 package.json 存在，检查这些 Rails 相关包：

# 提取 Rails 相关包的当前版本
cat package.json | grep -E '"@hotwired/|"@rails/|"stimulus"|"turbo-rails"' || echo "No Rails JS packages found"

需要检查的关键包：

| 包名 | 用途 | 版本对齐 | |---------|---------|-------------------| | @hotwired/turbo-rails | Turbo Drive/Frames/Streams | 应匹配 Rails 版本时代 | | @hotwired/stimulus | Stimulus JS 框架 | 跨 Rails 版本通常稳定 | | @rails/actioncable | WebSocket 支持 | 应匹配 Rails 版本 | | @rails/activestorage | 直接上传 | 应匹配 Rails 版本 | | @rails/actiontext | 富文本编辑 | 应匹配 Rails 版本 | | @rails/request.js | Rails UJS 替代品 | 应匹配 Rails 版本时代 |

7.3：检查更新

对于 npm/yarn 项目，检查可用更新：

# 使用 npm
npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null

# 或直接检查最新版本
npm view @hotwired/turbo-rails version 2>/dev/null
npm view @rails/actioncable version 2>/dev/null

7.4：检查 Importmap Pins（如适用）

如果应用使用 importmap-rails，检查 config/importmap.rb 中的固定版本：

cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "No importmap pins found"

更新 importmap pins：

bin/importmap pin @hotwired/turbo-rails
bin/importmap pin @hotwired/stimulus

7.5：JS 依赖总结

在升级总结中包含：

### JavaScript 依赖

**包管理器**：[npm/yarn/importmap/none]

| 包名 | 当前版本 | 最新版本 | 操作 |
|---------|---------|--------|--------|
| @hotwired/turbo-ra