cicd-pipeline-generator

用途

CI/CD Pipeline Generator 用于在创建或配置 CI/CD 流水线文件时提供支持，面向自动化测试、构建与部署场景。它可生成生产级流水线配置，适用于多种平台（GitHub Actions、GitLab CI、CircleCI、Jenkins），主要面向现代 Web 应用，尤其是 Node.js/Next.js 项目。

主要能力

平台选择

可根据项目需求选择 CI/CD 平台：

GitHub Actions：适合 GitHub 托管项目，原生集成
GitLab CI/CD：适合 GitLab 仓库及复杂流水线需求
CircleCI：面向 Docker 工作流与快速构建
Jenkins：适合自托管、高度可定制环境

详细平台对比、优缺点与用例建议见 references/platform-comparison.md。

流水线配置生成

按以下原则生成配置，标准阶段包括：

安装依赖：检出代码、配置运行时环境（Node.js 版本）、恢复缓存依赖、使用 npm ci 安装、缓存依赖
Lint：运行 ESLint、TypeScript 类型检查，快速失败
测试：执行单元测试与集成测试、生成覆盖率报告、上传至 Codecov/Coveralls
构建：创建生产构建、验证构建成功、存储构建产物
部署：部署到预发（develop 分支）与生产（main 分支），运行部署后冒烟测试

缓存策略

基于 package-lock.json 缓存 node_modules 与 .npm/，示例：

cache:
  key: ${{ hashFiles('package-lock.json') }}
  paths:
    - node_modules/
    - .npm/

环境变量：配置 NODE_ENV（构建时设为 production）、平台专用令牌（存为 secrets）、构建时变量。

使用方式

使用 assets/ 目录提供的模板：

GitHub Actions 模板（assets/github-actions-nodejs.yml）：多作业工作流，含 lint、test、build、deploy；可选多 Node.js 版本矩阵构建；Vercel 部署集成；产物上传；覆盖率报告。
GitLab CI 模板（assets/gitlab-ci-nodejs.yml）：多阶段流水线；依赖缓存；手动生产部署；自动预发部署；覆盖率报告。

使用模板步骤：

复制相应模板文件
放置到正确位置：GitHub Actions 为 .github/workflows/ci.yml，GitLab CI 为 .gitlab-ci.yml
自定义部署目标、环境变量与分支名
在平台设置中添加所需 secrets

部署配置示例

Vercel（GitHub Actions）：

- uses: amondnet/vercel-action@v25
  with:
    vercel-token: ${{ secrets.VERCEL_TOKEN }}
    vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
    vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
    vercel-args: '--prod'

所需 Secrets：VERCEL_TOKEN、VERCEL_ORG_ID、VERCEL_PROJECT_ID。

Netlify：

- run: |
    npm install -g netlify-cli
    netlify deploy --prod --dir=.next
  env:
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

AWS S3 + CloudFront：

- uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

- run: |
    aws s3 sync .next/static s3://${{ secrets.S3_BUCKET }}/static
    aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DIST_ID }} --paths "/*"

测试集成：配置 Jest 运行与覆盖率报告（--coverage --coverageReporters=text --coverageReporters=lcov），并用 codecov/codecov-action@v4 上传。采用快速失败策略，按 lint → test → build → deploy 顺序执行。

基于分支的工作流

功能分支/PR：仅运行 lint + test，不部署，添加测试结果 PR 评论
develop 分支：lint + test + build，自动部署到预发
main 分支：lint + test + build，部署到生产（可选手动审批），创建发布标签

适用场景

为 GitHub/GitLab 托管的 Node.js/Next.js 项目搭建自动化流水线；需要跨多平台生成配置模板；需要配置 Vercel、Netlify 或 AWS 的自动化部署；需要矩阵测试、多环境部署、定时运行、Slack 通知、安全扫描等高级配置。

工作流决策

按决策树生成流水线：选择平台（GitHub → 用对应模板；GitLab → 用对应模板；CircleCI/Jenkins → 改编 GitHub Actions 模板；不确定 → 查阅 platform-comparison.md）；确定所需阶段（始终含 Lint、Test、Build；可选安全扫描、E2E、性能测试）；选择部署平台；确定触发条件（push、PR、tag、手动）；确定所需环境变量。

最佳实践

安全：secrets 存于平台密钥管理，绝不出现在代码中；使用最小权限令牌；定期轮换；审计访问权限；不记录 secrets
性能：积极缓存依赖、并行独立作业、矩阵构建、快速失败、优化 Docker 层缓存
可靠性：固定 Node.js 精确版本（18.x）、提交 lockfile、外部服务加重试、设置合理超时（10-15 分钟）、非关键步骤用 continue-on-error
可维护性：添加注释、使用可复用工作流、保持配置 DRY、版本控制、在 README 记录所需 secrets

常见模式

多环境部署、矩阵测试、条件步骤、产物管理（actions/upload-artifact@v4 与 download-artifact@v4）。

故障排查

流水线失败：检查日志、验证环境变量与 secrets、本地测试命令、查阅平台文档
构建缓慢：检查缓存命中、并行作业、使用更快 runner、优化依赖安装
部署失败：验证令牌、检查平台状态页、查看部署日志、本地测试命令

资源

模板（assets/）：github-actions-nodejs.yml、gitlab-ci-nodejs.yml
参考文档（references/）：platform-comparison.md

示例用法

用户请求：“创建运行测试并部署到 Vercel 的 GitHub Actions 工作流”——复制模板、创建 .github/workflows/ 目录、保存为 ci.yml、更新 Vercel 凭据、添加 secrets、提交触发。

用户请求：“设置带预发和生产环境的 GitLab CI”——复制模板、保存为 .gitlab-ci.yml、配置 CI/CD 变量、审查生产手动审批、提交触发。

高级配置

支持 monorepo（paths 过滤）、定时运行（cron）、外部服务集成（Slack）、安全扫描（npm audit、Snyk）。

限制

本技能主要面向 Node.js/Next.js 项目，模板与示例以该类项目为主；其他语言与框架需要自行调整。具体安装步骤、价格、平台支持细节以官方文档为准。