huachuang/前端Jenkins部署指南.md

# 前端 Jenkins 部署指南

## 一、项目概况

| 项目 | 说明 |
|------|------|
| 源码路径 | `nl-ui/nl-ui-admin-vben/yudao-ui-admin-vben/` |
| 框架 | Vue 3 + Vite + Ant Design Vue 4（基于 vue-vben-admin 5.7.0） |
| 包管理器 | pnpm 11.7.0（强制，不可用 npm/yarn） |
| Node 版本 | >= 22.18.0（`.node-version` 指定 24.16.0） |
| 构建工具 | Turbo（monorepo 编排）+ Vite（打包） |
| 构建产物 | `apps/web-antdv-next/dist/` |
| 路由模式 | hash 模式（`VITE_ROUTER_HISTORY=hash`） |

---

## 二、环境变量说明

构建时通过 `.env.production` 控制关键配置，可按环境覆盖。

**文件位置：** `apps/web-antdv-next/.env.production`

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `VITE_BASE` | `/` | 部署路径前缀，部署在子路径时改为 `/admin/` |
| `VITE_GLOB_API_URL` | `http://127.0.0.1:48080/admin-api` | 后端 API 地址（完整 URL） |
| `VITE_ROUTER_HISTORY` | `hash` | 路由模式，hash 模式无需 nginx 特殊配置 |
| `VITE_COMPRESS` | `none` | 压缩方式（none / gzip / brotli） |
| `VITE_ARCHIVER` | `true` | 是否生成 `dist.zip` |
| `VITE_PWA` | `false` | 是否启用 PWA |

**多环境覆盖方式**：在 Jenkins 构建步骤中创建 `.env.production.local` 文件覆盖 `VITE_GLOB_API_URL` 等变量，Vite 会优先读取 local 文件。

---

## 三、Jenkins 流水线（Pipeline）

### 3.1 声明式流水线（推荐，使用 Docker 镜像自带 Node 环境）

```groovy
pipeline {
    // 使用 Docker 镜像，自带 Node 24 + pnpm，不需要 Jenkins 宿主机装 Node
    agent {
        docker {
            image 'node:24-slim'
            args '-u root --memory=4g'
        }
    }

    // 构建参数，支持按环境选择
    parameters {
        choice(name: 'DEPLOY_ENV', choices: ['dev', 'staging', 'prod'], description: '部署环境')
        string(name: 'API_BASE_URL', defaultValue: 'http://127.0.0.1:48080/admin-api', description: '后端 API 地址')
    }

    environment {
        // 源码子目录（仓库根目录下的相对路径）
        SOURCE_DIR  = 'nl-ui/nl-ui-admin-vben/yudao-ui-admin-vben'
        // pnpm 缓存目录，挂到宿主机避免重复下载
        PNPM_HOME   = '/root/.local/share/pnpm'
    }

    stages {

        // ==================== 第一步：拉取代码 ====================
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        // ==================== 第二步：安装依赖 ====================
        stage('Setup') {
            steps {
                dir(env.SOURCE_DIR) {
                    sh 'corepack enable'
                    sh 'corepack prepare pnpm@11.7.0 --activate'
                    // 安装依赖（锁定版本）
                    sh 'pnpm install --frozen-lockfile'
                }
            }
        }

        // ==================== 第三步：代码检查（可选） ====================
        stage('Lint') {
            steps {
                dir(env.SOURCE_DIR) {
                    sh 'pnpm run lint || true'
                }
            }
        }

        // ==================== 第四步：构建 ====================
        stage('Build') {
            steps {
                dir(env.SOURCE_DIR) {
                    script {
                        // 根据部署环境覆盖 API 地址
                        def apiUrl = params.API_BASE_URL
                        if (params.DEPLOY_ENV == 'prod') {
                            apiUrl = 'https://api.your-domain.com/admin-api'
                        } else if (params.DEPLOY_ENV == 'staging') {
                            apiUrl = 'https://staging-api.your-domain.com/admin-api'
                        }

                        // 写入环境变量（Vite 构建时读取）
                        writeFile file: 'apps/web-antdv-next/.env.production.local', text: """
                            VITE_GLOB_API_URL=${apiUrl}
                        """.stripIndent().trim()

                        // 执行构建
                        sh '''#!/bin/bash
                            export NODE_OPTIONS="--max-old-space-size=8192"
                            pnpm run build --filter=@vben/web-antdv-next
                        '''
                    }
                }
            }
        }

        // ==================== 第五步：打包产物 ====================
        stage('Archive') {
            steps {
                dir(env.SOURCE_DIR) {
                    script {
                        def distPath = 'apps/web-antdv-next/dist'
                        sh "tar -czf dist-${params.DEPLOY_ENV}.tar.gz -C ${distPath} ."
                        archiveArtifacts artifacts: "dist-${params.DEPLOY_ENV}.tar.gz", fingerprint: true
                    }
                }
            }
        }

        // ==================== 第六步：部署 ====================
        stage('Deploy') {
            when {
                expression { params.DEPLOY_ENV == 'dev' || params.DEPLOY_ENV == 'staging' || params.DEPLOY_ENV == 'prod' }
            }
            steps {
                dir(env.SOURCE_DIR) {
                    script {
                        def serverIp   = ''
                        def deployPath = '/usr/share/nginx/html/admin'

                        if (params.DEPLOY_ENV == 'dev')      { serverIp = '192.168.1.10' }
                        else if (params.DEPLOY_ENV == 'staging') { serverIp = '192.168.1.20' }
                        else if (params.DEPLOY_ENV == 'prod')    { serverIp = '192.168.1.30' }

                        sshagent(['deploy-ssh-key']) {
                            sh """
                                ssh root@${serverIp} 'mkdir -p ${deployPath}'
                                scp dist-${params.DEPLOY_ENV}.tar.gz root@${serverIp}:/tmp/
                                ssh root@${serverIp} '
                                    rm -rf ${deployPath}/*
                                    tar -xzf /tmp/dist-${params.DEPLOY_ENV}.tar.gz -C ${deployPath}
                                    rm -f /tmp/dist-${params.DEPLOY_ENV}.tar.gz
                                    nginx -t && nginx -s reload
                                '
                            """
                        }
                    }
                }
            }
        }
    }

    post {
        success { echo "构建成功！环境：${params.DEPLOY_ENV}" }
        failure { echo "构建失败！请检查日志。" }
        always  { cleanWs() }
    }
}
```

### 3.2 简化版流水线（仅构建 + 归档，手动部署）

```groovy
pipeline {
    agent {
        docker {
            image 'node:24-slim'
            args '-u root --memory=4g'
        }
    }

    parameters {
        string(name: 'API_BASE_URL', defaultValue: 'http://127.0.0.1:48080/admin-api', description: '后端 API 地址')
        string(name: 'VITE_BASE', defaultValue: '/', description: '部署子路径')
    }

    environment {
        SOURCE_DIR = 'nl-ui/nl-ui-admin-vben/yudao-ui-admin-vben'
    }

    stages {
        stage('Checkout') { steps { checkout scm } }

        stage('Install & Build') {
            steps {
                dir(env.SOURCE_DIR) {
                    sh 'corepack enable && corepack prepare pnpm@11.7.0 --activate'
                    sh 'pnpm install --frozen-lockfile'

                    writeFile file: 'apps/web-antdv-next/.env.production.local', text: """
                        VITE_GLOB_API_URL=${params.API_BASE_URL}
                        VITE_BASE=${params.VITE_BASE}
                    """.stripIndent().trim()

                    sh '''
                        export NODE_OPTIONS="--max-old-space-size=8192"
                        pnpm run build --filter=@vben/web-antdv-next
                    '''
                }
            }
        }

        stage('Package') {
            steps {
                dir("${env.SOURCE_DIR}/apps/web-antdv-next") {
                    sh 'tar -czf dist.tar.gz -C dist .'
                    archiveArtifacts artifacts: 'dist.tar.gz', fingerprint: true
                }
            }
        }
    }

    post {
        always { cleanWs() }
    }
}
```

---

## 四、Nginx 部署配置

项目使用 hash 路由，nginx 配置很简单：

```nginx
server {
    listen       80;
    server_name  admin.your-domain.com;

    # 前端静态文件
    root   /usr/share/nginx/html/admin;
    index  index.html;

    # hash 路由模式，单页应用标准配置
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理到后端网关
    location /admin-api/ {
        proxy_pass http://backend-gateway:48080/admin-api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

---

## 五、Docker 部署（可选）

项目自带 Dockerfile 但默认构建的是 playground 应用，需要调整。推荐新建一个：

```dockerfile
# Dockerfile 放在 yudao-ui-admin-vben/ 目录下
# ============ 构建阶段 ============
FROM node:24-slim AS builder

RUN npm install -g pnpm@11.7.0

WORKDIR /app
COPY pnpm-lock.yaml pnpm-workspace.yaml package.json turbo.json .npmrc ./
COPY internal/ internal/
COPY packages/ packages/
COPY apps/web-antdv-next/ apps/web-antdv-next/

RUN pnpm install --frozen-lockfile

ARG VITE_GLOB_API_URL=http://127.0.0.1:48080/admin-api
ENV VITE_GLOB_API_URL=${VITE_GLOB_API_URL}

RUN NODE_OPTIONS="--max-old-space-size=8192" pnpm run build --filter=@vben/web-antdv-next

# ============ 运行阶段 ============
FROM nginx:stable-alpine

COPY --from=builder /app/apps/web-antdv-next/dist /usr/share/nginx/html

COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

构建镜像：

```bash
docker build \
  --build-arg VITE_GLOB_API_URL=https://api.your-domain.com/admin-api \
  -t nl-admin-ui:latest \
  .
```

---

## 六、Jenkins 配置清单

在 Jenkins 上配置前需要准备：

| 配置项 | 说明 |
|--------|------|
| **Node.js 插件** | 安装 Jenkins NodeJS Plugin，添加 Node.js 24.x 安装 |
| **SSH 凭据** | 添加目标服务器的 SSH 私钥（ID 为 `deploy-ssh-key`） |
| **Git 仓库** | 确保 Jenkins 能访问代码仓库 |
| **构建机资源** | 内存 >= 4GB（`NODE_OPTIONS=--max-old-space-size=8192`） |
| **网络** | 构建机能访问 `registry.npmmirror.com`（或换内网 npm 镜像） |

---

## 七、常见问题

### Q1：构建报 `pnpm: command not found`

Jenkins 环境中 `corepack enable` 可能不生效，改用 `npm install -g pnpm@11.7.0`。

### Q2：构建 OOM（内存溢出）

调大 Node 内存限制：`NODE_OPTIONS="--max-old-space-size=8192"`，流水线中已默认设置。

### Q3：API 地址不对

检查 `.env.production.local` 是否在构建前正确写入，且 `VITE_GLOB_API_URL` 为完整 URL（如 `https://api.your-domain.com/admin-api`）。

### Q4：页面 404 白屏

确认 nginx 配置了 `try_files $uri $uri/ /index.html`，以及 `VITE_BASE` 与部署路径匹配。