整体流程概览（流水线高层）
- 开发者把代码 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 配置项（逐条解释）
下面用示例同时讲解每个配置的作用。
yaml
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。不过优先流程应是本地开发者更新并提交锁文件。
在 GitLab 上如何配置（UI 操作）
-
编写自己项目的
.gitlab-ci.yml。包含想要执行的各种指令（代码检查、自动打包、自动部署等）。 -
项目 -> 构建 -> 流水线 -> 新流水线：
- 可以创建流水线。
-
项目 → Settings → CI/CD → Variables：
- 添加变量：
Key、Value，并设置 Protected（仅在受保护分支/Tags 使用）、Masked（在 job 日志中隐藏）。 - 用于 token（例如
PRIV_TOKEN）、CA（建议用 base64 存储INTERNAL_CA_B64）、其他 secret。
- 添加变量：
-
Pipeline 页面：可以查看最近的 pipeline，点击 pipeline id 查看各 job 日志、artifacts、测试报告。修改.gitlab-ci.yml文件，直接修改、增添远程仓库项目内容，合并请求等操作也会自动触发流水线。或者手动点击
run pipeline触发流水线。 -
Jobs 页面：查看某个 job 的详细日志；可在 job 上点 "Retry" 重新跑，或点击 Debug（如果 runner 支持交互调试）。pipeline 包含多个 stage 阶段，每个 stage 阶段包含多个 job 作业。
-
Environments / Releases：用于管理部署环境（staging/prod），可以把 Deploy job 绑定到环境，并在 GitLab UI 看到部署历史。
-
Protected Branches：设置哪些分支能触发 Protected CI（配合 Protected variables 使用）。