Vite+React配置basename后构建部署资源加载失败问题排查

使用 React 18.2.0、Vite 4.4.0，路由采用 react-router-dom 6.14.1，需将应用部署到 /packers 路径。开发环境运行正常，但构建后用 Express.js 4.18.2 部署时仅能加载 HTML，无法加载资源；若不配置 basename 则构建部署正常。

项目相关文件 #

main.jsx

import ReactDOM from "react-dom/client";
import { RouterProvider } from "react-router-dom";
import { router } from "./routes/routes";

ReactDOM.createRoot(document.getElementById("root")).render(
  <RouterProvider router={router} />
);

routes.jsx

import { createBrowserRouter, redirect } from "react-router-dom";
import Main from "../Layout/Main";
import Home from "../pages/Home";
import Login from "../pages/Login";
import Recovery from "../pages/Recovery";
import Signup from "../pages/Signup";
import ErrorPage from "../pages/ErrorPage";

const routes = [
  {
    path: "/",
    element: <Main />,
    errorElement: <ErrorPage />,
    children: [
      {
        path: "/",
        element: <Home />,
      },
      {
        path: "/login",
        element: <Login />,
      },
      {
        path: "/reset",
        element: <Recovery />,
      },
      {
        path: "/signup",
        element: <Signup />,
      },
    ],
  },
];

export const router = createBrowserRouter(routes, {
  basename: "/packers"
});

vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import svgr from "vite-plugin-svgr";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), svgr()],
  base: '/packers'
});

• 开发与生产环境资源解析逻辑不同：
  开发时 Vite 内置的开发服务器会自动代理资源请求，能正确识别 base 配置的 /packers 路径，将请求映射到本地资源。但构建后，静态资源的路径被硬编码为 /packers/xxx，而 Express 默认只处理根路径下的静态资源请求，无法匹配到这些带前缀的资源路径，导致资源加载失败。
• 前端路由的回退规则未配置：
  设置 basename 后，前端路由的所有路径都以 /packers 开头。当用户刷新页面或直接访问这类路由时，Express 会尝试寻找对应的后端路由，找不到就返回 404，而非返回 index.html 交由前端路由处理，进一步引发页面异常。

1. 调整 Express 服务器配置 #

修改 Express 代码，让它正确映射 /packers 路径的静态资源，并处理路由回退：

const express = require('express');
const path = require('path');
const app = express();

// 将 /packers 路径的请求映射到构建后的 dist 目录
app.use('/packers', express.static(path.join(__dirname, 'dist')));

// 所有 /packers 开头的路由请求，返回 index.html 让前端路由处理
app.get('/packers/*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

2. 确认配置一致性 #

确保 vite.config.js 中的 base: '/packers' 和 routes.jsx 中 createBrowserRouter 的 basename: '/packers' 完全一致，避免拼写错误或路径格式差异（比如是否带末尾斜杠，两边要统一）。

3. 验证构建后的资源路径 #

构建完成后，检查 dist/index.html 中的资源引用，确认 JS/CSS 文件的路径均以 /packers/ 开头（例如 <script type="module" src="/packers/assets/index.xxx.js"></script>），确保路径生成正确。

内容的提问来源于stack exchange，提问作者dreygur