镜像自地址
https://github.com/lhly/search-syntax-pro.git
已同步 2026-10-20 22:37:48 +08:00
6de39fe131
- 新增GitHub Actions工作流实现自动化构建和发布 - 添加版本一致性检查脚本 - 更新package.json和manifest.json版本至1.5.0 - 删除旧版图标文件 - 完善README文档，添加发布流程说明 - 添加CICD_SETUP.md配置指南
280 行
7.6 KiB
Markdown
280 行
7.6 KiB
Markdown
# CI/CD 自动化部署配置指南
|
||
|
||
本文档说明 SearchSyntax Pro 项目的自动化构建和发布流程。
|
||
|
||
## 📋 概览
|
||
|
||
- **CI/CD 平台**：GitHub Actions
|
||
- **工作流文件**：`.github/workflows/release.yml`
|
||
- **当前版本**：v1.5.0
|
||
- **触发方式**：Tag 推送、Main 分支推送、Pull Request
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 发布新版本（完整流程）
|
||
|
||
```bash
|
||
# 1. 确保在 main 分支且工作区干净
|
||
git checkout main
|
||
git pull origin main
|
||
|
||
# 2. 更新版本号（会自动创建 commit 和 tag）
|
||
npm version patch # 1.5.0 -> 1.5.1 (bug 修复)
|
||
npm version minor # 1.5.0 -> 1.6.0 (新功能)
|
||
npm version major # 1.5.0 -> 2.0.0 (破坏性更新)
|
||
|
||
# 3. 推送代码和标签到 GitHub
|
||
git push origin main
|
||
git push origin --tags
|
||
|
||
# 4. 监控 GitHub Actions 构建状态
|
||
# 访问：https://github.com/lhly/search-syntax-pro/actions
|
||
|
||
# 5. 等待构建完成（约 3-5 分钟）
|
||
|
||
# 6. 审查并发布 Release
|
||
# 访问：https://github.com/lhly/search-syntax-pro/releases
|
||
# - 检查 ZIP 文件完整性
|
||
# - 补充发布说明（可选）
|
||
# - 点击 "Publish release" 发布
|
||
|
||
# 7. 上传到 Chrome Web Store
|
||
# - 下载 ssp-v{version}.zip
|
||
# - 登录 Chrome Web Store Developer Console
|
||
# - 上传新版本并提交审核
|
||
```
|
||
|
||
## 🔧 工作流说明
|
||
|
||
### 触发条件
|
||
|
||
| 触发事件 | 条件 | 执行内容 |
|
||
|---------|------|---------|
|
||
| **Tag 推送** | `v*.*.*` | 完整流程：构建 → 测试 → 打包 → 发布 |
|
||
| **Main 推送** | `push to main` | CI 验证：构建 → 测试（不发布） |
|
||
| **Pull Request** | `PR to main` | 质量检查：构建 → 测试 |
|
||
|
||
### 工作流程图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ GitHub Actions Pipeline │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Job 1: build-and-test │
|
||
│ ├─ Checkout code │
|
||
│ ├─ Setup Node.js 18.x │
|
||
│ ├─ Cache dependencies │
|
||
│ ├─ Install dependencies (npm ci) │
|
||
│ ├─ Type check (tsc --noEmit) │
|
||
│ ├─ Lint (eslint) │
|
||
│ ├─ Run tests (jest) │
|
||
│ ├─ Verify version consistency ✅ │
|
||
│ ├─ Build extension (npm run build) │
|
||
│ └─ Upload build artifacts │
|
||
│ │
|
||
│ Job 2: package (需要 Job 1 成功) │
|
||
│ ├─ Download build artifacts │
|
||
│ ├─ Create ZIP package │
|
||
│ └─ Upload ZIP artifact │
|
||
│ │
|
||
│ Job 3: release (仅 Tag 触发，需要 Job 2 成功) │
|
||
│ ├─ Download ZIP package │
|
||
│ ├─ Extract version info │
|
||
│ ├─ Generate changelog │
|
||
│ └─ Create GitHub Release (草稿) 📦 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 📦 构建产物
|
||
|
||
### Artifacts（保留 90 天）
|
||
|
||
- **dist-{sha}**：构建后的扩展文件
|
||
- **extension-package-{sha}**：打包好的 ZIP 文件
|
||
|
||
### GitHub Release（永久保存）
|
||
|
||
- **ssp-v{version}.zip**：可直接安装的 Chrome 扩展
|
||
- 自动生成的更新日志
|
||
- 构建信息和技术细节
|
||
|
||
## ✅ 版本管理
|
||
|
||
### 版本一致性检查
|
||
|
||
项目包含自动化脚本确保版本号同步：
|
||
|
||
```bash
|
||
# 手动检查版本一致性
|
||
npm run check-version
|
||
|
||
# 或直接运行脚本
|
||
node scripts/check-version.js
|
||
```
|
||
|
||
检查内容：
|
||
- ✅ `package.json` 的 `version` 字段
|
||
- ✅ `public/manifest.json` 的 `version` 字段
|
||
- ✅ 版本号格式验证（语义化版本）
|
||
|
||
### 版本号规范
|
||
|
||
遵循语义化版本（Semantic Versioning）：
|
||
|
||
```
|
||
主版本号.次版本号.补丁版本号[-预发布标识]
|
||
|
||
例如：
|
||
- 1.5.0 (稳定版本)
|
||
- 1.5.1-beta.1 (预发布版本)
|
||
- 2.0.0-rc.1 (候选版本)
|
||
```
|
||
|
||
## 🛠️ 本地开发
|
||
|
||
### 测试 CI 流程
|
||
|
||
在推送到 GitHub 之前，可以本地验证：
|
||
|
||
```bash
|
||
# 1. 类型检查
|
||
npm run type-check
|
||
|
||
# 2. 代码检查
|
||
npm run lint
|
||
|
||
# 3. 运行测试
|
||
npm run test
|
||
|
||
# 4. 版本一致性
|
||
npm run check-version
|
||
|
||
# 5. 构建项目
|
||
npm run build
|
||
|
||
# 6. 打包扩展
|
||
npm run package
|
||
```
|
||
|
||
### 调试工作流
|
||
|
||
如果 GitHub Actions 构建失败：
|
||
|
||
1. **查看日志**：
|
||
- 访问 Actions 标签页
|
||
- 点击失败的工作流
|
||
- 查看具体失败的步骤和错误信息
|
||
|
||
2. **常见问题**：
|
||
- 版本号不一致 → 运行 `npm run check-version`
|
||
- 构建失败 → 本地运行 `npm run build` 检查
|
||
- 测试失败 → 本地运行 `npm test` 修复
|
||
- 类型错误 → 运行 `npm run type-check`
|
||
|
||
3. **重新触发**：
|
||
- 修复问题后重新推送
|
||
- 或在 Actions 页面点击 "Re-run jobs"
|
||
|
||
## 📝 最佳实践
|
||
|
||
### 发布检查清单
|
||
|
||
发布前确认：
|
||
|
||
- [ ] 代码已合并到 main 分支
|
||
- [ ] 本地测试全部通过
|
||
- [ ] 更新了 CHANGELOG 或提交信息清晰
|
||
- [ ] 版本号符合语义化规范
|
||
- [ ] 没有未提交的更改
|
||
|
||
### 版本更新策略
|
||
|
||
- **补丁版本**（patch）：Bug 修复、文档更新、小优化
|
||
- **次版本**（minor）：新功能、功能增强、非破坏性更改
|
||
- **主版本**（major）：破坏性更改、重大架构调整
|
||
|
||
### Git 标签规范
|
||
|
||
```bash
|
||
# ✅ 正确的标签格式
|
||
git tag v1.5.0
|
||
git tag v2.0.0-beta.1
|
||
|
||
# ❌ 错误的标签格式
|
||
git tag 1.5.0 # 缺少 'v' 前缀
|
||
git tag version1.5 # 不符合语义化版本
|
||
```
|
||
|
||
## 🔒 安全性
|
||
|
||
### 权限配置
|
||
|
||
工作流使用的权限：
|
||
|
||
- `contents: write` - 创建 Release 和上传文件
|
||
- `pull-requests: read` - 读取 PR 信息
|
||
|
||
### Token 使用
|
||
|
||
- 使用 GitHub 自动提供的 `GITHUB_TOKEN`
|
||
- 无需手动配置密钥
|
||
- Token 权限限定在当前仓库
|
||
|
||
## 🚨 故障排查
|
||
|
||
### 构建失败
|
||
|
||
**问题**：构建失败，错误信息为 "dist directory not found"
|
||
|
||
**解决**：
|
||
```bash
|
||
# 检查 dist 目录是否被 gitignore
|
||
# 确保构建脚本正确执行
|
||
npm run build
|
||
ls -la dist/
|
||
```
|
||
|
||
### 版本不一致
|
||
|
||
**问题**：CI 报错 "版本号不一致"
|
||
|
||
**解决**：
|
||
```bash
|
||
# 运行版本检查脚本
|
||
npm run check-version
|
||
|
||
# 手动同步版本（如果需要）
|
||
# 编辑 public/manifest.json，将 version 改为与 package.json 一致
|
||
```
|
||
|
||
### Release 创建失败
|
||
|
||
**问题**：Tag 推送后没有创建 Release
|
||
|
||
**解决**：
|
||
1. 检查 Tag 格式是否为 `v*.*.*`
|
||
2. 查看 Actions 日志确认权限问题
|
||
3. 确保 `package` Job 成功完成
|
||
|
||
## 📚 参考资源
|
||
|
||
- [GitHub Actions 文档](https://docs.github.com/en/actions)
|
||
- [语义化版本规范](https://semver.org/lang/zh-CN/)
|
||
- [Chrome 扩展发布指南](https://developer.chrome.com/docs/webstore/publish/)
|
||
- [项目 README](../README.md)
|
||
|
||
## 🆘 获取帮助
|
||
|
||
遇到问题？
|
||
|
||
1. 查看 [GitHub Issues](https://github.com/lhly/search-syntax-pro/issues)
|
||
2. 查看工作流日志了解详细错误
|
||
3. 提交新 Issue 并附上错误日志
|
||
|
||
---
|
||
|
||
**最后更新**：2025-11-10
|
||
**维护者**：SearchSyntax Pro Team
|