Jenkins 自动化部署 Nuxt 项目完整教程

Nuxt 项目部署是前端工程化中常见的一环，手动部署不仅效率低，还容易出错。本文分享一套基于 Jenkins 的 Nuxt 自动化部署方案，通过 Docker 构建 + rsync 同步的方式，实现一键部署上线。

方案概览

整体流程分为三个阶段：拉取代码 → Docker 构建 → 同步部署到服务器。构建阶段使用 Docker 容器来运行 Node 环境，这样做的好处是不需要在 Jenkins 宿主机上安装 Node.js，构建环境和项目需要的 Node 版本完全解耦，升级也方便。

部署阶段使用 rsync 增量同步到远程服务器，比 scp 全量传输更快，也支持排除不需要的文件。

Jenkins Pipeline 配置

直接上完整的 Jenkinsfile 配置，后面分段讲解：

pipeline {
    agent any
    environment {
        REMOTE_USER = 'root'
        REMOTE_HOST = 'xxxx'
        REMOTE_PATH = '/data/web/xxx'
    }
    stages {
        stage('Checkout') {
            steps {
                echo 'Checkout'
                echo "${params.BRANCH}"
                checkout(
                    [
                        $class: 'GitSCM',
                        branches: [[name: "${params.BRANCH}"]],
                        userRemoteConfigs: [
                            [credentialsId: 'xxxx', url: 'xxxxx']
                        ]
                    ]
                )
            }
        }
        stage('Build Frontend node') {
             steps {
                script {
                    sh """
                        cp .prod.env .env
                        docker run --rm \
                            -u root \
                            -v ${WORKSPACE}:/workspace \
                            -w /workspace \
                            -p 3012:3012 \
                            -e PORT=3012 \
                            -e NITRO_PORT=3012 \
                            node:22-alpine \
                            /bin/sh -c "
                                cd /workspace/
                                npm install --registry=https://registry.npmmirror.com &&
                                npm run build
                            "
                    """
                }
            }
        }
        stage('Finished') {
            steps {
                script {
                    sshagent(credentials: ['jenkins-deploy-key']) {
                        sh """
                            rsync -avz --delete --force --exclude=".user.ini" \
                                ./.output \
                                ${REMOTE_USER}@${REMOTE_HOST}:${REMOTE_PATH}/
                            echo "Deployment complete."
                        """
                    }
                }
            }
        }
    }
}

分段解析

1. 环境变量定义

顶部 environment 区块定义了远程服务器的连接信息，包括用户名、IP 地址和部署路径。统一放在这里方便后续修改，也方便做成参数化构建。

2. Checkout 阶段

使用 GitSCM 插件拉取指定分支的代码，分支名通过参数 ${params.BRANCH} 传入。需要在 Jenkins 项目中配置好 Git 凭证，credentialsId 对应你在 Jenkins 里添加的凭证 ID。

3. Build 阶段

这是整个流水线的核心部分。思路是用 Docker 启动一个 node:22-alpine 容器，把当前工作目录挂载进去，在容器里执行 npm install 和 npm run build。

有几个细节值得注意：

--rm：构建完成后自动删除容器，不会留下残留容器
-u root：以 root 用户运行，避免文件权限问题
-v ${WORKSPACE}:/workspace：把 Jenkins 工作目录挂载到容器内，构建产物直接写到宿主机
-w /workspace：设置工作目录
npm install 使用国内镜像源：加速依赖安装
cp .prod.env .env：把生产环境配置文件复制到位，Nuxt 构建时会读取 .env

4. 部署阶段

构建产物生成在 .output 目录中，使用 sshagent 插件加载 SSH 密钥，然后通过 rsync 同步到远程服务器。

rsync 的几个参数说明：

-avz：归档模式 + 详细输出 + 压缩传输
--delete：删除目标目录中源端没有的文件，保持两边一致
--exclude=".user.ini"：排除服务器上的特定文件，避免被覆盖

同步完成后，在远程服务器上用 PM2 或 systemd 重启 Nuxt 服务即可。这一步也可以加到 Pipeline 里，用 ssh 命令远程执行重启。

前置准备

在使用这套流水线之前，需要先做好以下准备工作：

Jenkins 安装 Docker，并且 Jenkins 用户有权限执行 docker 命令
安装 SSH Agent 插件（sshagent）
在 Jenkins 凭证中添加 Git 凭证和部署用的 SSH 密钥
远程服务器配置好 SSH 密钥登录，并且目标目录存在
项目根目录下有 .prod.env 生产环境配置文件

常见问题

Q: 构建很慢怎么办？

可以把 node_modules 缓存起来，下次构建不用重新安装所有依赖。可以使用 Jenkins 的 stash/unstash，或者把 node_modules 挂载到宿主机的缓存目录。

Q: 构建时端口冲突怎么办？

构建阶段其实不需要端口映射，上面的 -p 参数是为了调试方便，实际构建生产环境时可以去掉。

Q: rsync 同步权限报错？

检查远程服务器上目标目录的所有者是否和 SSH 登录用户一致，或者在 rsync 命令里加上合适的权限参数。

总结

用 Docker 构建 + rsync 部署的方案，好处是构建环境干净、升级 Node 版本方便、部署速度快。整个流程配置好之后，点一下构建就可以自动完成从拉代码到部署上线的全部步骤，比手动部署省心很多。

如果项目有多个环境，可以在 Jenkins 里建多个 Job，或者把环境做成参数，一套流水线适配多个环境。

Jenkins 自动化部署 Nuxt 项目完整教程（Docker + rsync）