当前位置：首页 > news >正文

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

news 来源：原创 2025/4/20 7:40:50

“为什么我访问 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 等）默认会：

优先寻找请求路径对应的静态文件（如 index.html、.js、.css 等）。
若文件存在，则直接返回该文件，不再回退到其它目录。
若文件不存在，则“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;
}

部署步骤

打包 & 上传

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

放置配置
- CentOS：直接放在 /etc/nginx/conf.d/myapp.conf

测试 & 重载

sudo nginx -t
sudo systemctl reload nginx

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

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

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

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

四、补充技巧

避免手动地址栏写 index.html
直接访问 / 即可，现代服务器都会自动加载 index.html。
Hash 模式降级
如果你不想配置服务器路由回退，可在 Vue Router 中改为：
```
import { createRouter, createWebHashHistory } from 'vue-router'
const router = createRouter({history: createWebHashHistory(),routes: [ /* ... */ ]
});
```
所有 URL 会加上 #/，彻底绕过服务器路由判断。
CI/CD 自动发布
在打包完成后，结合 GitHub Actions / GitLab CI 自动将 dist/ 同步到服务器或 CDN，避免漏传、错传文件。