整体架构#

流水线分两个阶段：

1. build：在 node:22-alpine 镜像里执行 npm ci 和 npm run build，产出 dist/ 并作为 artifact 保留 7 天。
2. deploy：在 alpine:3.20 里安装 rsync，执行 deploy/deploy.sh，把 artifact 同步到挂载目录。

只有推送到 dev 分支 才会触发（rules: if: $CI_COMMIT_BRANCH == "dev"）。

GitLab 与 Runner 前置配置#

流水线能跑起来，需要先准备好 GitLab 实例、代码仓库 和 Runner。下面按实际搭建顺序说明（自托管 GitLab + 与 1Panel 同机的 Runner）。

1
git remote add origin http://<gitlab-host>/<group>/vue-spa.git
2
git push -u origin dev

1
# 添加 GitLab 官方源（以 Debian/Ubuntu 为例，其他发行版见官方文档）
2
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
3
sudo apt-get install gitlab-runner
4

5
# 确认 Runner 用户能访问 Docker（executor 选 docker 时需要）
6
sudo usermod -aG docker gitlab-runner

1
sudo gitlab-runner register

1
GitLab instance URL: http://<gitlab-host>:9091
2
Registration/Authentication token: <从 GitLab 页面复制的 token>
3
Description: vue-spa-deploy-runner
4
Tags: docker,deploy          # 可留空
5
Executor: docker
6
Default Docker image: node:22-alpine

1
[[runners]]
2
  name = "vue-spa-deploy-runner"
3
  url = "http://<gitlab-host>:9091"
4
  token = "<runner-token>"
5
  executor = "docker"
6
  [runners.docker]
7
    image = "node:22-alpine"
8
    volumes = ["/cache"]

1
sudo gitlab-runner verify    # 应显示 runner is alive
2
sudo gitlab-runner list      # 列出已注册 runner

1
sudo gitlab-runner restart
2
sudo systemctl status gitlab-runner

.gitlab-ci.yml 要点#

仓库根目录的 .gitlab-ci.yml 是入口，和项目当前配置大致对应如下：

1
stages:
2
  - build
3
  - deploy
4

5
variables:
6
  NODE_VERSION: "22"
7
  NPM_CONFIG_CACHE: "$CI_PROJECT_DIR/.npm"
8
  VITE_API_BASE_URL: "/api"
9
  DEPLOY_PATH: "/deploy-target"
10

11
build:
12
  stage: build
13
  image: node:${NODE_VERSION}-alpine
14
  cache:
15
    key: "${CI_COMMIT_REF_SLUG}-npm"
16
    paths:
17
      - .npm/
18
      - node_modules/
19
  script:
20
    - npm ci
21
    - npm run build
22
  artifacts:
23
    paths:
24
      - dist/
25
    expire_in: 7 days
26
  rules:
27
    - if: $CI_COMMIT_BRANCH == "dev"
28

29
deploy:
30
  stage: deploy
31
  image: alpine:3.20
32
  needs:
33
    - job: build
34
      artifacts: true
35
  before_script:
36
    - apk add --no-cache rsync
37
  script:
38
    - chmod +x deploy/deploy.sh
39
    - ./deploy/deploy.sh
40
  environment:
41
    name: production
42
    url: $DEPLOY_URL
43
  rules:
44
    - if: $CI_COMMIT_BRANCH == "dev"

几个值得留意的细节：

• VITE_API_BASE_URL: "/api" 在 CI 变量里写死为相对路径，生产环境由 Nginx 把 /api/ 反代到后端，前端代码里不需要写死后端 IP。
• cache 缓存 .npm/ 和 node_modules/，按分支 slug 分 key，重复构建会快不少。
• needs + artifacts 让 deploy 只等 build 的 dist/，两阶段职责清晰。
• environment.url: $DEPLOY_URL 在 GitLab 流水线页面可以直接点链接访问部署结果（需在 Variables 里配置）。

同机部署的关键：Runner Docker 卷挂载#

如果 Runner 用 Docker executor，Job 跑在容器里，默认看不到宿主机文件系统。
本方案的做法是：把 1Panel 站点根目录挂进容器，映射为 /deploy-target。

注册 Runner 后，编辑 /etc/gitlab-runner/config.toml，在对应 [[runners]] 的 [runners.docker] 下增加站点卷挂载：

1
[[runners]]
2
  name = "vue-spa-deploy-runner"
3
  url = "http://<gitlab-host>:9091"
4
  executor = "docker"
5
  [runners.docker]
6
    image = "node:22-alpine"
7
    volumes = ["/cache", "/1Panel/1panel/www/sites/<site-name>/index:/deploy-target:rw"]

保存后重启并验证：

1
gitlab-runner restart
2
gitlab-runner verify

含义：

这一步只需配置一次。之后每次 deploy job 写 /deploy-target/dist/，就等于直接更新了线上目录。具体路径以你 1Panel 里站点实际目录为准，可参考项目仓库 deploy/1panel-runner.md。

部署脚本：rsync 增量同步#

deploy/deploy.sh 逻辑很直白：

1
DEPLOY_PATH="${DEPLOY_PATH:-/deploy-target}"
2
TARGET="${DEPLOY_PATH%/}/dist/"
3

4
mkdir -p "${TARGET}"
5

6
rsync -av --delete \
7
  --exclude '.DS_Store' \
8
  dist/ "${TARGET}"

• --delete：删除目标目录里已不存在的旧文件，避免 hash 文件名变更后残留垃圾。
• DEPLOY_PATH 可通过 CI 变量覆盖，默认 /deploy-target 与 Runner 挂载一致。
• 若没有 rsync，脚本会回退到 cp -a（CI 里已显式安装 rsync，一般不会走到分支）。

本地想手动验证，可以先 npm run build，再指定目标路径执行同一脚本：

1
DEPLOY_PATH=/path/to/site/root ./deploy/deploy.sh

Nginx：History 路由 + API 反代#

Vue Router 使用 History 模式时，刷新子路由会 404，需要在 Nginx 里加：

1
location / {
2
    try_files $uri $uri/ /index.html;
3
}

API 不走浏览器直连后端（避免跨域、暴露内网地址），统一走 /api/ 前缀由 Nginx 反代：

1
location /api/ {
2
    proxy_pass http://<backend-host>:12989;
3
    proxy_set_header Host $host;
4
    proxy_set_header X-Real-IP $remote_addr;
5
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
6
    proxy_set_header X-Forwarded-Proto $scheme;
7
}

开发环境则由 Vite 的 VITE_PROXY_TARGET 做同样的事；生产环境靠 Nginx。
完整示例见项目仓库的 deploy/nginx.conf.example（仓库内为真实地址，博客此处已脱敏）。

环境变量与构建#

DEPLOY_URL、VITE_DEV_TOKEN 的配置入口见上文 「项目 CI/CD 变量」。

注意：Vite 的环境变量在 npm run build 时写入产物，改 Variables 或 .env.production 后必须重新跑 build，只改 Nginx 或只 redeploy 不会生效。

项目里 VITE_API_BASE_URL 开发与生产均用 /api，后端地址只出现在 Nginx / Vite 代理配置里，前端代码保持环境无关。

和「远程 SSH 部署」的对比#

同机方案特别适合内网 GitLab + 单台应用服务器的组合：不引入额外中间层，流水线就是「构建 → 拷文件 → Nginx 已有配置直接生效」。

故障排查 checklist#

1. deploy 成功但页面没更新
   看 Runner 的 volumes 是否挂对路径；宿主机上 .../index/dist/ 时间戳是否变化。

2. 刷新子路由 404
   检查 Nginx 是否有 try_files ... /index.html。

3. 接口 404 或跨域
   确认 location /api/ 的 proxy_pass 指向正确后端；前端 VITE_API_BASE_URL 是否为 /api。

4. 构建通过、环境变量不生效
   Vite 变量必须在 build stage 注入，改 Variables 后重新触发整条流水线。

5. 流水线一直 pending
   项目 Runners 页是否 online；是否勾选 Run untagged jobs；.gitlab-ci.yml 的 tags 是否与 Runner tags 匹配。

6. gitlab-runner verify 失败
   检查 GitLab URL、authentication token 是否过期、Docker 是否正常运行；必要时在 GitLab 删除旧 Runner 后重新 register。

小结#

这套 GitLab 部署把四件事串在一起：

1. GitLab + Runner 注册：实例/项目创建 Runner，executor 选 docker，并保证能接 untagged job。
2. .gitlab-ci.yml：dev 分支 push → build artifact → deploy。
3. Runner 卷挂载：容器内 /deploy-target 对应 1Panel 站点目录，免 SSH。
4. Nginx：静态资源 + History fallback + /api/ 反代。

你只管合并到 dev，流水线会自动 npm run build 并把 dist/ 推到线上。若同时保留手动 npm run build + 上传的流程，也可以作为 CI 挂掉时的兜底，两套方式产物路径一致即可。