保姆级教学：使用 Jenkins 部署前端项目（2025 年最新版）

保姆级教学：使用 Jenkins 部署前端项目（2025 年最新版）

一、环境准备

1. 服务器要求

   • 操作系统：Linux（推荐 CentOS/Ubuntu）、Windows 或 Docker 环境
   • 依赖软件：
     • Java JDK 11+（Jenkins 运行依赖）
     • Node.js 14+（前端项目构建）
     • Git（代码拉取）

2. Jenkins 安装

   • Linux（CentOS 示例）：

     # 安装 Java 和 Jenkins 仓库
     sudo yum install java-11-openjdk -y
     sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo
     sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io.key
     # 安装 Jenkins
     sudo yum install jenkins -y
     # 启动服务
     sudo systemctl start jenkins
     sudo systemctl enable jenkins
     

   • Docker 安装：

     docker run -d --name jenkins -p 8080:8080 -p 50000:50000 -v jenkins_home:/var/jenkins_home jenkins/jenkins:lts
     

3. 初始化 Jenkins

   • 访问 http://<服务器IP>:8080，输入初始密码（通过 sudo cat /var/lib/jenkins/secrets/initialAdminPassword 获取）。
   • 安装推荐插件（Git、Node.js、Pipeline、Publish Over SSH）。

二、Jenkins 核心配置

1. 安装必要插件

   • Node.js 插件：管理前端项目构建环境。
   • Git 插件：拉取代码仓库。
   • Publish Over SSH：部署到远程服务器。
   • Pipeline 插件：定义自动化流水线（可选）。

2. 全局工具配置

   • Node.js 配置：
     • 进入 系统管理 > 全局工具配置。
     • 添加 Node.js 安装，选择版本（如 16.x），勾选“自动安装”。
   • SSH 服务器配置：
     • 进入 系统管理 > 系统设置 > Publish over SSH。
     • 添加远程服务器信息（IP、端口、用户名、密码/密钥）。

三、创建 Jenkins 任务（以 Vue 项目为例）

1. 新建任务

   • 选择“自由风格项目”，输入任务名称（如 vue-project-deploy）。

2. 源码管理

   • 选择 Git，填写仓库 URL（如 https://github.com/your/vue-project.git）。
   • 添加凭证（用户名/密码或 SSH 密钥）。

3. 构建环境

   • 勾选“提供 Node & npm bin/folder 到 PATH”，选择配置的 Node.js 版本。

4. 构建步骤

   • 执行 Shell：

     # 安装依赖
     npm install
     # 构建生产环境包
     npm run build
     # 打包构建结果（可选）
     tar -zcvf dist.tar.gz dist
     

5. 构建后操作

   • 发送构建文件到远程服务器：
     • 选择配置的 SSH 服务器。
     • 源文件：dist/**（或 dist.tar.gz）。
     • 移除前缀：dist。
     • 远程目录：/var/www/html/vue-project。
     • 执行命令（如解压并重启服务）：

       tar -zxvf dist.tar.gz -C /var/www/html/vue-project
       systemctl reload nginx
       

四、自动化触发与参数化构建

1. Git Webhook 触发

   • 在 Git 仓库（如 GitHub/Gitee）中设置 Webhook，指向 http://<Jenkins服务器IP>:8080/github-webhook/。
   • Jenkins 任务中勾选“GitHub hook trigger for GITScm polling”。

2. 参数化构建（可选）

   • 添加字符串参数（如 ENV，默认值 prod）。
   • 修改构建命令：

     npm run build -- --mode ${ENV}
     

五、常见问题解决

1. 权限问题

   • 确保 Jenkins 用户对目标目录有写入权限：

     chown -R jenkins:jenkins /var/www/html
     

2. 依赖安装失败

   • 检查 Node.js 版本是否兼容，或切换 npm 源：

     npm config set registry https://registry.npmmirror.com
     

3. 构建超时

   • 在任务配置中增加超时时间（分钟）。

六、完整案例演示

1. 项目结构

   vue-project/
     ├── public/
     ├── src/
     ├── package.json
     └── Jenkinsfile（可选，定义流水线）
   

2. Jenkinsfile 示例（Pipeline）

   pipeline {
     agent any
     stages {
       stage('拉取代码') {
         steps {
           git 'https://github.com/your/vue-project.git'
         }
       }
       stage('构建') {
         steps {
           sh 'npm install'
           sh 'npm run build'
         }
       }
       stage('部署') {
         steps {
           sshPublisher(
             publishers: [
               sshPublisherDesc(
                 configName: 'prod-server',
                 transfers: [
                   sshTransfer(
                     sourceFiles: 'dist/**',
                     remoteDirectory: '/var/www/html/vue-project',
                     execCommand: 'systemctl reload nginx'
                   )
                 ]
               )
             ]
           )
         }
       }
     }
   }
   

七、扩展优化

1. Docker 容器化 Jenkins
   • 使用 Docker 部署 Jenkins，实现环境隔离。
2. 集成自动化测试
   • 在构建步骤中添加 npm run test。
3. 监控与日志
   • 通过 系统管理 > 系统日志 查看详细构建日志。

通过以上步骤，您可实现从代码提交到生产环境部署的全自动化流程。如遇具体问题，可结合 Jenkins 日志和项目报错信息进一步排查。