Vite子路由部署后无法访问解决方法

Vite 构建的单页应用部署后子路由（如 `/login`）直接访问报 404 或跳回首页，根本原因在于静态服务器未启用 SPA 路由回退机制——开发时 Vite 自动处理了 History 模式下的路径兜底，但生产环境需手动配置服务端将所有非静态资源请求重写为 `index.html`，让前端路由接管；本文详解 Vercel、Netlify 和 Nginx 的标准重写配置，并对比分析 Hash 模式的临时替代方案及关键注意事项，助你彻底解决路由不可直达、无法刷新、收藏失效等痛点，真正实现语义化 URL 的开箱即用。

Vite 构建的单页应用（SPA）部署到静态托管平台（如 Vercel、Netlify、Nginx）后，直接访问 /login 等子路径返回 404 或跳回首页，根本原因是服务端未正确配置 SPA 路由回退机制。

Vite 构建的单页应用（SPA）部署到静态托管平台（如 Vercel、Netlify、Nginx）后，直接访问 `/login` 等子路径返回 404 或跳回首页，根本原因是服务端未正确配置 SPA 路由回退机制。

当你在本地开发时（npm run dev），Vite 开发服务器默认启用 HTML 5 History 模式路由的自动回退——即所有未知路径均返回 index.html，再由前端路由（如 Vue Router 或 React Router）接管并渲染对应页面。但生产环境的静态服务器默认不具备该能力：它会严格按文件路径查找资源。例如请求 https://your-site.com/login，服务器会尝试寻找 ./login/index.html 或 ./login.html，而你的构建产物中通常只有 index.html 和静态资源，因此返回 404 或默认首页。

✅ 正确解决方案（二选一）

方案一：配置服务端路由回退（推荐，保留 History 模式）

确保所有非资源请求（即非 .js/.css/.png 等）均返回 index.html，让前端路由接管。

• Vercel（你当前使用的平台）：在项目根目录添加 vercel.json：

  {
    "rewrites": [
      { "source": "/(.*)", "destination": "/index.html" }
    ]
  }

  ✅ 部署后，所有路径（如 /login, /dashboard）都会加载 index.html，Vue Router/React Router 即可正常解析。

• Netlify：在根目录创建 _redirects 文件：

  /* /index.html 200

• Nginx（自托管）：在 location 块中添加：

  location / {
    try_files $uri $uri/ /index.html;
  }

方案二：改用 Hash 模式路由（快速验证，不推荐长期使用）

修改前端路由配置，避免依赖服务端支持：

• Vue Router（v4）：

  // router/index.ts
  import { createRouter, createWebHashHistory } from 'vue-router'
  
  const router = createRouter({
    history: createWebHashHistory(), // ← 替换为 hash 模式
    routes: [/* ... */]
  })

• React Router（v6+）：

  import { HashRouter } from 'react-router-dom'
  
  ReactDOM.createRoot(document.getElementById('root')!).render(
    <HashRouter> {/* ← 替换 BrowserRouter */}
      <App />
    </HashRouter>
  )

  此时 URL 变为 https://yoursite.com/#/login，无需服务端配置，但 SEO 和分享体验较差。

⚠️ 注意事项

• 检查 vite.config.ts 中 base 配置是否与部署路径匹配（如部署在子路径 /app/，需设 base: '/app/'）；
• 确保构建产物中 index.html 的