如何解决 Vite 项目部署后仅首页可访问、其他路由 404 的问题

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: ‘//’，并确保路由 createWebHistory(‘//’) 匹配；同时通过 .nojekyll 和 404.html 回退（不推荐，History 模式支持有限）。

✅ 方案二：改用 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 全部正常加载——这才是现代前端工程化的关键闭环。