镜像自地址
https://github.com/lhly/cloud-drive-renamer.git
已同步 2026-10-20 13:47:47 +08:00
e94089c9ad
- 添加项目基础配置文件和构建工具配置 - 实现夸克网盘批量重命名核心功能 - 添加多语言支持和国际化配置 - 实现重命名规则引擎和多种重命名规则 - 添加测试框架和测试用例 - 配置CI/CD自动化流程 - 添加文档和快速入门指南
407 行
8.7 KiB
Markdown
407 行
8.7 KiB
Markdown
# 📦 发布流程指南
|
||
|
||
> CloudDrive Renamer Chrome 扩展自动化发布流程
|
||
|
||
---
|
||
|
||
## 🎯 概览
|
||
|
||
本项目已配置完整的 CI/CD 自动化发布流程，通过 GitHub Actions 实现：
|
||
|
||
- ✅ **自动构建**：推送标签即触发构建
|
||
- ✅ **质量保证**：自动运行测试和代码检查
|
||
- ✅ **自动打包**：生成可直接安装的 ZIP 文件
|
||
- ✅ **自动发布**：创建 GitHub Release 并附加下载链接
|
||
- 📋 **变更日志**：自动生成版本间的变更记录
|
||
|
||
---
|
||
|
||
## 🚀 快速发布
|
||
|
||
### 标准发布流程（3 步）
|
||
|
||
```bash
|
||
# 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 页面查看
|
||
```
|
||
|
||
### 手动版本号控制
|
||
|
||
```bash
|
||
# 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 会自动启动：
|
||
|
||
```yaml
|
||
触发条件: 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. **本地重现**
|
||
```bash
|
||
# 按照 CI 的步骤本地执行
|
||
npm ci
|
||
npm run test
|
||
npm run typecheck
|
||
npm run lint
|
||
npm run build
|
||
```
|
||
|
||
3. **常见原因**
|
||
- 测试失败 → 修复代码后重新提交
|
||
- 类型错误 → 修复 TypeScript 类型
|
||
- 依赖问题 → 更新 `package-lock.json`
|
||
- 构建错误 → 检查 Vite 配置
|
||
|
||
### 版本号不一致
|
||
|
||
**问题**：不同文件中的版本号不同步
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 运行版本同步脚本
|
||
npm run sync:version
|
||
|
||
# 验证同步结果
|
||
cat package.json | grep version
|
||
cat manifest.json | grep version
|
||
cat src/shared/version.ts | grep APP_VERSION
|
||
```
|
||
|
||
### 标签推送失败
|
||
|
||
**问题**：无法推送标签或标签已存在
|
||
|
||
**解决方案**：
|
||
|
||
```bash
|
||
# 删除本地标签
|
||
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` 中配置：
|
||
|
||
```yaml
|
||
permissions:
|
||
contents: write # 允许创建 Release 和上传文件
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 版本号规范
|
||
|
||
遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范：
|
||
|
||
### 格式：`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`
|
||
|
||
### 预发布版本
|
||
|
||
用于测试的预发布版本：
|
||
|
||
```bash
|
||
# 创建 Beta 版本
|
||
npm version 0.2.0-beta.1
|
||
|
||
# 推送标签
|
||
git push origin v0.2.0-beta.1
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 回滚流程
|
||
|
||
如果发布后发现严重问题，可以快速回滚：
|
||
|
||
### 方法 1：发布修复版本（推荐）
|
||
|
||
```bash
|
||
# 1. 修复问题
|
||
# 2. 创建新的 patch 版本
|
||
npm version patch
|
||
git push origin main --tags
|
||
```
|
||
|
||
### 方法 2：删除有问题的 Release
|
||
|
||
```bash
|
||
# 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 文档](https://developer.chrome.com/docs/webstore/using_webstore_api/)
|
||
- [chrome-webstore-upload 文档](https://github.com/fregante/chrome-webstore-upload)
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
### 常见问题
|
||
|
||
- 📖 查看 [GitHub Actions 文档](https://docs.github.com/en/actions)
|
||
- 🔧 查看 [项目 Issues](https://github.com/YOUR_USERNAME/cloud-drive-renamer/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. 等待自动化流程完成 ✅
|
||
|
||
**祝发布顺利！** 🚀
|