Vue3+Vite+Nginx部署后刷新404白屏问题的完整排查指南

症状：Vue 单页应用（SPA）首次进入页面正常，一刷新就白屏或 404。

一、问题现象

• 访问 http://your-server/dashboard/home → 正常
• 在该页面按 F5 / Ctrl+R 刷新 → 白屏，控制台报大量 404
• 浏览器地址栏 URL 没变，但页面什么都加载不出来

二、问题本质：两个独立原因叠加

刷新白屏这个现象，背后其实有两个完全不同的原因，必须同时解决，缺一不可。

原因一：Nginx 不认识 Vue Router 的路由路径（基础原因）

Vue Router 使用 HTML5 History 模式（createWebHistory）时，/dashboard/home 这类路径是纯前端路由，不对应任何真实文件。

首次进入为什么正常？

用户从首页 / 进入应用，Nginx 找到真实的 index.html 并返回，Vue 的 JS 运行后，Vue Router 接管所有导航。用户点击菜单跳转到 /dashboard/home，这是 Vue Router 通过浏览器 History.pushState() 完成的，根本没有向服务器发送任何 HTTP 请求，所以正常。

刷新为什么失败？

刷新时浏览器向服务器发出真实的 HTTP 请求：GET /dashboard/home。Nginx 在硬盘上找不到对应的文件，于是返回 404。

浏览器刷新  →  HTTP GET /dashboard/home  →  Nginx 找文件  →  找不到  →  404

Nginx 修复方式：配置 try_files，当找不到文件时，统一回退到 index.html，让 Vue Router 接管路由判断。

location / {
    root /home/your-app/dist;
    index index.html;
    try_files $uri $uri/ /index.html;   # 关键：找不到文件就返回 index.html
}

原因二：VITE_PUBLIC_PATH = ./导致资源路径错位（隐藏原因，也是本文重点）

仅修复 Nginx 之后，很多人发现：刷新后页面不再 404 了，但变成了白屏——HTML 返回了，JS/CSS 却全部 404。

这是因为 Vite 打包时，base 配置项（对应 VITE_PUBLIC_PATH）决定了 index.html 里所有静态资源的引用方式。

./（相对路径）vs/（绝对路径）的区别

当 VITE_PUBLIC_PATH = ./ 时，打包产物 index.html 内容如下：

<script type="module" crossorigin src="./assets/index-BsHqOBiK.js"></script>
<link rel="stylesheet" href="./assets/index-Df9KKQPD.css" rel="external nofollow" >

./ 是相对于当前页面 URL 的路径，浏览器会根据当前 URL 来解析：

当 VITE_PUBLIC_PATH = / 时，打包产物 index.html 内容如下：

<script type="module" crossorigin src="/assets/index-BsHqOBiK.js"></script>
<link rel="stylesheet" href="/assets/index-Df9KKQPD.css" rel="external nofollow" >

/ 开头是绝对路径，浏览器无论在哪个 URL 下，都固定从网站根路径加载：

为什么首次进入正常，刷新才白屏？

因为"首次进入"通常是从网站根路径 / 加载的 index.html，此时 ./ 被正确解析为 /assets/...，资源加载成功，Vue 启动。

后续的页面跳转（/dashboard/home）是 Vue Router 纯前端路由，不触发新的 HTML 请求，资源早就加载完毕了，所以一切正常。

刷新时，浏览器重新请求 /dashboard/home 对应的 HTML，Nginx 回退返回 index.html，但浏览器此时 URL 是 /dashboard/home，./assets/... 被解析为 /dashboard/assets/...，全部 404，白屏。

三、完整修复步骤

第一步：修改 Vite 打包配置

找到项目里的 .env.production（或 vite.config.ts 里的 base 字段）：

# .env.production
- VITE_PUBLIC_PATH = ./
+ VITE_PUBLIC_PATH = /

或直接在 vite.config.ts 里：

export default defineConfig({
-  base: './',
+  base: '/',
})

第二步：检查 Nginx 配置

确保 Nginx 有正确的 try_files 兜底：

server {
    listen 80;
    server_name your-domain.com;

    root /home/your-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;   # 必须有这行
    }

    # 静态资源缓存（可选）
    location ~* \.(js|css|png|jpg|gif|ico|svg|woff2?)$ {
        expires 30d;
        access_log off;
    }
}

注意 try_files 最后参数必须是 URI（如 /index.html），不能是文件系统绝对路径（如 /home/app/dist/index.html），否则 Nginx 会把它当 URL 再次查找，导致死循环或 404。

第三步：重新构建并部署

npm run build
# 将 dist/ 目录上传到服务器
nginx -s reload

第四步：验证构建产物

grep -o 'src="[^"]*"' dist/index.html | head -5

正确输出（绝对路径，/ 开头）：

src="/assets/index-BsHqOBiK.js"

错误输出（相对路径，./ 开头）：

src="./assets/index-BsHqOBiK.js"

四、常见错误配置（避坑）

错误一：try_files 用文件路径而非 URI

# ❌ 错误：/home/app/dist/index.html 被当作 URL 解析
try_files $uri $uri/ /home/app/dist/index.html;

# ✅ 正确：/index.html 是 URL 路径，Nginx 会用 root 拼接找到真实文件
try_files $uri $uri/ /index.html;

错误二：alias + try_files 兜底路径写错

location /app {
    alias /home/app/dist/;

    # ❌ 错误：兜底 URI 用 /index.html，
    # 这会跳回 location /，然后用 root 目录找文件，与 alias 目录不同
    try_files $uri $uri/ /index.html;

    # ✅ 正确：兜底 URI 带上 location 前缀，让请求再次进入这个 location
    try_files $uri $uri/ /app/index.html;
}

错误三：Hash 模式不需要任何 Nginx 配置

如果你使用的是 createWebHashHistory（URL 带 #，如 /#/dashboard/home），# 后面的内容不会发送给服务器，Nginx 永远只收到 GET /，不存在刷新 404 问题，无需任何特殊配置。

只有 createWebHistory（无 # 的干净 URL）才需要上述配置。

五、总结

两个问题独立存在，必须同时解决。实际排查时，往往先修了 Nginx 发现还是白屏，再去查资源请求路径，才发现是打包配置的问题。

以上就是Vue3+Vite+Nginx部署后刷新404白屏问题的完整排查指南的详细内容，更多关于Vue3 Vite Nginx部署后刷新404白屏的资料请关注脚本之家其它相关文章！

最新评论