Vue3 项目部署到服务器报错：3 个最常见错误与排查顺序

能，而且绝大多数 Vue3 部署报错都集中在「构建产物」和「服务器配置」这两层，并不是 Vue3 框架本身的问题。最常见的三类是：路由 history 模式刷新子路由 404、开发期的代理在服务器上彻底失效、以及 base 路径或环境变量配错导致资源白屏。它们的适用边界很清楚：本地 npm run dev 正常，不等于生产构建后也能跑，因为开发服务器帮你兜底了很多事。下面把排查顺序、各自成因和修复命令一次讲清，先把「为什么本地好端端的、一上线就挂」这件事说透。（以上根因与命令依据 Vue3 官方部署文档与 Nginx 文档。）

先看结论

选哪条先查，取决于你看到的是「页面根本打不开」还是「页面开了但数据没来」。

要系统理解 Vue3 的构建与部署边界，可以先过一遍 Vue3 教程，把路由模式和打包配置这两条线分清楚，再看下面的反例会更顺。

一、构建产物与静态目录：先确认丢没丢东西

部署前先在本地运行一次生产构建，看 dist 目录是否真的生成：

npm run build
ls -lh dist

预期结果是 dist 下出现 index.html 和 assets 目录；如果 dist 根本没生成，说明构建脚本或依赖本身有问题，先别急着怪服务器。这一步配置的是「把什么交给服务器」，出错时先检查构建命令和输出目录，再往下走。

很多 Vue3 部署报错其实在构建阶段就埋下了：比如 public 目录里的文件没被拷贝、或者 assetsDir 配错导致资源路径不对。构建完用 ls dist/assets 看一眼产物是否齐全，能省掉后面一大半排查时间。记住一个判据——构建产物不完整，后面所有部署报错都查不出根因。如果 dist 里只有 index.html 没有 assets，多半是静态资源没被打包进去，或者 public 目录命名不对；这种部署报错在 CI 里很常见，构建日志里通常会有 warning，别只看退出码为 0 就以为成功。配套把 Vue3 实战补齐，也可以看 Vue3 课程。

二、路由 history 模式：刷新子路由 404

Vue Router 的 history 模式依赖服务端把所有路径都兜底回 index.html。开发期 Vite 帮你做了，生产服务器没配就会 404。这也是最容易被误判的一类部署报错：本地切换路由正常，一刷新就 404，根因从来不在路由配置，而在服务器少了兜底。

location / {
    try_files $uri $uri/ /index.html;
}

失败时（比如刷新 /user/123 报 404），先检查服务器有没有这条兜底规则，再修复：把上述 try_files 加进 Nginx 的 location，重载后验证刷新不再 404。这一步的边界是——hash 模式不需要兜底，history 模式必须兜底，选模式时就该想清楚。如果你用的是静态托管（如对象存储或 GitHub Pages），也要在后台配「错误页 / 404 回退」指向 index.html，否则同样会 404。静态托管平台（对象存储、Pages 类服务）没有 Nginx 配置文件，兜底要在控制台或 _redirects / 404.html 里配；别在本地试通了 Nginx 就以为上线也通，两套机制要分别验证。

三、开发期代理在服务器上失效：接口 404 或 CORS

开发期你在 vite.config 里写的 proxy 只活在 dev server，上线后这段配置不会跟着走。服务器上要么用 Nginx 反代，要么让后端直接放开跨域。

location /api/ {
    proxy_pass http://backend;
    proxy_set_header Host $host;
}

验证是否真的通：在服务器上用 curl 直接打后端，再打带 /api 的地址，看是否都返回 200。从性能取舍看，统一在 Nginx 收口比每个前端各自处理跨域更干净，也更好排查。这类部署报错的特征是「本地能调接口、线上调不通」，抓住「dev proxy 不跟随上线」这一点就能快速定位。Nginx 配合 SSI 等高级用法的细节，可随时翻 SSI 速查手册。如果后端是 Spring Boot 这类内嵌容器的服务，也可以直接在应用层加 CORS 注解，但生产仍建议收口到网关或 Nginx，避免每个服务各自开放。

四、base 路径与环境变量配错：资源白屏

如果你的站点挂在子路径（如 https://example.com/app/），没设 base: '/app/' 会导致 index.html 里去抓 /assets/xxx.js，而真实路径是 /app/assets/xxx.js，于是白屏。

// vite.config.js
export default {
  base: '/app/',
  // 环境变量区分开发与生产
  envPrefix: 'VITE_'
}

这类错误的排错要点是：打开浏览器开发者工具的 Network，看 404 的资源路径是不是少了一段前缀。修复时把 base 和部署路径对齐，再重新构建验证。另外 VITE_ 开头的环境变量只在构建期注入，本地写死的常量上线后不会自动变成服务器地址，这也是一类隐蔽的部署报错来源——常见于接口域名写死成 localhost，上线后请求全打回本地。这类问题排查时，把 console.log 打出的接口地址和浏览器 Network 里的实际请求地址对照，往往一眼就能看出是 base 还是环境变量写错了——部署报错最怕凭直觉改配置，对照实际请求才是正道。

总结

• Vue3 部署报错大多在「构建产物」和「服务器配置」两层，不在框架本身。
• history 模式必须让服务器兜底回 index.html，否则刷新子路由 404。
• 开发期 proxy 不跟随上线，服务器上用 Nginx 反代或后端放开跨域。
• base 与部署子路径不一致会让资源 404 白屏，Network 里一眼能看出路径差在哪。
• 环境变量只在构建期注入，本地常量不会自动变成服务器地址。
• 排查顺序：先看构建产物在不在，再看路由兜底，最后查代理与 base。

常见问题

Q：为什么本地 dev 正常、build 之后却白屏？

几乎都是资源路径问题：base 没设对，或者部署到了子路径却用了根路径引用。打开 Network 看 404 的 URL，缺的那段前缀就是 base 该填的值。

Q：刷新页面才 404、首次进入正常，是怎么回事？

这是典型的 history 模式没兜底：首次进入走 index.html，刷新后服务器直接找 /user/123 这个文件，找不到就 404。加 try_files 兜底即可。

Q：为什么本地能调的接口，到服务器就 404 或跨域？

开发期 proxy 没迁到生产。服务器上用 Nginx 反代 /api，或在后端配置 CORS，别指望 dev server 的 proxy 替你上班。

延伸学习

• JSP 入门课程：想理解服务端是怎么接管请求的，这本 Java 服务器页面课程能补一层。
• html5 怎么部署到服务器：从静态站到动态站，部署思路一次理清。
• Txyvue3 课程：Vue3 配套微课，把构建与部署串成一条线。