Gitee + nginx + Jenkins 自动化部署 Vue 项目实战

1. 从手动上传到流水线这套方案到底解决了什么痛点前端项目上线这件事做过的人都知道有多琐碎。本地跑一遍npm run build等个一两分钟然后把dist目录打包打开终端scp传到服务器再登录服务器把文件挪到 nginx 的站点目录下最后可能还要 reload 一下 nginx。这一套流程走下来快的话五六分钟慢的话十几分钟中间任何一个环节手抖——比如传错目录、忘了删旧文件、build 的时候环境变量没切对——都会导致线上出问题。更麻烦的是团队协作场景。如果项目不止你一个人维护每次发版都得约定好谁来构建、谁来上传、上传到哪台机器沟通成本高不说还容易因为某个人本地环境差异导致构建产物不一致。我见过不少小团队发版靠的是某个人在自己电脑上 build 完用 FTP 工具拖上去这种方式在项目初期还能凑合一旦迭代频率上来迟早出事。这套Gitee nginx Jenkins的组合核心目标就是把构建和发布这两个动作从人工操作变成自动化流水线。你只需要把代码推到 Gitee 仓库剩下的构建、传输、部署、重载全部由 Jenkins 自动完成。听起来像是大厂才需要的东西但实际上这套方案的门槛比想象中低很多一台普通的云服务器就能跑起来个人项目、小团队项目完全适用。我先把这套方案的适用场景说清楚免得有人看完觉得我用不上个人开发者手上有几个 Vue 项目在维护每次改点东西都要手动部署烦了想一劳永逸。小团队三五个人协作没有专职运维需要一个大家都能用的自动发版流程。学习目的想搞明白 CI/CD 到底是怎么回事拿自己的项目练手比看文档强一百倍。不适合的场景也说一下如果你的项目一天发版几十次、需要灰度发布、需要多环境并行部署那这套方案会显得笨重应该考虑更专业的流水线平台。但对于绝大多数中小项目来说Gitee nginx Jenkins 的性价比非常高。整篇文章我会按照环境准备 → Jenkins 安装配置 → 构建任务编排 → nginx 对接 → 踩坑排查的顺序来讲每一步都会说清楚为什么这么做而不是只丢一堆命令让你抄。中间会穿插我自己踩过的坑这些内容在官方文档里基本找不到但实际部署时大概率会遇到。2. 环境准备服务器、仓库、工具链的选型逻辑2.1 服务器配置与系统选择先说服务器。这套方案对机器配置的要求其实不高Jenkins 本身是个 Java 应用构建 Vue 项目主要吃 CPU 和内存。我的经验是2 核 4G 是起步配置1 核 2G 也能跑但构建时会比较吃力。如果项目依赖多、构建时间长建议直接上 2 核 4G 或更高省得构建时把服务器拖垮。系统方面我推荐用主流的 Linux 发行版比如 Ubuntu 20.04/22.04 或者 CentOS 7/8。为什么强调这个因为 Jenkins 的安装方式在不同发行版上差异不小Ubuntu 用 aptCentOS 用 yum后面的路径和权限管理也不一样。选一个你熟悉的别为了新去选一个自己没碰过的系统出问题时排查成本会翻倍。这里有个容易被忽略的点服务器的时间同步。Jenkins 构建记录、日志时间戳都依赖系统时间如果服务器时间不准排查问题时会对不上号。装完系统第一件事就是确认时间同步正常这个后面踩坑章节还会提到。2.2 Gitee 仓库的准备与权限设计Gitee 作为代码托管平台在这套方案里承担的是代码源的角色。Jenkins 需要能从 Gitee 拉取代码所以仓库的访问权限要提前规划好。有两种方式让 Jenkins 访问 Gitee 仓库方式优点缺点适用场景HTTPS 用户名密码配置简单直观密码明文存储有风险改密码要同步更新个人项目、内网环境SSH 密钥安全性高无需输密码需要生成密钥对并配置公钥团队协作、生产环境我个人强烈推荐用SSH 密钥方式。生成一对密钥公钥放到 Gitee 仓库的部署公钥里私钥配置到 Jenkins 的凭据管理中。这样 Jenkins 拉代码时用的是密钥认证不用担心密码泄露或过期问题。具体操作上在服务器上执行ssh-keygen -t rsa -b 4096 -C jenkinsdeploy生成密钥对然后把~/.ssh/id_rsa.pub的内容复制到 Gitee 仓库的管理 → 部署公钥管理里。注意部署公钥默认是只读的这对 Jenkins 拉代码来说正好够用也更安全。提示生成密钥时不要设置 passphrase否则 Jenkins 拉代码时会卡在输入密码环节。如果已经设了可以用ssh-keygen -p重新设置为空。2.3 Node.js 与构建工具链的安装Vue 项目构建依赖 Node.js所以服务器上必须装 Node。这里有个关键决策用哪个版本、怎么装。我的建议是用nvmNode Version Manager来管理 Node 版本而不是直接用系统包管理器装。原因很简单不同项目可能依赖不同的 Node 版本用 nvm 可以随时切换不会互相干扰。而且 nvm 装 Node 不需要 root 权限对 Jenkins 这种以特定用户运行的服务来说更友好。安装 nvm 的命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash装完之后记得source ~/.bashrc让环境变量生效然后nvm install 16或nvm install 18装你需要的版本。Vue 2 项目一般用 Node 14/16Vue 3 Vite 项目建议 Node 16 以上。这里有个大坑要提前说Jenkins 执行构建脚本时默认不会加载用户的.bashrc所以 nvm 装好的 Node 在 Jenkins 里可能找不到。解决办法是在 Jenkins 的构建脚本里显式指定 Node 路径或者用 Jenkins 的 NodeJS 插件来管理。这个后面会详细讲。2.4 nginx 的角色定位与安装nginx 在这套方案里是最终承接者负责把构建好的静态文件对外提供服务。它的安装相对简单Ubuntu 下apt install nginxCentOS 下yum install nginx就行。但安装只是第一步真正要设计的是站点目录结构。我见过很多人把所有项目都塞到/var/www/html下结果项目一多就乱套。推荐的做法是每个项目一个独立目录比如/var/www/ ├── project-a/ │ └── dist/ ├── project-b/ │ └── dist/ └── project-c/ └── dist/这样 Jenkins 部署时只需要把构建产物同步到对应项目的dist目录nginx 配置里指向这个目录即可。目录规划清楚了后面自动化脚本写起来也清爽。3. Jenkins 的安装与初始化那些文档不会告诉你的细节3.1 安装方式的选择与实操Jenkins 的安装方式有好几种直接下 war 包跑、用 Docker 跑、用系统包管理器装。我推荐用系统包管理器装因为这样 Jenkins 会注册成系统服务开机自启、日志管理、权限控制都更规范。Ubuntu 下的安装步骤大致是先导入 Jenkins 的 GPG 密钥添加软件源然后apt install jenkins。CentOS 下类似用 yum 源。安装完成后 Jenkins 会自动启动默认监听 8080 端口。装完之后第一件事是访问http://服务器IP:8080会看到一个解锁 Jenkins的页面要求输入初始密码。这个密码在/var/lib/jenkins/secrets/initialAdminPassword文件里用cat命令读出来填进去就行。接下来是插件安装环节。Jenkins 会问你是安装推荐插件还是自定义。新手直接选推荐插件里面包含了 Git、Pipeline、凭据管理等核心插件够用了。装插件的过程可能比较慢取决于网络状况耐心等。3.2 用户权限与安全配置初始化完成后Jenkins 会让你创建管理员账号。这里有个建议不要用默认的 admin 账号名也不要用弱密码。Jenkins 暴露在公网上时是攻击重灾区弱密码分分钟被爆破。创建完账号后进入系统管理 → 全局安全配置把安全策略调整一下。默认的登录用户可以做任何事在生产环境是不合适的建议改成基于矩阵的授权或项目矩阵授权策略给不同用户分配不同权限。个人项目的话至少确保匿名用户没有管理权限。还有一个必做的安全动作关闭 Jenkins 的匿名读取权限。默认配置下任何人都能看到你的构建记录、任务配置甚至可能触发构建。在安全配置里把匿名用户的权限全部去掉只保留登录用户的权限。3.3 凭据管理SSH 密钥的正确配置姿势前面提到用 SSH 密钥让 Jenkins 访问 Gitee具体配置在系统管理 → 凭据 → 系统 → 全局凭据里。新建一个凭据类型选SSH Username with private key然后把服务器上生成的私钥内容粘贴进去。这里有个细节私钥的格式。如果你用ssh-keygen生成的是 OpenSSH 格式的私钥开头是-----BEGIN OPENSSH PRIVATE KEY-----Jenkins 某些版本可能不认需要转成 PEM 格式。转换命令是ssh-keygen -p -m PEM -f ~/.ssh/id_rsa转换后再把私钥内容填到 Jenkins 凭据里就不会报格式错误了。这个坑我踩过当时排查了半天才发现是格式问题。另外凭据的 ID 建议起一个有意义的名字比如gitee-ssh-key后面在任务配置里引用时一目了然。别用默认的随机 ID过两天自己都忘了是哪个。3.4 全局工具配置Node 和 Git 的路径指定Jenkins 需要知道 Node 和 Git 装在哪。进入系统管理 → 全局工具配置找到 NodeJS 和 Git 两项。Git 一般系统装好后路径是/usr/bin/gitJenkins 通常能自动检测到。NodeJS 的话如果你用 nvm 装的路径类似/root/.nvm/versions/node/v16.20.0/bin/node。把完整路径填进去Jenkins 构建时就能找到。注意如果 Jenkins 是以jenkins用户运行的而 nvm 是装在root用户下的那 Jenkins 是访问不到那个 Node 的。解决办法要么把 Node 装到全局路径要么给 jenkins 用户也装一份 nvm。这个权限问题非常隐蔽构建时报node: command not found多半就是它。4. 构建任务编排从拉代码到产出 dist 的完整链路4.1 任务类型选择自由风格还是 PipelineJenkins 创建任务时第一个要做的决策是选自由风格项目还是流水线Pipeline。这两者的区别简单说自由风格通过界面勾选配置适合简单任务上手快但配置复杂后难以维护。Pipeline用代码Jenkinsfile描述整个流程适合复杂任务可版本化可复用。对于Vue 项目自动化构建到发布这个场景我推荐用 Pipeline。原因有三第一整个流程拉代码、装依赖、构建、部署用代码写出来一目了然比在界面里点来点去清晰得多第二Jenkinsfile 可以跟项目代码一起放在仓库里改流程就是改代码有版本记录第三Pipeline 的灵活性更高后面想加个通知、加个测试环节都很方便。当然如果你只是想快速跑通自由风格也不是不行。但既然要学就一步到位学 Pipeline收益更大。4.2 Jenkinsfile 的结构设计一个典型的 Vue 项目 Jenkinsfile 大概长这样pipeline { agent any environment { NODE_HOME /root/.nvm/versions/node/v16.20.0/bin PATH ${NODE_HOME}:${env.PATH} } stages { stage(拉取代码) { steps { git branch: master, credentialsId: gitee-ssh-key, url: gitgitee.com:yourname/your-project.git } } stage(安装依赖) { steps { sh npm install } } stage(构建项目) { steps { sh npm run build } } stage(部署到 nginx) { steps { sh rm -rf /var/www/your-project/dist/* cp -r dist/* /var/www/your-project/dist/ } } } }这个结构看起来简单但每一段都有讲究。environment里显式指定 Node 路径就是为了解决前面说的 nvm 环境变量问题。stages按顺序执行任何一步失败后面的都不会跑这保证了不会出现构建失败但旧文件被删了的尴尬情况。4.3 拉代码阶段的凭据引用与分支策略git步骤里的credentialsId就是前面在凭据管理里创建的那个 SSH 密钥的 ID。url用 SSH 格式gitgitee.com:...不要用 HTTPS 格式否则凭据类型对不上。分支策略上个人项目一般固定拉master或main。如果是团队协作可以考虑用参数化构建让触发时选择分支。Jenkins Pipeline 支持parameters块定义参数然后在git步骤里引用parameters { string(name: BRANCH, defaultValue: master, description: 构建分支) }这样构建时就能手动指定分支灵活性更高。4.4 依赖安装与构建阶段的优化npm install这一步是构建里最耗时的环节尤其是依赖多的项目。有几个优化点第一用npm ci替代npm install。npm ci会严格按照package-lock.json安装速度更快且保证每次构建的依赖版本一致。前提是项目里有package-lock.json文件。第二配置 npm 镜像源。默认的 npm 源在国内访问可能较慢可以在服务器上配置镜像源加速npm config set registry https://registry.npmmirror.com第三利用 Jenkins 的缓存。如果构建频繁可以考虑把node_modules缓存起来避免每次都重新下载。不过这个要小心缓存失效时反而会出问题新手建议先不做。构建阶段就是npm run build没什么好说的。但要注意构建时的环境变量。Vue 项目通常有.env.production之类的文件构建时会读取。如果 Jenkins 构建出来的产物和本地不一致多半是环境变量的问题检查一下构建命令有没有指定正确的 mode。4.5 部署阶段的文件同步策略部署阶段的核心动作是把dist目录的内容同步到 nginx 站点目录。这里有个关键决策先删后拷还是直接覆盖。我推荐先删后拷也就是上面 Jenkinsfile 里写的rm -rf再cp。原因是 Vue 项目构建后文件名带 hash旧版本的文件如果不清掉会一直堆积在目录里时间长了占空间不说还可能造成混淆。先删后拷保证目录里只有最新版本的产物。但先删后拷有个风险删除和拷贝之间有个空窗期这期间用户访问会 404。对于访问量不大的项目这个空窗期只有几百毫秒基本无感。如果对可用性要求高可以用先拷到临时目录再原子替换的方式cp -r dist /var/www/your-project/dist-new mv /var/www/your-project/dist /var/www/your-project/dist-old mv /var/www/your-project/dist-new /var/www/your-project/dist rm -rf /var/www/your-project/dist-oldmv操作在同一文件系统内是原子的这样切换瞬间完成用户几乎无感。这个技巧在要求高的场景下很有用。5. nginx 对接与自动化触发让流程真正跑起来5.1 nginx 站点配置的关键参数nginx 的配置看起来简单但针对 Vue 这种单页应用SPA有几个参数必须配对否则会出现刷新 404、资源加载失败等问题。一个典型的 Vue 项目 nginx 配置server { listen 80; server_name your-domain.com; root /var/www/your-project/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 30d; add_header Cache-Control public, immutable; } }try_files $uri $uri/ /index.html这行是 SPA 的核心。Vue Router 用的是 history 模式时用户直接访问/some/route这样的路径nginx 会去找对应的文件找不到就 404。加上这行配置后找不到的路径都回退到index.html由前端路由接管问题就解决了。静态资源的缓存配置也很重要。Vue 构建后的文件名带 hash内容变了文件名就变所以可以放心设置长缓存比如 30 天。这样用户第二次访问时直接读缓存加载速度飞快。5.2 构建完成后的 nginx 重载大多数情况下部署完静态文件不需要 reload nginx因为 nginx 是实时读文件的。但如果你改了 nginx 配置文件就需要 reload 让配置生效。在 Jenkins Pipeline 里可以加一步stage(重载 nginx) { steps { sh nginx -t nginx -s reload } }nginx -t是先测试配置语法没问题再 reload。这个习惯很重要直接 reload 一个语法错误的配置会导致 nginx 起不来线上直接挂掉。注意Jenkins 用户需要有执行 nginx 命令的权限。如果 Jenkins 以jenkins用户运行而 nginx 需要 root 权限 reload就得配置 sudo 免密。在/etc/sudoers里加一行jenkins ALL(ALL) NOPASSWD: /usr/sbin/nginx然后 Jenkins 脚本里用sudo nginx -s reload。5.3 Gitee Webhook 自动触发构建前面所有配置完成后流程还是手动点构建按钮。要实现真正的自动化需要配置 Gitee 的 Webhook让代码推送时自动触发 Jenkins 构建。Jenkins 这边需要装Gitee 插件在插件管理里搜 Gitee装完后在任务配置里勾选Gitee webhook 触发构建会生成一个 Webhook URL 和一个 Secret Token。然后到 Gitee 仓库的管理 → WebHooks里添加一个 WebhookURL 填 Jenkins 生成的那个Token 填 Secret。触发事件勾选Push就行。配置完成后往仓库推一次代码Gitee 会向 Jenkins 发一个请求Jenkins 收到后自动开始构建。整个过程不需要人工干预真正实现了推代码即发布。这里有个坑Jenkins 的 Webhook URL 必须是 Gitee 能访问到的地址。如果 Jenkins 部署在内网Gitee 的公网请求到不了Webhook 就会失败。解决办法是用公网可访问的地址或者用轮询Poll SCM替代 Webhook。轮询的缺点是实时性差且会给服务器带来额外负担能不用就不用。5.4 构建通知与结果反馈构建完了怎么知道成功还是失败总不能一直盯着 Jenkins 界面。配置构建通知很有必要。最简单的方式是邮件通知。Jenkins 自带邮件插件配置好 SMTP 后可以在 Pipeline 的post块里加通知逻辑post { success { echo 构建成功 } failure { echo 构建失败请检查日志 } }如果需要更及时的通知可以接入企业微信、钉钉等工具的机器人。这些工具都提供了 Webhook 接口构建完成后用curl发个请求就能推送消息。具体配置这里不展开思路是通的。6. 踩坑实录那些让我熬夜排查的问题6.1 Node 版本不匹配导致的构建失败这是最常见的问题。本地用 Node 16 构建正常Jenkins 上用 Node 14 构建就报错提示某个依赖不支持。原因是 Jenkins 环境里的 Node 版本和本地不一致。排查方法在 Jenkins 构建脚本里加一行node -v看实际用的是哪个版本。如果不对检查全局工具配置里的 Node 路径以及environment块里的 PATH 设置。根本解决办法是统一环境。要么在 Jenkins 里装和本地一样的 Node 版本要么用.nvmrc文件锁定版本构建时先nvm use再构建。6.2 权限问题文件拷贝失败与目录不可写Jenkins 以jenkins用户运行时对/var/www/目录可能没有写权限导致cp命令失败。报错信息通常是Permission denied。解决办法有两种一是把/var/www/your-project/目录的属主改成jenkinschown -R jenkins:jenkins /var/www/your-project/二是把 jenkins 用户加到有权限的用户组里。我推荐第一种简单直接。但要注意nginx 也需要能读这些文件。如果目录属主是 jenkinsnginx 以www-data或nginx用户运行可能读不了。稳妥的做法是把目录权限设为755文件权限设为644这样所有用户都能读只有属主能写。6.3 构建产物路径不对dist 到底在哪Vue CLI 项目默认构建产物在dist目录但 Vite 项目可能配置成别的名字比如build或output。如果 Jenkins 部署时找不到dist目录先检查项目的构建配置。在vue.config.js或vite.config.js里找outputDir配置项确认实际输出目录。然后在 Jenkinsfile 里对应修改拷贝路径。还有一个隐蔽问题构建命令执行的工作目录。Jenkins 拉代码后工作目录是任务的工作空间npm run build生成的dist就在这个目录下。如果脚本里用了相对路径要确保路径是相对于工作空间的。6.4 Webhook 触发失败从日志定位问题Webhook 配置后不触发排查思路是第一看 Gitee 的 Webhook 记录。Gitee 仓库的 Webhook 管理页面有请求记录能看到每次推送有没有发请求、返回什么状态码。如果状态码是 404说明 URL 不对如果是 403说明 Token 不对。第二看 Jenkins 的日志。Jenkins 的系统日志在系统管理 → 系统日志里能看到 Webhook 请求有没有到达、为什么被拒绝。第三检查网络。如果 Jenkins 在内网Gitee 的公网请求到不了Webhook 记录里会显示超时或连接失败。这种情况只能改用轮询或者把 Jenkins 暴露到公网。6.5 构建缓存导致的改了代码没生效有时候明明推了新代码构建也成功了但线上还是旧版本。这种情况多半是缓存问题。可能是 nginx 缓存了index.html。index.html文件名不带 hash如果被缓存了用户拿到的还是旧的入口文件自然加载的是旧资源。解决办法是在 nginx 配置里对index.html设置不缓存location /index.html { add_header Cache-Control no-cache, no-store, must-revalidate; }也可能是浏览器缓存。让用户强制刷新CtrlF5能解决但更好的办法是通过 nginx 配置控制缓存策略从源头避免。6.6 磁盘空间被构建产物撑爆Jenkins 每次构建都会在工作空间里保留一份代码和构建产物构建次数多了磁盘空间会被慢慢吃掉。我见过一个项目跑了半年Jenkins 工作空间占了十几个 G。解决办法是配置构建保留策略。在任务配置里设置丢弃旧的构建比如只保留最近 10 次构建记录。这样 Jenkins 会自动清理旧的工作空间释放磁盘。另外node_modules目录也是空间大户。如果不需要保留可以在构建后清理掉或者用npm ci配合缓存策略来减少重复下载。7. 进阶优化让这套流程更稳更快7.1 构建速度优化从五分钟到一分钟构建慢是常态但可以优化。几个有效的方向并行执行。如果项目有测试环节测试和构建可以并行跑节省时间。Jenkins Pipeline 的parallel块支持这个。依赖缓存。把node_modules或 npm 缓存目录挂载到持久化存储避免每次重新下载。Jenkins 的cache指令或手动配置都能实现。增量构建。如果项目大全量构建慢可以考虑只构建改动的部分。不过这需要构建工具支持Vue CLI 和 Vite 都有相关配置。升级硬件。如果服务器 CPU 和内存是瓶颈加配置是最直接的。构建是 CPU 密集型任务核心数越多越快。7.2 多环境部署测试、预发、生产的隔离项目大了往往需要多环境。测试环境、预发环境、生产环境代码一样但配置不同。这套方案也能支持思路是用 Jenkins 的参数化构建定义ENV参数构建时选择环境。然后在构建脚本里根据ENV加载不同的环境变量文件部署到不同的目录。parameters { choice(name: ENV, choices: [test, staging, prod], description: 部署环境) }部署目录也按环境区分比如/var/www/your-project-test/、/var/www/your-project-prod/。nginx 配置多个 server 块分别指向不同目录。7.3 回滚机制出问题了怎么快速恢复自动化部署最怕的是部署上去发现有问题想回滚却回不去。所以回滚机制必须提前设计。最简单的回滚方式是保留上一版本。部署时不要直接删旧文件而是把旧版本重命名保留比如dist-20240101。出问题时把软链接指回旧版本即可。ln -sfn /var/www/your-project/dist-20240101 /var/www/your-project/currentnginx 配置里root指向current这个软链接。这样切换版本只需要改软链接秒级完成非常优雅。7.4 日志与监控构建失败了怎么第一时间知道构建失败不可怕可怕的是失败了没人知道。除了前面说的通知机制还建议做两件事一是保留构建日志。Jenkins 默认保留每次构建的完整日志出问题时可以回溯。但要注意日志量构建频繁的话日志会占不少空间配置保留策略时把日志也考虑进去。二是监控构建成功率。如果构建频繁失败说明流程有问题需要排查。可以定期看看 Jenkins 的构建趋势图成功率下降时及时介入。8. 我在这套方案上的一些个人体会这套 Gitee nginx Jenkins 的方案我从几年前开始用中间换过服务器、换过项目但核心思路一直没变。它最大的价值不是技术多先进而是把一件重复的、容易出错的事情变成了可靠的自动化流程。有几个体会比较深。第一环境一致性比什么都重要。本地能构建成功不代表服务器能成功Node 版本、依赖版本、环境变量任何一处不一致都可能导致构建失败。所以我现在习惯在项目里放一个.nvmrc和package-lock.json锁定版本减少环境差异。第二自动化流程要能看得见。构建失败了日志要清晰报错要能定位到具体哪一步。我见过一些流水线失败了只报一句构建失败排查起来像大海捞针。所以我在 Jenkinsfile 里会加足够的echo输出让每一步都有迹可循。第三别追求一步到位。一开始不用搞太复杂先把推代码 → 自动构建 → 自动部署这条主链路跑通后面再慢慢加通知、加回滚、加多环境。我见过有人一上来就想搞一套完美的 CI/CD结果配置太复杂自己都维护不了最后放弃了。最后分享一个小技巧在 Jenkinsfile 里加一个手动确认环节。生产环境部署前让流程暂停等人工点确认再继续。这样既保留了自动化的效率又避免了手滑推错分支直接上生产的风险。用input指令就能实现stage(生产部署确认) { steps { input message: 确认部署到生产环境, ok: 确认 } }这个环节在个人项目里可能觉得多余但在团队协作场景下能避免很多不必要的麻烦。