【GitLab/CI】前端 CI

整体流程概览（流水线高层）

1. 开发者把代码 push / open MR → 触发 GitLab Pipeline。
2. Pipeline 按 stages（例如 install → lint → test → build → deploy）顺序执行，每个 stage 内的 job 并行。
3. Runner（你为项目/组配置的）拉取镜像或启动容器，执行 job 的 before_script / script；job 可以产出 artifacts（构建产物）并写入 cache（依赖缓存）。
4. 若某一步失败，CI 报红并把日志返回给 MR；成功后可触发部署（到测试/预发布/生产），或生成 Review App。

典型前端流水线（各阶段目的）

• prepare（可选）：准备环境、注入 secrets、生成 .npmrc、写 CA 等。
• install：安装依赖（pnpm / npm / yarn），做 lockfile 校验（--frozen-lockfile）。
• lint：静态代码检查（eslint 等）。快速失败，减少无效构建。
• test：单元/集成测试（Jest、Vitest 等）。
• build：生产构建（如 pnpm build），生成 dist。
• e2e（可选）：端到端测试（Cypress / Playwright）。通常需要独立环境或 service。
• deploy：将 dist 发布到测试/生产环境。

必备与常见的 .gitlab-ci.yml 配置项（逐条解释）

下面用示例同时讲解每个配置的作用。

stages:- prepare- install- lint- test- build- deployvariables:FRONTEND_DIR: frontendPNPM_STORE_DIR: .pnpm-storeNODE_ENV: productionimage: node:20cache:key: ${CI_COMMIT_REF_SLUG}-pnpm-storepaths:- .pnpm-store- frontend/node_modulesbefore_script:- cd ${FRONTEND_DIR}install:stage: installscript:- npm -g pnpm@7- pnpm config set store-dir ${PNPM_STORE_DIR}- pnpm install --frozen-lockfilecache:policy: pull-pushlint:stage: lintscript:- pnpm linttest:stage: testscript:- pnpm test --reporter=jest-junitartifacts:reports:junit: junit.xmlwhen: alwaysbuild:stage: buildscript:- pnpm buildartifacts:paths:- distexpire_in: 1 weekdeploy:stage: deployscript:- ./deploy-script.shonly:- main

解释（按配置项）：

1. stages：流水线的阶段顺序。stage 的顺序决定执行顺序，stage 内 job 并行。

2. variables：定义 pipeline 内的环境变量（可在 job 中引用）。放敏感信息不要放在这里，要放 GitLab 的 CI/CD Variables。

3. image：Runner 在执行 job 时用的容器镜像（Docker/Kubernetes executor 会拉这个镜像）。选稳定的 Node 镜像，或自建含依赖的镜像。镜像下载的策略：

   • never： 当使用这个策略，会禁止Gitlab Runner从Docker hub或者其他地方下拉镜像，只能使用自己手动下拉的镜像
   • if-not-present： 当使用这个策略，Runner会先检测本地是否有镜像，有的话使用该镜像，如果没有再去下拉。这个策略如果再配合定期删除镜像，就能达到比较好的效果
   • always： 这个是gitlab-ci默认使用的策略，即每一次都是重新下拉镜像，导致的结果就是比较耗时间

4. cache：用于存依赖等来加速后续 job。key 决定缓存隔离粒度（按分支、commit、共享等）。paths 列出要缓存的目录。policy 可设 pull-push（默认），或 pull。

5. before_script：在每个 job 执行实际 script 前会执行的命令（可复用），常用于 cd、设置环境、解码 secrets。after_script同理。

6. script：job 的要执行的命令（必须有）。很多错误就在这里可以看到。

7. artifacts：job 成功后保留的文件供下个 stage 使用或供下载（如 dist、测试报告、coverage）。expire_in 控制保存时间。

8. only/except 或 rules：控制何时触发 job。rules 更灵活，推荐使用 rules 替代 only/except。

9. artifacts.reports：特殊用途的 artifacts，比如 junit 测试报告或 coverage，可在 GitLab UI 显示测试结果。

10. when：controls when artifact is uploaded (always, on_success, on_failure)。

11. needs：允许跳过 stage 顺序，直接使用另一个 job 的 artifacts，能加速 pipeline（注意并发与资源）。

12. services：只想其他 docker 镜像，这些镜像会合 image 制定的镜像绑定。

13. retry, timeout, parallel：job 重试次数、最长时长、并行 matrix（并发运行多个相同 job）。

lockfile 与可重复构建

• 强制使用 --frozen-lockfile（pnpm）或 npm ci（npm）可保证 CI 严格按锁文件安装。若本地修改了 package.json 却没更新锁文件，CI 会失败——这是好事，防止无意识升级。
• 若想在 CI 自动更新 lockfile（不推荐），可在临时 job 使用 pnpm install --no-frozen-lockfile，并把新的 lockfile 提交/创建 MR。不过优先流程应是本地开发者更新并提交锁文件。

在 GitLab 上如何配置（UI 操作）

0. 编写自己项目的 .gitlab-ci.yml 。包含想要执行的各种指令（代码检查、自动打包、自动部署等）。

1. 项目 -> 构建 -> 流水线 -> 新流水线：

   • 可以创建流水线。

2. 项目 → Settings → CI/CD → Variables：

   • 添加变量：Key、Value，并设置 Protected（仅在受保护分支/Tags 使用）、Masked（在 job 日志中隐藏）。
   • 用于 token（例如 PRIV_TOKEN）、CA（建议用 base64 存储 INTERNAL_CA_B64）、其他 secret。

3. Pipeline 页面：可以查看最近的 pipeline，点击 pipeline id 查看各 job 日志、artifacts、测试报告。修改.gitlab-ci.yml文件，直接修改、增添远程仓库项目内容，合并请求等操作也会自动触发流水线。或者手动点击 run pipeline 触发流水线。

4. Jobs 页面：查看某个 job 的详细日志；可在 job 上点 “Retry” 重新跑，或点击 Debug（如果 runner 支持交互调试）。pipeline 包含多个 stage 阶段，每个 stage 阶段包含多个 job 作业。

5. Environments / Releases：用于管理部署环境（staging/prod），可以把 Deploy job 绑定到环境，并在 GitLab UI 看到部署历史。

6. Protected Branches：设置哪些分支能触发 Protected CI（配合 Protected variables 使用）。