本地跑得好好的代码一上服务器就白屏F12 打开一看全是 404 资源报错如果你正在经历这个阶段恭喜你你到了 Vue 学习路上最“让人长记性”的一关——项目部署。这篇内容对应进阶学习的第 58 天刚好是 Vue 进阶与生态整合里最容易忽视、却最见功力的环节。很多人学了组件、路由、状态管理觉得已经能写项目了但真到部署上线那一步才发现自己对构建工具、服务器配置的理解还停留在“能跑 dev 就行”的程度。这一篇我会把 Vue 项目从打包到上线的完整链路拆开讲清楚产物是什么、为什么配置要这么写、服务器上到底干了什么以及上线后的各种故障怎么排查。适合刚接触部署、手里有项目但不知道怎么丢到服务器上的开发者也适合想弄明白 Nginx 配置原理而不是照抄的人。1. 动手之前先搞清楚你将要部署的到底是什么1.1 开发服务器和生产服务器的差异以及为何不能直接丢源码很多人第一次部署时会下意识想我把整个项目文件夹压缩上传然后服务器上装个 Node.js跑npm run dev不就完事了吗表面上确实能跑但这是完全错误的做法。开发环境里npm run dev启动的是一个开发服务器它做的事情包括模块热替换代码改了页面自动刷新、即时编译.vue单文件组件、把浏览器不认识的各种 import 语法转为可执行代码。这些功能本质上都是“给开发时用的便利设施”生产环境根本不需要而且会带来严重的性能开销。生产环境要的是另一套东西压缩过的 JS、压缩过的 CSS、不带语义化的变量名、去掉注释和 console、按路由拆成独立 chunk 方便按需加载。这些工作由npm run build完成也就是 Vue 项目打包的核心命令。Vue 底层用的是 ViteVite 在生产构建时会执行完整的编译和打包流程最终生成一个dist目录这个目录里的东西才是你真正要部署的产物。dist目录的结构大概是这样dist/ ├── index.html ├── logo.svg └── assets/ ├── index-6f3a2b1c.js ├── index-8e4d5f6a.css └── vendor-3f2a5d7e.jsassets里那些带一串 hash 的文件是经过压缩和内容哈希标记的静态资源。注意这个 hash 是内容相关的也就是说文件内容变了文件名就会变这个是后面处理浏览器缓存的关键机制。index.html是整个应用的入口它会用相对或绝对路径引用这些带 hash 的资源。浏览器运行时实际执行流程是用户访问你的域名服务器返回index.html浏览器解析 HTML 发现里面有script src/assets/index-6f3a2b1c.js再去请求这个 JS 文件JS 执行后动态渲染出整个页面。所以部署的本质就一句话把dist目录里的静态文件交给服务器让用户能通过 HTTP 访问到它们。1.2 环境变量在部署前如何区分开发与生产另一个容易出问题的地方是环境变量。项目里经常有这种代码const apiUrl http://localhost:3000/api本地开发时连本机后端没问题一部署到服务器这个地址就废了——用户浏览器访问你的线上域名时代码会试图请求localhost:3000这是用户自己的电脑当然请求不到。Vite 提供了环境变量机制我们可以用.env.development和.env.production两个文件区分不同环境的配置。以接口地址为例# .env.development VITE_API_BASE_URLhttp://localhost:3000/api# .env.production VITE_API_BASE_URLhttps://api.example.com/api代码里用import.meta.env.VITE_API_BASE_URL读取这样npm run dev时 Vite 自动加载.env.developmentnpm run build时加载.env.production。注意变量名必须带VITE_前缀这是 Vite 刻意设计的隔离机制防止把本机敏感变量暴露给前端。这里有个关键认知环境变量不是运行时读取的而是在构建时被写死进产物里的。npm run build之后import.meta.env.VITE_API_BASE_URL会被直接替换成字面字符串你是改不了已构建产物的环境变量的。所以部署后如果发现接口地址不对修改.env.production之后必须重新npm run build再上传新的dist。1.3 路由模式决定服务器回退策略Vue Router 有两种路由模式这个选择直接决定服务器该怎么配。开发展模式时很多人没留意因为 Vite 开发服务器都已经帮你处理好了但生产环境没有这个待遇。createWebHashHistoryhash 模式地址长这样https://example.com/#/dashboard。#后面的内容不会发送到服务器所以服务器完全不用管路由只管index.html一个入口文件就行。这种模式兼容性最好、服务器配置最简单但 URL 不太美观。createWebHistoryhistory 模式地址长这样https://example.com/dashboard。这种模式 URL 干净、美观是生产环境推荐的方式。但它的代价是用户访问/dashboard时服务器收到的请求是这个路径如果服务器只知道返回dist/index.html那/dashboard这个路径对应的是一个不存在的文件就会返回 404。处理方式是配置服务器的“回退”fallback凡是请求路径不对应实际文件、也不是以/api之类的接口路径一律返回index.html让 Vue Router 接管路由解析。具体怎么配第三章会详细讲。两种模式的取舍其实很清晰路由模式URL 示例服务器要求适用场景hash 模式/#/dashboard无要求任意静态服务器可用简单部署、无服务器控制权history 模式/dashboard必须配置路由回退到 index.html正式生产环境推荐2. 打包配置里的细枝末节直接影响上线后的生死2.1 base 路径部署白屏的头号嫌疑人关于部署我见过的翻车案例里白屏出现频率最高而白屏里八成以上是base路径没配对。你自己试一下就知道本地 build 完之后用浏览器打开dist/index.html如果页面是空白的打开控制台看资源请求路径大概率是/assets/index-xxx.js——以/开头的绝对路径。这意味着你的资源只能部署在域名根路径下才找得到。如果你把dist上传到服务器但应用不是部署在根路径而是部署在子目录比如https://example.com/my-app/那/assets/xxx.js就会去请求https://example.com/assets/xxx.js而真实文件在https://example.com/my-app/assets/xxx.js直接 404页面自然就白屏了。解决方式是在vite.config.js里设置base选项// vite.config.js export default defineConfig({ base: /my-app/, // 其余配置省略 })这样构建出来的 index.html 引用路径就变成了/my-app/assets/xxx.js部署在子目录下一切正常。如果应用部署在根路径用默认的base: /就行。补充一个部署实操经验如果你用的是虚拟主机、OSS 静态托管这类不太方便自定义路由的服务但又必须用 history 路由模式我劝你尽早换成 hash 模式省得后面踩各种回退配置的坑。而如果部署在自己的云服务器上history 模式配 Nginx 才是正道体验好很多。2.2 打包产物的结构与可配置项Vite 的构建配置都集中在build字段下有几个我实际用下来觉得值得关注的// vite.config.js export default defineConfig({ build: { outDir: dist, // 产物目录默认就是 dist一般不用改 assetsDir: assets, // 静态资源存放目录 sourcemap: false, // 生产环境建议关掉避免源码暴露 chunkSizeWarningLimit: 1000, // 调整 chunk 大小警告阈值 }, })outDir不用多说默认dist就行。assetsDir决定 JS/CSS 图片等静态资源在产物里的存放目录。sourcemap值得单独说一下开发时开着方便定位错误但生产环境建议关掉一方面避免源码直接暴露给用户另一方面 map 文件本身也挺占体积的。真有生产排错需求临时打包一份带 sourcemap 的产物分析分析完再关掉。还有一个常用配置是手动分包。Vue 项目打包时如果不做任何处理Vite 默认会把第三方依赖和业务代码混在一起打包。如果依赖很大比如 Element Plus、ECharts 这类生成的 JS 文件体积会非常可观影响首屏加载。通过rollupOptions可以手动拆包build: { rollupOptions: { output: { manualChunks: { vue: [vue, vue-router, pinia], echarts: [echarts], }, }, }, }把 Vue 全家桶拆成一个 chunkECharts 单独拆一个 chunk业务代码再单独一个。这样用户访问页面时浏览器可以同时并行下载多个 chunk比下载一个巨型文件快得多而且第三方库不带业务变动文件名 hash 不变浏览器可以长期缓存下次访问直接命中缓存。2.3 构建体积分析与 CDN 优化思路部署前我建议做一次体积体检手段很简单装一个可视化插件npm i -D rollup-plugin-visualizer然后配置import { visualizer } from rollup-plugin-visualizer plugins: [ visualizer({ open: true }), ]运行npm run build后会自动打开一个 HTML 报告展示每个 chunk 的体积占比。你会发现往往某个重型依赖占了半壁江山。这时候有两个选择一是把大依赖改成 CDN 引入在index.html里直接加script标签然后在 Vite 配置里用external排除掉它并把代码里的 import 声明映射成全局变量。这个方案可行但配置比较繁琐而且依赖外部 CDN 的稳定性。二是做组件按需加载。以 Element Plus 为例借助自动导入插件只有用到的组件才会打进产物而不是全量引入。这一步往往能把产物体积减少一半以上比上 CDN 更实在。我自己实测过仅仅是把 ECharts 改成按需注册首屏 JS 体积就从 800 多 KB 降到了不到 300 KB。这里不展开每个插件的具体配置了记住一个原则先分析再优化不要凭感觉瞎优化。构建体积报告会告诉你问题出在哪针对性解决比盲目上 CDN 靠谱得多。3. 服务器端的静态服务与路由回退以 Nginx 为例3.1 静态文件服务的基础配置把 site 上传到服务器之后需要一个 Web 服务器软件来承接 HTTP 请求。可选的有 Nginx、Apache、Caddy 等我默认用 Nginx原因是它性能好、配置语言简洁、社区资料多是当前部署前端项目的主流选择。假设你的站点目录路径是/var/www/my-app/dist/先创建好目录把dist里的所有文件上传进去。注意是dist里的内容不是整个dist文件夹。很多新人在这里出错root指向了包含dist的上一级目录又忘了加/dist后缀结果怎么访问都是 404。Nginx 的配置核心就是一个server块server { listen 80; server_name example.com www.example.com; root /var/www/my-app/dist; index index.html; location / { try_files $uri $uri/ /index.html; } }这段配置的含义监听 80 端口HTTP 默认端口把example.com域名的请求映射到/var/www/my-app/dist目录。index index.html意味着当访问/时Nginx 直接返回index.html。3.2 try_files 是什么为什么 SPA 必须用它前面说的 history 路由回退核心就是这一段location / { try_files $uri $uri/ /index.html; }try_files的语法是“按顺序尝试命中即止”。拿https://example.com/dashboard举例第一步$uriNginx 查找/var/www/my-app/dist/dashboard这个文件不存在。第二步$uri/尝试把/dashboard当作目录查找/var/www/my-app/dist/dashboard/下的索引文件也不存在。第三步/index.html都找不到那就直接回退到/var/www/my-app/dist/index.html。这个回退的本质是把无法对应到物理文件的路径全部交给前端路由去处理。Vue Router 启动后读取浏览器地址栏的 URL匹配到对应路由渲染对应页面。index.html是单页应用的入口只要它被返回应用就能接管剩下的逻辑。注意一个边界情况如果dist目录下有真实的静态资源路径比如assets/index-xxx.js请求这个路径时$uri第一步就命中了物理文件Nginx 直接返回文件不会执行第二步和第三步。这就保证了静态资源和前端路由互不干扰。3.3 资源压缩与缓存策略的落地配置前面说了文件名带 hash 是内容相关的这个特性用在缓存策略上效果极佳。思路一句话概括带 hash 的资源长缓存不带 hash 的入口不缓存。所谓入口就是index.html本身它是所有资源的引用起点。如果它被浏览器缓存那下次发版后用户看到的还是旧页面的引用永远不会去请求新资源。所以index.html必须禁用缓存。带 hash 的静态资源则相反文件名变了说明内容变了浏览器会请求新文件文件名没变说明内容没变直接用本地缓存就好完全不需要向服务器发请求。Nginx 里的配置location /assets/ { expires 30d; add_header Cache-Control public, max-age2592000; } location / { try_files $uri $uri/ /index.html; expires -1; add_header Cache-Control no-cache, no-store, must-revalidate; }/assets/目录存放的是所有带 hash 的构建产物给 30 天缓存。index.html所在的根路径设置为禁止缓存。这样下次部署时index.html马上拿到新的里面引用的新资源文件名带了新 hash也会请求新文件没变过的资源直接从本地缓存读取访问速度也快。Gzip 压缩也是上线必做的配置文件级开启gzip on; gzip_vary on; gzip_min_length 1024; gzip_comp_level 5; gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svgxml;gzip_min_length 1024的意思是小于 1KB 的文件不值得压缩体积小压缩了也没多大收益还浪费 CPU。gzip_comp_level设 5 即可默认 1 压缩率偏低调到 9 压缩率提升有限但 CPU 占用上升明显实测 5 是性价比比较好的档位。4. 反向代理、HTTPS 与缓存策略上线之后才遇到的硬仗4.1 为什么线上也要配反向代理前端项目部署上线后很快会碰到跨域问题。开发环境有 Vite 的proxy帮忙转发请求生产环境就没有这个待遇了。如果你直接在前端代码里写https://api.example.com/api/xxx然后从https://app.example.com发请求过去同源策略直接拦截除非后端配合开了 CORS。更规范的方案是 Nginx 反向代理前端只请求自己的域名/api/xxxNginx 收到后再转发给真实的后端服务。这让你在浏览器层面完全看不到跨域问题因为请求是从同源域名发出去的。4.2 Nginx 代理配置里的关键细节配置很简单location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }把/api/开头的请求转发到本机 8080 端口的后端服务。注意proxy_pass的地址后面加不加/有讲究——如果写http://127.0.0.1:8080不带斜杠Nginx 会保留完整的原始 URI 转发给后端也就是请求/api/xxx后端收到/api/xxx如果写http://127.0.0.1:8080/带斜杠则会去掉匹配的/api/前缀转发后端收到/xxx。到底要不要保前缀取决于后端接口定义实际开发里因为这里弄错接口 404 的情况很常见。proxy_set_header Host $host也很重要不设置的话后端收到的 Host 是127.0.0.1:8080如果你的后端校验了 Host 头比如某些服务限定了域名白名单就会无法正常工作。X-Real-IP是为了让后端拿到用户真实 IP否则它看到的所有请求都来自 Nginx 所在的内网地址。4.3 HTTPS 证书配置与 HTTP/2现在的正规站点没有 HTTPS 已经说不过去了。证书申请渠道不具体展开假设你已经有证书文件Nginx 配置 HTTPS 监听的标准写法server { listen 443 ssl; server_name example.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; add_header Strict-Transport-Security max-age31536000 always; # 静态资源、代理等配置同上 }Strict-Transport-SecurityHSTS是对浏览器说“以后请直接用 HTTPS 访问我”这样可以防住中间人把 HTTPS 降级为 HTTP。但注意一旦开了 HSTS浏览器会强制 HTTPS 访问如果证书配置有问题、或者你临时想改回 HTTP 测试用户那边会被卡住因为浏览器不会给你机会。所以我一般是先确认 HTTPS 完全稳定了再开 HSTS。加一个把 HTTP 跳转到 HTTPS 的配置server { listen 80; server_name example.com; return 301 https://$host$request_uri; }301是永久重定向对 SEO 和用户访问体验都比较友好。HTTP/2 的话新版本的 Nginx 直接在监听行加http2也可以或者用单独的http2 on;指令不同版本的 Nginx 语法有差异。HTTP/2 最直观的收益是同一连接支持多路复用对带大量静态资源的页面加载有明显帮助。开启了之后建议用浏览器开发者工具验证一下协议版本是否为h2确认配置真正生效了。5. 部署后的常见故障排查链路5.1 白屏第一要查的永远是资源路径页面一打开全白最基本的排查顺序是这样的第一步打开浏览器开发者工具 Network 面板看有没有 404。如果看到assets/xxx.js404基本可以确定是资源路径问题——多半是 base 配置 / 部署目录层级不匹配。第二步打开页面源码直接看index.html里script标签的 src 路径。如果部署在子目录但路径是绝对路径/assets/xxx.js那就是 base 没配如果路径是对的但服务器返回 404那就是服务器 root 指错目录了。第三步确认服务器上文件真的存在。SSH 进服务器ls /var/www/my-app/dist/assets看看文件列表和路径写法对得上不对得上。这里说一个我当年踩过的坑dist上传时用了带目录的方式服务器上变成了/dist/assets/xxx.js但 Nginx root 指向的目录下没有dist这一层同样导致 404。上传时仔细检查最终目录结构比什么都管用。5.2 刷新页面就 404history 模式回退没配页面能正常打开但从 A 页跳转 B 页没问题一按 F5 刷新就 404。这个症状几乎可以确诊history 路由模式 服务器没有配置 try_files 回退。想想刷新时发生了什么浏览器向服务器发了一个真实的 HTTP 请求路径是/dashboard。服务器在磁盘上找不到dashboard这个物理文件又没人告诉它“找不到就返回 index.html”于是直接返回 404。跳转时没问题是因为那是前端路由控制的没有产生真正的服务器请求。修复方式就是加try_files $uri $uri/ /index.html;详见第三章。如果你用的是非 Nginx 服务器本质思路也一样凡是请求不到物理文件的路径通通返回入口 HTML。5.3 页面更新了用户却还是旧版本的资源发版后你自己看着是新页面用户那边怎么刷新都是旧的。这通常是两层问题叠加一是index.html被缓存了用户拿到的是旧入口文件里面引用的还是旧资源名二是静态资源缓存策略不合理。排查时先看index.html的响应头如果发现Cache-Control里带max-age之类的长缓存标记说明入口文件的缓存策略不对。需要改成no-cache, no-store, must-revalidate让浏览器每次访问都去服务器拿新的index.html。至于/assets/下带 hash 的文件正常不需要手动清缓存文件名就是版本号。但如果你发现构建出来的资源 hash 没变那就要怀疑构建失败了——文件内容变了hash 不可能相同这是内容哈希的数学保证。检查构建日志看看是不是增量缓存或者配置问题导致产物没更新。5.4 改完配置后没生效、端口被占用、权限报错高频出现的服务器侧问题也列一下改了 Nginx 配置发现没生效执行nginx -t先测试配置有没有语法错误然后systemctl reload nginx。注意是 reload 不是 restartreload 是平滑重载业务不中断。重启 Nginx 报bind() to 0.0.0.0:80 failed (98: Address already in use)说明 80 端口被占一般是 Nginx 已经在运行导致重复启动或者有别的进程占了端口。用ss -tlnp | grep :80查一下占用进程。上传文件后首页能打开但静态资源 403多半是文件权限问题Nginx 的 worker 进程没有权限读取站点目录。确认站点目录执行权限比如chmod -R 755目录、chmod -R 644文件或者直接chown -R给 Nginx 用户。这些看着都是小问题但上线遇到时特别让人烦躁。排查原则就一条看日志。Nginx 的error.log会明确告诉你哪个文件找不到、哪个权限不够、哪个地址无法解析。我每次折腾服务器都是先把日志开成 tail 跟随模式哪个请求报错立刻能看到效率高得多。6. 上线前最后一道把关本地模拟生产环境最后说一个我每次都会做、但很多人会跳过的步骤本地模拟生产环境预览。Vite 提供了一个命令npm run preview。它会读取你已经构建好的dist目录起一个本地静态服务器来提供服务。这等于在本地模拟了一次“生产环境部署”可以提前发现很多问题base 路径没配对导致的资源 404路由模式导致的手动回退问题preview默认支持 history 回退但至少能验证资源路径环境变量打包后是否生效dev 和 preview 用的是不同模式。流程就是先npm run build再npm run preview浏览器打开本地预览地址把页面能点的路径都点一遍该刷新的刷新该跳转的跳转看有没有资源加载失败。没问题再上传服务器能省掉一半的线上排查成本。部署这件事本质上没有太多高深理论翻来覆去就那么几个点产物要打包对、路径要写对、服务器要配对、缓存策略要想清楚。但把这几个点串起来需要真正理解“开发环境”和“生产环境”的差别而不是停留在“命令能跑就行”的层面。如果你也正在经历第一次上线按照这篇的顺序把每一步过一遍你会发现自己对 Vue 项目的理解会上一个台阶——毕竟学会部署才是真的学会了一个项目的完整闭环。