cloud-drive-renamer/RELEASE.md

📦 发布流程指南

CloudDrive Renamer Chrome 扩展自动化发布流程

---

🎯 概览

本项目已配置完整的 CI/CD 自动化发布流程，通过 GitHub Actions 实现：

• ✅ 自动构建：推送标签即触发构建
• ✅ 质量保证：自动运行测试和代码检查
• ✅ 自动打包：生成可直接安装的 ZIP 文件
• ✅ 自动发布：创建 GitHub Release 并附加下载链接
• 📋 变更日志：自动生成版本间的变更记录

---

🚀 快速发布

标准发布流程（3 步）

# 1. 更新版本号（在 package.json 中）
npm version patch   # 0.1.0 → 0.1.1 (修复 bug)
npm version minor   # 0.1.0 → 0.2.0 (新功能)
npm version major   # 0.1.0 → 1.0.0 (重大更新)

# 2. 推送代码和标签
git push origin main
git push origin --tags

# 3. 等待 GitHub Actions 完成（约 3-5 分钟）
# ✅ 发布完成！访问 GitHub Releases 页面查看

手动版本号控制

# 1. 手动编辑 package.json 中的 version 字段
# 例如：从 "0.1.0" 改为 "0.2.0"

# 2. 同步版本号到其他文件
npm run sync:version

# 3. 提交更改
git add .
git commit -m "chore: bump version to 0.2.0"

# 4. 创建并推送标签
git tag v0.2.0
git push origin main
git push origin v0.2.0

---

📋 发布前检查清单

在创建新版本前，请确认：

✅ 代码质量

• 所有测试通过：npm run test
• 类型检查通过：npm run typecheck
• 代码检查通过：npm run lint
• 本地构建成功：npm run build

✅ 功能验证

• 在 Quark 网盘测试重命名功能
• （可选）在 Aliyun Drive 测试（如已实现）
• （可选）在 Baidu Pan 测试（如已实现）
• 测试扩展弹出窗口和选项页面

✅ 文档更新

• 更新 README.md（如有新功能）
• 更新 CHANGELOG.md（如果手动维护）
• 更新屏幕截图（如 UI 有变化）

✅ 版本管理

• 确认版本号符合语义化版本规范
• 确认 package.json 版本号正确
• 运行 npm run sync:version 同步版本号

---

🔄 自动化流程详解

工作流触发

当你推送符合 v*.*.* 格式的标签时，GitHub Actions 会自动启动：

触发条件: git push origin v0.1.0
工作流文件: .github/workflows/release.yml

执行步骤

Job 1: Build and Test（构建和测试）

1. 环境准备

   • 检出代码仓库
   • 设置 Node.js 20 环境
   • 启用 npm 缓存加速

2. 依赖安装

   • 使用 npm ci 安装锁定版本的依赖
   • 确保构建可重现性

3. 质量检查

   • 运行 Vitest 单元测试
   • 运行 TypeScript 类型检查
   • 运行 ESLint 代码检查

4. 构建扩展

   • 执行 npm run build
   • 自动运行 sync-version.js 同步版本号
   • 生成 dist/ 目录

5. 验证构建

   • 检查必需文件存在（manifest.json, icons 等）
   • 输出构建统计信息

6. 上传产物

   • 将 dist/ 目录作为 artifact 上传
   • 供后续 Job 使用

Job 2: Create Release（创建发布）

1. 准备工作

   • 下载构建产物
   • 提取版本号（去除 v 前缀）

2. 打包扩展

   • 创建 cloud-drive-renamer-{version}.zip
   • 包含完整的扩展文件

3. 生成变更日志

   • 自动比较当前标签与上一个标签
   • 提取提交信息生成变更列表
   • 包含安装指南和支持的网盘列表

4. 创建 Release

   • 在 GitHub 上创建正式发布
   • 附加 ZIP 文件供下载
   • 包含详细的发布说明

5. 输出摘要

   • 显示发布 URL 和下载链接
   • 提示后续操作

---

📥 发布产物

每次发布会自动生成以下文件：

GitHub Release 页面

访问：https://github.com/YOUR_USERNAME/cloud-drive-renamer/releases

包含：

• 📦 cloud-drive-renamer-{version}.zip - 完整扩展包
• 📝 自动生成的变更日志
• 📋 安装指南

安装方式

用户可以通过以下方式安装：

1. 手动安装（开发模式）

   1. 下载并解压 cloud-drive-renamer-{version}.zip
   2. 打开 Chrome，访问 chrome://extensions/
   3. 启用"开发者模式"
   4. 点击"加载已解压的扩展程序"
   5. 选择解压后的文件夹
   

2. Chrome Web Store（未来）

   • Phase 2 实施后可通过商店自动更新

---

🐛 故障排查

构建失败

问题：GitHub Actions 工作流失败

排查步骤：

1. 查看日志

   • 访问 GitHub Actions 页面
   • 点击失败的工作流
   • 查看详细错误信息

2. 本地重现

   # 按照 CI 的步骤本地执行
   npm ci
   npm run test
   npm run typecheck
   npm run lint
   npm run build
   

3. 常见原因

   • 测试失败 → 修复代码后重新提交
   • 类型错误 → 修复 TypeScript 类型
   • 依赖问题 → 更新 package-lock.json
   • 构建错误 → 检查 Vite 配置

版本号不一致

问题：不同文件中的版本号不同步

解决方案：

# 运行版本同步脚本
npm run sync:version

# 验证同步结果
cat package.json | grep version
cat manifest.json | grep version
cat src/shared/version.ts | grep APP_VERSION

标签推送失败

问题：无法推送标签或标签已存在

解决方案：

# 删除本地标签
git tag -d v0.1.0

# 删除远程标签（谨慎操作！）
git push origin --delete v0.1.0

# 重新创建标签
git tag v0.1.0
git push origin v0.1.0

---

🔐 权限和安全

GitHub Token

工作流使用 GITHUB_TOKEN 自动创建 Release：

• ✅ 自动提供：GitHub 自动为每个工作流提供 token
• ✅ 权限受限：仅能访问当前仓库
• ✅ 无需配置：无需手动设置 Secrets

工作流权限

已在 release.yml 中配置：

permissions:
  contents: write  # 允许创建 Release 和上传文件

---

🎨 版本号规范

遵循 语义化版本 规范：

格式：MAJOR.MINOR.PATCH

• MAJOR（主版本号）：不兼容的 API 修改

  • 例如：重大架构调整，移除旧功能
  • 1.0.0 → 2.0.0

• MINOR（次版本号）：向下兼容的功能性新增

  • 例如：新增云盘支持，新增重命名规则
  • 0.1.0 → 0.2.0

• PATCH（修订号）：向下兼容的问题修正

  • 例如：Bug 修复，性能优化
  • 0.1.0 → 0.1.1

预发布版本

用于测试的预发布版本：

# 创建 Beta 版本
npm version 0.2.0-beta.1

# 推送标签
git push origin v0.2.0-beta.1

---

🔄 回滚流程

如果发布后发现严重问题，可以快速回滚：

方法 1：发布修复版本（推荐）

# 1. 修复问题
# 2. 创建新的 patch 版本
npm version patch
git push origin main --tags

方法 2：删除有问题的 Release

# 1. 在 GitHub 上手动删除 Release
# 2. 删除对应的标签
git tag -d v0.2.0
git push origin --delete v0.2.0

# 3. 修复问题后重新发布
git tag v0.2.0
git push origin v0.2.0

---

🚀 下一步：Phase 2（可选）

Phase 2 将实现 Chrome Web Store 自动上传：

前置要求

1. Chrome Web Store 开发者账号

   • 注册开发者账号（一次性 $5 费用）
   • 手动发布扩展至少一次

2. Google Cloud Project

   • 创建项目并启用 Chrome Web Store API
   • 配置 OAuth 2.0 凭证

3. 获取 API 凭证

   • Client ID
   • Client Secret
   • Refresh Token

实施步骤

详细步骤请参考：

• Chrome Web Store API 文档
• chrome-webstore-upload 文档

---

📞 获取帮助

常见问题

• 📖 查看 GitHub Actions 文档
• 🔧 查看 项目 Issues

报告问题

如果遇到发布流程的问题，请创建 Issue 并包含：

• ✅ 错误信息和日志
• ✅ 执行的命令
• ✅ GitHub Actions 工作流链接
• ✅ 本地环境信息（Node.js 版本等）

---

📊 发布统计

成功指标

• ⏱️ 发布时间：约 3-5 分钟（从推送标签到发布完成）
• 🎯 成功率目标：> 95%
• 🔄 发布频率：根据需要（建议每周或双周）

监控

定期检查：

• GitHub Actions 工作流成功率
• Release 下载量
• 用户反馈和问题报告

---

🎉 总结

现在你的项目已配置完整的自动化发布流程！

只需 3 步即可发布新版本：

1. 更新版本号 (npm version patch/minor/major)
2. 推送标签 (git push origin --tags)
3. 等待自动化流程完成 ✅

祝发布顺利！ 🚀