# 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