search-syntax-pro/.github/CICD_SETUP.md

CI/CD 自动化部署配置指南

本文档说明 SearchSyntax Pro 项目的自动化构建和发布流程。

📋 概览

• CI/CD 平台：GitHub Actions
• 工作流文件：.github/workflows/release.yml
• 当前版本：v1.5.0
• 触发方式：Tag 推送、Main 分支推送、Pull Request

🚀 快速开始

发布新版本（完整流程）

# 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 扩展
• 自动生成的更新日志
• 构建信息和技术细节

✅ 版本管理

版本一致性检查

项目包含自动化脚本确保版本号同步：

# 手动检查版本一致性
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 之前，可以本地验证：

# 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 标签规范

# ✅ 正确的标签格式
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"

解决：

# 检查 dist 目录是否被 gitignore
# 确保构建脚本正确执行
npm run build
ls -la dist/

版本不一致

问题：CI 报错 "版本号不一致"

解决：

# 运行版本检查脚本
npm run check-version

# 手动同步版本（如果需要）
# 编辑 public/manifest.json，将 version 改为与 package.json 一致

Release 创建失败

问题：Tag 推送后没有创建 Release

解决：

1. 检查 Tag 格式是否为 v*.*.*
2. 查看 Actions 日志确认权限问题
3. 确保 package Job 成功完成

📚 参考资源

• GitHub Actions 文档
• 语义化版本规范
• Chrome 扩展发布指南
• 项目 README

🆘 获取帮助

遇到问题？

1. 查看 GitHub Issues
2. 查看工作流日志了解详细错误
3. 提交新 Issue 并附上错误日志

---

最后更新：2025-11-10 维护者：SearchSyntax Pro Team