Jenkins 实现 Vue 项目自动化构建与远程服务器部署

前言

在前后端分离项目开发中，Vue 项目的构建、打包、部署流程常需手动操作，效率低且易出错。本文基于 Jenkins + Node.js + Nginx 技术栈，详细讲解从环境配置、项目构建到远程服务器部署的完整流程，解决依赖冲突、路径错误、权限不足等常见问题，最终实现「代码提交 → 自动构建 → 自动部署」的全自动化流程。

一、环境准备

1.1 服务器环境

角色	系统版本	核心软件	IP 地址
Jenkins 服务器	CentOS 7	Jenkins 2.440.3 + Node.js 16.20.2	10.1.12.7
目标部署服务器	CentOS 7	Nginx 1.20.1	10.1.12.8

1.2 核心工具依赖

Jenkins 插件：NodeJS Plugin（管理 Node 版本）、Publish Over SSH（远程文件推送）、Git Plugin（代码拉取）
构建工具：Node.js 16.20.2（适配 CentOS 7 系统库）、npm 8.19.4、cnpm（国内镜像加速）
部署工具：Nginx（静态资源服务）、SSH（远程连接）

二、Jenkins 基础配置

2.1 安装必要插件

登录 Jenkins → 进入「Manage Jenkins」→「Plugins Manager」
在「Available Plugins」中搜索并安装以下插件：
- NodeJS Plugin（管理 Node.js 版本）
- Publish Over SSH（远程服务器文件推送）
- Git Plugin（从 Git 仓库拉取代码）
安装完成后重启 Jenkins（「Manage Jenkins」→「Restart Jenkins」）

2.2 配置 Node.js 环境（解决系统库兼容问题）

CentOS 7 默认系统库 GLIBC 2.17 不支持高版本 Node.js（如 v18+），需配置 Node.js 16.20.2（官方最后支持 GLIBC 2.17 的 LTS 版本）：

进入「Manage Jenkins」→「Global Tool Configuration」→「NodeJS」→「Add NodeJS」
配置参数：
- Name：NodeJS_16.20.2（自定义名称）
- Install automatically：勾选（自动下载适配版本）
- Version：选择「16.20.2」（精确到该版本）
点击「Save」保存，后续任务将使用该 Node 环境。

2.3 配置远程服务器 SSH 连接（Publish Over SSH）

实现 Jenkins 向目标服务器推送文件，需先配置 SSH 连接：

进入「Manage Jenkins」→「Configure System」→ 下拉找到「Publish over SSH」
点击「Add SSH Server」，配置目标服务器信息：
- Name：管理后台服务器（自定义名称，后续任务中引用）
- Hostname：目标服务器 IP（如 10.1.12.8）
- Username：SSH 登录用户名（如 root，需有目标目录写入权限）
- Remote Directory：留空（避免与任务路径拼接，后续在任务中配置绝对路径）
配置认证方式（二选一）：
- 密码认证：勾选「Use password authentication, or use a different key」→ 输入服务器密码
- 私钥认证：点击「Add」→ 选择「SSH Username with private key」→ 上传 Jenkins 服务器的私钥（目标服务器需提前配置公钥）
点击「Test Configuration」验证连接，显示「Success」说明配置成功。

三、Vue 项目构建脚本配置（解决依赖冲突）

3.1 新建 Jenkins 任务

点击 Jenkins 首页「New Item」→ 选择「Freestyle project」→ 输入任务名称（如 petals-web-admin）→ 点击「OK」
进入任务配置页，开始逐步配置。

3.2 配置代码拉取（Git 仓库）

在「Source Code Management」中选择「Git」
输入 Git 仓库地址（如 git@xxx.com:xxx/web-admin.git）
配置认证方式（添加 Git 账号或私钥）
选择需要构建的分支（如 */main）

3.3 配置构建环境（绑定 Node.js）

在「Build Environment」中勾选「Provide Node & npm bin/ folder to PATH」
在下拉列表中选择「NodeJS_16.20.2」（使用已配置的 Node 环境）

3.4 编写构建脚本（解决依赖冲突与打包路径问题）

在「Build Steps」中选择「Execute shell」，输入以下脚本（分步骤解释）：

bash 复制代码

# 1. 安装 cnpm（国内镜像加速，避免 npm 超时）
npm install -g cnpm --registry=https://registry.npmmirror.com

# 2. 清理旧依赖（避免版本冲突）
rm -rf node_modules package-lock.json

# 3. 打包 Vue 项目（生成 dist 目录）
npm run build

# 4. （可选）压缩 dist 目录（减少传输文件数量，提升推送速度）
cd dist && tar -zcvf ../vue-app.tar.gz ./* && cd ..

关键问题解决说明：

系统库兼容 ：使用 Node.js 16.20.2，避免 GLIBC 版本缺失 错误。

3.5 配置参数化构建（可选，动态指定部署目录）

支持构建时手动输入目标部署目录，需配置「参数化构建」：

进入任务配置 →「General」→ 勾选「This project is parameterized」
点击「Add Parameter」→ 选择「String Parameter」：
- Name：TARGET_REMOTE_DIR（参数名，后续引用）
- Default Value：/opt/web-test/assets（默认部署目录）
- Description：目标服务器部署目录（示例：/opt/web-test/assets）
后续推送配置将引用该参数，实现动态目录部署。

四、构建后操作：推送文件到目标服务器

4.1 配置文件推送规则（解决路径错误问题）

核心问题：避免文件推送到默认 /root 目录，需配置 绝对路径 并确保权限正确。

进入任务配置 →「Post-build Actions」→「Add post-build action」→ 选择「Send files or execute commands over SSH」
配置推送参数（关键步骤）：
- SSH Server：选择之前配置的「管理后台服务器」
- Source files：vue-app.tar.gz（构建生成的压缩包，若未压缩则填 dist/**/*）
- Remove prefix：留空（压缩包无需移除前缀，若直接推 dist 则填 dist/）
- Remote directory ：$TARGET_REMOTE_DIR（引用参数化构建的目录，或直接填绝对路径 /opt/web-test/assets）
- Exec command ：推送后执行的命令（解压、重启 Nginx）：
  bash 复制代码
```
# 进入目标目录，创建目录（若不存在）
mkdir -p $TARGET_REMOTE_DIR
cd $TARGET_REMOTE_DIR
# 解压压缩包（覆盖旧文件）
tar -zxvf vue-app.tar.gz -C ./
# 清理压缩包
rm -f vue-app.tar.gz
# 重启 Nginx，使新文件生效
systemctl restart nginx
```
点击「Save」保存配置。

4.2 关键注意事项（避免推送失败）

目标目录权限 ：确保 SSH 登录用户（如 root）对目标目录有写入权限，在目标服务器执行：
bash 复制代码
```
chown -R root:root /opt/web-test/assets
chmod 755 /opt/web-test/assets
```
绝对路径校验 ：Remote directory 必须以 / 开头（如 /opt/web-test/assets），避免相对路径（如 opt/web-test/assets）导致文件推到 /root 目录。
日志查看 ：构建后在「Console Output」中搜索 SSH: 查看推送日志，确认是否显示 cd [/opt/web-test/assets]（正确路径）。

五、常见问题排查与解决方案

5.1 问题 1：Node.js 启动报错（GLIBC 版本缺失）

报错日志：

bash 复制代码

node: /lib64/libm.so.6: version `GLIBC_2.27' not found (required by node)

原因：CentOS 7 系统库 GLIBC 2.17 不支持高版本 Node.js（如 v18+）。
解决方案：配置 Node.js 16.20.2（参考 2.2 节），确保任务使用该版本。

5.2 问题 2：文件推送到 /root 目录（路径错误）

报错日志：

bash 复制代码

SSH: Remote root is not absolute, getting absolute directory from PWD
SSH: cd [/root]

原因：Remote directory 配置为相对路径（如 opt/web-test/assets），自动拼接在用户根目录 /root 下。
解决方案 ：将 Remote directory 改为绝对路径（如 /opt/web-test/assets），并清空全局 SSH 配置中的「Remote Directory」。

5.3 问题 3：推送文件权限不足（Permission denied）

报错日志：

bash 复制代码

SSH: scp: /opt/web-test/assets/vue-app.tar.gz: Permission denied

原因：SSH 登录用户对目标目录无写入权限。
解决方案 ：在目标服务器执行 chown -R 用户名:用户名 /opt/web-test/assets（如 chown -R root:root /opt/web-test/assets）。

六、自动化部署验证

触发构建 ：进入 Jenkins 任务 → 点击「Build with Parameters」（若开启参数化）→ 输入目标目录（如 /opt/web-test/assets）→ 点击「Build」。
查看构建日志 ：进入构建记录 → 点击「Console Output」，确认以下关键步骤成功：
- Node.js 版本：Using Node.js from /root/.jenkins/tools/.../NodeJS_16.20.2
- 依赖安装：added 809 packages in 31s
- 打包成功：dist//assets/...js.gz 生成
- 推送成功：SSH: Transferred 1 file(s)、Command exit status: 0
验证部署结果 ：
- 登录目标服务器 → 进入 /opt/web-test/assets，确认解压后的文件存在。
- 访问 Nginx 服务（如 http://10.1.12.8），确认 Vue 项目正常加载。

七、总结

本文通过 Jenkins 实现了 Vue 项目的全自动化部署，核心流程为：
Git 拉取代码 → Node.js 16.20.2 构建环境 → cnpm 安装依赖（解决版本冲突）→ npm run build 打包 → Publish Over SSH 推送至目标服务器 → 解压并重启 Nginx。

关键解决的问题包括：系统库与 Node 版本兼容、pinia 依赖冲突、部署路径错误、权限不足等，可直接应用于生产环境，大幅提升前端项目部署效率。