Vue3 本地打包启动白屏解决思路！! !

“为什么我访问 http://127.0.0.1:5501/index.html 白屏，删了 index.html 再访问 / 就又活过来了？”
—— 你的项目与 SPA 路由的“宫斗大戏”

---

一、问题复现

• 场景

  1. 本地通过 VSCode Live Server（或其他静态服务器）启动了打包后的 Vue3 应用目录（假设为 dist/）。

  2. 访问 http://127.0.0.1:5501/index.html，页面一片空白（白屏）。

  3. 删掉根目录下的 index.html，再次访问 http://127.0.0.1:5501/，页面又瞬间正常渲染了！

• 本能误区

  • “是不是文件丢了？是不是打包坏了？”

  • 反复打包、重装依赖，也无济于事。

---

二、幕后黑手：静态挂载 & 路由拦截双重锅

1. 静态服务器挂载顺序

多数本地静态服务器（Live Server、http-server、serve 等）默认会：

1. 优先寻找请求路径对应的静态文件（如 index.html、.js、.css 等）。

2. 若文件存在，则直接返回该文件，不再回退到其它目录。

3. 若文件不存在，则“fallback”到根目录的 index.html（如果开启了单页应用回退）。

因果分析

• 当你在项目根目录下也放置了一份 “空白” index.html（比如不小心把源码的空白模板也上传进 dist/），访问 /index.html 时，服务器把它当作静态文件直接返回，就一片白。

• 删除后，请求 /index.html 找不到后，触发回退，将真正的打包入口 dist/index.html 返回，于是页面正常。

2. Vue Router History 模式“误判”

如果你在项目中使用了 createWebHistory()（History 模式）：

• 访问 http://…/index.html

  • 浏览器加载了文件后，Vue 启动时会把当前 URL 路径 /index.html 当成一个路由去匹配。

  • 由于通常路由表里并没有对应 /index.html 的条目，结果匹配失败，组件不渲染，就白屏了。

• 访问 http://…/

  • 路径是 /，正好匹配首页组件，应用正常启动。

---

三、最终解法：规范挂载 & 路由回退

下面以 Nginx 为例，示范如何在生产（或本地模拟生产）环境下正确部署，彻底杜绝“删了才行”的尴尬。

1. Nginx 标准配置

server {
    listen       80;
    server_name  your.domain.com;            # 替换成你的域名或 IP

    # ① 指定根目录为打包输出
    root   /var/www/myapp;                   # 假设你把 dist 放这里
    index  index.html;

    # ② 静态资源走文件系统，开启长缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|ttf|woff2?)$ {
        expires    30d;
        access_log off;
    }

    # ③ 单页应用路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }

    # ④ 全部 404 也返回入口页（可选）
    error_page 404 /index.html;
}

部署步骤

1. 打包 & 上传

   npm run build
   scp -r dist/* user@server:/var/www/myapp/
   

2. 放置配置

   • CentOS：直接放在 /etc/nginx/conf.d/myapp.conf

3. 测试 & 重载

   sudo nginx -t
   sudo systemctl reload nginx
   

2. VSCode Live Server（本地调试）快速修复

在项目根目录下新建或修改 .vscode/settings.json：

{
  "liveServer.settings.root": "dist"
}

保存后重启 Live Server，即可让它把 dist/ 当作站点根，不再被源码根目录下的文件干扰。

---

四、补充技巧

1. 避免手动地址栏写 index.html
   直接访问 / 即可，现代服务器都会自动加载 index.html。

2. Hash 模式降级
   如果你不想配置服务器路由回退，可在 Vue Router 中改为：

   import { createRouter, createWebHashHistory } from 'vue-router'
   const router = createRouter({
     history: createWebHashHistory(),
     routes: [ /* ... */ ]
   });
   

   所有 URL 会加上 #/，彻底绕过服务器路由判断。

3. CI/CD 自动发布
   在打包完成后，结合 GitHub Actions / GitLab CI 自动将 dist/ 同步到服务器或 CDN，避免漏传、错传文件。

---

五、结语

原来「删除一份文件就能跑起来」背后的真相，既有静态服务器的挂载机制，也有 Vue Router 的路由解析逻辑。掌握了这两点，你就能：

• 保证打包目录干净、无冗余模板

• 正确配置服务器根目录和单页应用回退

• 根据场景灵活切换 History/Hash 模式

从此，无论在本地调试还是在线上发布，都能稳稳启动，再也不用靠“删档”才能爽跑！如果你也碰到过类似诡异白屏，赶紧对照本文排查一遍吧~