当前位置：首页 > news >正文

完整教程：【GitLab/CI】前端 CI

news 2026/3/26 23:41:20

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

开发者把代码 push / open MR → 触发 GitLab Pipeline。
Pipeline 按 stages（例如 install → lint → test → build → deploy）顺序执行，每个 stage 内的 job 并行。
Runner（你为项目/组配置的）拉取镜像或启动容器，执行 job 的 before_script / script；job 可以产出 artifacts（构建产物）并写入 cache（依赖缓存）。
若某一步失败，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
- deploy
variables:
FRONTEND_DIR: frontend
PNPM_STORE_DIR: .pnpm-store
NODE_ENV: production
image: node:20
cache:
key: ${CI_COMMIT_REF_SLUG}-pnpm-store
paths:
- .pnpm-store
- frontend/node_modules
before_script:
- cd ${FRONTEND_DIR}
install:
stage: install
script:
- npm -g pnpm@7
- pnpm config set store-dir ${PNPM_STORE_DIR}
- pnpm install --frozen-lockfile
cache:
policy: pull-push
lint:
stage: lint
script:
- pnpm lint
test:
stage: test
script:
- pnpm test --reporter=jest-junit
artifacts:
reports:
junit: junit.xml
when: always
build:
stage: build
script:
- pnpm build
artifacts:
paths:
- dist
expire_in: 1 week
deploy:
stage: deploy
script:
- ./deploy-script.sh
only:
- main

解释（按部署项）：

stages：流水线的阶段顺序。stage 的顺序决定执行顺序，stage 内 job 并行。
variables：定义 pipeline 内的环境变量（可在 job 中引用）。放敏感信息不要放在这里，要放 GitLab 的 CI/CD Variables。
image：Runner 在执行 job 时用的容器镜像（Docker/Kubernetes executor 会拉这个镜像）。选稳定的 Node 镜像，或自建含依赖的镜像。镜像下载的策略：
- never：当使用这个策略，会禁止Gitlab Runner从Docker hub或者其他地方下拉镜像，只能使用自己手动下拉的镜像
- if-not-present：当利用这个策略，Runner会先检测本地是否有镜像，有的话使用该镜像，假如没有再去下拉。这个策略如果再配合定期删除镜像，就能达到比较好的效果
- always：这个是gitlab-ci默认使用的策略，即每一次都是重新下拉镜像，导致的结果就是比较耗时间
cache：用于存依赖等来加速后续 job。key 决定缓存隔离粒度（按分支、commit、共享等）。paths 列出要缓存的目录。policy 可设 pull-push（默认），或 pull。
before_script：在每个 job 执行实际 script 前会执行的命令（可复用），常用于 cd、设置环境、解码 secrets。after_script同理。
script：job 的要执行的命令（必须有）。很多错误就在这里可以看到。
artifacts：job 成功后保留的文件供下个 stage 使用或供下载（如 dist、测试报告、coverage）。expire_in 控制保存时间。
only/except 或 rules：控制何时触发 job。rules 更灵活，推荐使用 rules 替代 only/except。
artifacts.reports：特殊用途的 artifacts，比如 junit 测试报告或 coverage，可在 GitLab UI 显示测试结果。
when：controls when artifact is uploaded (always, on_success, on_failure)。
needs：允许跳过 stage 顺序，直接使用另一个 job 的 artifacts，能加速 pipeline（注意并发与资源）。
services：只想其他 docker 镜像，这些镜像会合 image 制定的镜像绑定。
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。不过优先流程应是本地开发者更新并提交锁文件。