vite 构建的单页应用（spa）部署到静态托管平台（如 vercel、netlify、nginx）时，若未正确配置路由回退机制，会导致除根路径（/）外的所有路由（如 /login、/dashboard）返回 404 —— 这是因服务端未将深层路由重写为 index.html 所致。
vite 构建的单页应用（spa）部署到静态托管平台（如 vercel、netlify、nginx）时，若未正确配置路由回退机制，会导致除根路径（/）外的所有路由（如 /login、/dashboard）返回 404 —— 这是因服务端未将深层路由重写为 index.html 所致。
当你访问 https://www.php.cn/link/585a999cb6b22b1e8ced8066e496784c 时页面空白或报 404，而首页 https://www.php.cn/link/5280ac46ea82dd14e8eb0b1cfd2beb20 正常，这并非前端代码（如 Vue Router 或 React Router）本身有误，而是服务端（或托管平台）无法识别前端路由——它尝试在服务器上查找物理存在的 /login/index.html 文件，但该文件并不存在（Vite 打包后只有 index.html + 静态资源）。
根本原因在于：Vite 默认使用 HTML5 History 模式（即 createWebHistory），它依赖浏览器 History API 实现无刷新跳转，但要求服务端对所有非资源请求（如 /login, /user/profile）统一返回 index.html，再由前端路由接管渲染。若服务端未做此配置，就会直接返回 404。
✅ 正确解决方案分两类，按部署环境选择：
✅ 方案一：使用托管平台专属配置（推荐，零代码修改）
▪ Vercel（你当前使用的平台）
在项目根目录添加 vercel.json 文件：
{
"rewrites": [
{ "source": "/(.*)", "destination": "/index.html" }
]
}✅ 原理：将所有路径请求（除真实存在的 JS/CSS/图片等资源外）重写为 index.html，交由前端路由处理。
⚠️ 注意：确保 vercel.json 与 package.json 同级，并已提交至 GitHub 仓库主分支。
▪ Netlify
在项目根目录创建 _redirects 文件（无扩展名）：
/* /index.html 200
或在 netlify.toml 中配置：
[[redirects]] from = "/*" to = "/index.html" status = 200
▪ GitHub Pages
需启用 vite-plugin-gh-pages 或手动配置：在 vite.config.ts 中设置 base: '/
✅ 方案二：改用 Hash 模式（快速验证，适合开发/临时部署）
修改前端路由初始化方式（以 Vue Router 为例）：
// router/index.ts
import { createRouter, createWebHashHistory } from 'vue-router'
const router = createRouter({
history: createWebHashHistory(), // ← 替换为 createWebHashHistory()
routes: [ /* ... */ ]
})此时 URL 变为 https://example.com/#/login，# 后部分由前端解析，无需服务端配合。但缺点是 SEO 不友好、URL 不美观，仅建议用于调试或内部测试。
? 验证与排查要点
- ✅ 检查构建产物：运行 npm run build 后，dist/ 目录下应仅有 index.html 及 assets/ 文件夹，不应存在 login/index.html 等子页面文件（那是 SSR 或多页应用特征）；
- ✅ 确认路由模式：检查代码中是否使用 createWebHistory()（History 模式）而非 createWebHashHistory()；
- ✅ 查看网络请求：在浏览器 DevTools → Network 标签中刷新 /login，观察是否返回 index.html（状态码 200）还是 404；
- ❌ 错误做法：试图在 src/router/index.ts 中“修复”——前端路由逻辑本身无错，问题在部署层。
? 总结
| 场景 | 推荐方案 | 关键动作 |
|---|---|---|
| Vercel / Netlify / Cloudflare Pages | 平台重写规则 | 添加 vercel.json 或 _redirects |
| 自建 Nginx | 服务端配置 | location / { try_files $uri $uri/ /index.html; } |
| 快速验证/兼容旧环境 | 切换 Hash 模式 | 修改 createRouter({ history: createWebHashHistory() }) |
部署不是“上传完就结束”，SPA 的 History 模式天然需要服务端协同。一次正确的重写配置，即可让 /login、/admin、/user/123 全部正常加载——这才是现代前端工程化的关键闭环。
