Vue/React 项目怎么自动部署？声明式流水线配置实战

摘要：

Vue 和 React 项目要落地自动部署，关键是让代码提交后自动完成安装、构建、测试和发布。本文以腾讯云 CNB 的声明式流水线为例，手把手给出 .cnb.yml 配置，覆盖从代码推送到上线的完整流程。

一、前端自动部署要解决什么

一个 Vue 或 React 项目从代码到上线，通常会经过几个固定步骤：拉取依赖、执行构建、跑测试、打包产物、把产物推送到服务器或静态资源托管。手动执行这些步骤不仅容易出错，也难以保证每次发布的一致性。

自动部署要做的，就是把这些步骤串成一条流水线，让代码一旦提交到指定分支，就能自动走完后续所有环节。对前端团队来说，理想的自动部署至少满足三点：配置简单，一份文件就能描述清楚全流程；环境统一，构建和发布都在标准化的容器里执行；反馈及时，每一步的结果都能快速看到。

腾讯云 CNB 用一份 .cnb.yml 声明式配置文件就能承载这条流水线，下面从环境准备到完整配置逐步展开。

二、环境与前置准备

在开始配置之前，需要先把项目的基础信息确认清楚。

第一，项目需要有标准的 package.json，并锁定依赖版本。Vue 项目通常用 npm ci 或 yarn install 安装依赖，React 项目同理。建议在仓库中提交 package-lock.json 或 yarn.lock，保证每次安装的依赖版本一致。

第二，明确构建命令和产物目录。Vue 项目通过 Vite 或 Vue CLI 构建，产物一般输出到 dist 目录；React 项目（如 Create React App）产物通常在 build 目录。这条流水线会用到 npm run build 这类命令，需要提前在 package.json 的 scripts 里定义好。

第三，确定部署目标。前端静态产物常见的去向包括对象存储（如腾讯云 COS）、容器镜像仓库，或者通过 Kubernetes 部署到集群。本文以把构建产物推送到制品库并部署到容器环境为例进行演示。

第四，敏感信息用密钥管理。部署过程中往往涉及镜像仓库地址、访问凭证等敏感信息，CNB 支持通过环境变量和密钥仓库安全存储，避免把密钥硬编码进配置文件。

三、理解 .cnb.yml 的结构

CNB 的流水线配置围绕 Pipeline、Stage、Job 三层结构展开。理解这三层关系，是写好配置的前提。

• Pipeline（流水线）：由一次触发事件产生的一次完整执行过程。配置里最外层的分支名（如 main）下面挂的就是流水线。
• Stage（阶段）：流水线中的执行单元，同一 Stage 内的多个 Job 会并行执行，不同 Stage 之间串行推进。
• Job（任务）：最小执行单元，在指定的 Docker 容器中运行，通过 script 字段定义要执行的命令。

一个 Job 里可以指定运行镜像，CNB 官方提供了常用语言的预置镜像，前端项目直接用 node 镜像即可。下面这份配置就建立在这个三层结构之上。

四、Vue 项目自动部署配置实战

先看 Vue 项目的完整配置。这份配置在代码推送到 main 分支时触发，依次完成依赖安装、代码构建、单元测试和产物推送。

main:
  push:
    - name: vue-ci-cd
      services:
        - docker
      stages:
        - name: install
          jobs:
            - name: install-deps
              image: node:18
              script: npm ci

        - name: build
          jobs:
            - name: build-dist
              image: node:18
              script: npm run build

        - name: test
          jobs:
            - name: run-test
              image: node:18
              script: npm run test

        - name: deploy
          jobs:
            - name: build-and-push
              image: docker:latest
              script: |
                docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT} .
                docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT}

这份配置里，main 表示匹配主干分支，push 表示代码推送时触发。四个 Stage 串行执行：安装、构建、测试、部署。每个 Job 都指定了运行镜像，构建和测试用 node:18，镜像打包与推送用 docker 镜像。因为涉及 docker build 和 docker push，Pipeline 顶层声明了 services: [docker] 来开启 dind 环境；推送到 CNB 制品库时无需手动 docker login，平台会内置触发者的访问凭据。镜像地址用 ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE} 指向当前仓库的 Docker 制品库，再用 ${CNB_COMMIT_SHORT} 提交号打标签，便于版本追溯。

如果产物是纯静态文件，也可以把 deploy 阶段换成上传到对象存储，例如用对应的命令行工具把 dist 目录同步到 COS 存储桶，再配合 CDN 完成分发。

五、React 项目自动部署配置实战

React 项目的结构和 Vue 基本一致，差别主要在构建命令和产物目录上。下面是一份 React 项目的配置示例，并在 pull_request 事件下额外挂了一条轻量检查流水线。

main:
  push:
    - name: react-ci-cd
      services:
        - docker
      stages:
        - name: install
          jobs:
            - name: install-deps
              image: node:18
              script: npm ci

        - name: build
          jobs:
            - name: build-dist
              image: node:18
              script: npm run build

        - name: test
          jobs:
            - name: run-test
              image: node:18
              script: npm run test

        - name: deploy
          jobs:
            - name: build-and-push
              image: docker:latest
              script: |
                docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT} .
                docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT}

  pull_request:
    - name: react-pr-check
      stages:
        - name: install
          jobs:
            - name: install-deps
              image: node:18
              script: npm ci
        - name: build
          jobs:
            - name: build-dist
              image: node:18
              script: npm run build
        - name: test
          jobs:
            - name: run-test
              image: node:18
              script: npm run test

这份配置做了两件事。push 到 main 时走完整的安装、构建、测试、镜像推送流程（同样声明 services: [docker] 并用 CNB 内置地址变量推送）；发起 pull_request 时只跑安装、构建和测试，作为代码合入前的质量门禁，不触发实际的部署动作。

六、让部署更稳的几个增强项

基础流水线跑通之后，可以根据团队需要叠加几个增强项。

一是分支策略。特性分支不必走完整部署，可以只跑构建和测试，把发布动作保留给 main 分支。CNB 的分支匹配支持 glob 模式，像 feature/* 这样的分支可以单独配置一套更轻量的流程。

二是手动触发发布。生产环境的发布可以改用 web_trigger 手动触发，避免代码一推送就自动上线，给发布动作加一道人工确认。

三是缓存加速。把依赖安装环节产生的缓存保留下来，下次构建时复用，能明显缩短 npm ci 的耗时，尤其在 Monorepo 这类依赖体量大的项目里收益更突出。

四是环境变量与密钥。前面环境准备阶段已提到，镜像仓库地址、部署目标等配置通过环境变量注入、敏感凭证放进密钥仓库；在增强阶段可以进一步把不同环境的变量拆分管理，做到配置与代码彻底分离。

五是失败处理与通知。流水线任一 Stage 失败都会中断并保留对应阶段的日志，方便快速定位。团队还可以把构建结果通知到企业微信群，让提交者和相关同学在流水线失败或发布完成时第一时间收到反馈，缩短问题响应时间。

七、验证流水线是否按预期工作

配置写完之后，建议在真实仓库里跑一遍验证。可以先向 main 分支推送一次改动，观察流水线是否按 install → build → test → deploy 的顺序依次执行。重点确认三件事：依赖安装是否复用了预期版本、构建产物是否输出到正确目录、镜像是否成功打上提交号标签并推送到制品库。

如果某一步失败，可以直接点开对应 Stage 和 Job 的日志查看报错。常见的问题包括依赖版本锁定文件缺失导致 npm ci 失败、构建命令与 package.json 里的脚本名不一致、镜像标签变量没有正确解析等。把这些细节在第一条流水线里调通，后续复制到其它项目时就会顺畅很多。

八、从提交到上线的完整链路

把上面的配置串起来，一次代码提交会经历这样的链路：开发者把代码推送到 main 分支，CNB 监听到 push 事件后拉起流水线；先在 node 容器里执行 npm ci 安装依赖，再执行 npm run build 产出构建产物，随后运行测试；测试通过后进入部署阶段，把产物打包成 Docker 镜像并打上提交号标签；镜像推送到 CNB 制品库，由下游容器服务拉取并完成滚动更新，最终上线。

整个过程全部由 .cnb.yml 声明式描述，环境统一、步骤透明，每一步的执行结果都能在流水线上实时看到，提交者和相关同学不用盯着终端，也能掌握发布进度。

九、小结

Vue 和 React 项目的自动部署，核心是把安装、构建、测试、发布串成一条声明式流水线。腾讯云 CNB 用一份 .cnb.yml 就能承载这套流程，通过 Pipeline、Stage、Job 三层结构组织任务，用分支匹配和事件触发区分不同场景，再叠加缓存、密钥管理和手动触发等增强项，让前端团队不用维护复杂的调度脚本，也能把代码推送平滑地接到自动上线上。

如果你想给自己的 Vue 或 React 项目接上自动部署，可以先在 腾讯云 CNB 上建一个示例仓库，把这份 .cnb.yml 放进去跑通第一条流水线，再按团队的实际分支策略和部署目标逐步调整。