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 安装必要插件

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

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

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

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

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

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

3.1 新建 Jenkins 任务

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

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

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

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

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

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

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

# 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 配置参数化构建（可选，动态指定部署目录）

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

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

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

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

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

1. 进入任务配置 →「Post-build Actions」→「Add post-build action」→ 选择「Send files or execute commands over SSH」
2. 配置推送参数（关键步骤）：
   • 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）：

     # 进入目标目录，创建目录（若不存在）
     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
     

3. 点击「Save」保存配置。

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

1. 目标目录权限：确保 SSH 登录用户（如 root）对目标目录有写入权限，在目标服务器执行：

   chown -R root:root /opt/web-test/assets
   chmod 755 /opt/web-test/assets
   

2. 绝对路径校验：Remote directory 必须以 / 开头（如 /opt/web-test/assets），避免相对路径（如 opt/web-test/assets）导致文件推到 /root 目录。
3. 日志查看：构建后在「Console Output」中搜索 SSH: 查看推送日志，确认是否显示 cd [/opt/web-test/assets]（正确路径）。

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

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

报错日志：

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 目录（路径错误）

报错日志：

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）

报错日志：

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）。

六、自动化部署验证

1. 触发构建：进入 Jenkins 任务 → 点击「Build with Parameters」（若开启参数化）→ 输入目标目录（如 /opt/web-test/assets）→ 点击「Build」。
2. 查看构建日志：进入构建记录 → 点击「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
3. 验证部署结果：
   • 登录目标服务器 → 进入 /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 依赖冲突、部署路径错误、权限不足等，可直接应用于生产环境，大幅提升前端项目部署效率。