React Router项目中Vite构建路径配置的最佳实践

在React Router项目中，当开发者需要将应用部署到子路径时，经常会遇到静态资源路径配置的问题。本文将以一个典型场景为例，详细介绍如何正确配置Vite构建工具，确保React Router应用在子路径下能够正常工作。

问题背景

在基于React Router 7.5.1和Vite构建的项目中，开发者通常会尝试通过package.json中的"homepage"字段来配置应用的基础路径。然而，这种方法在Vite构建的项目中并不生效，因为Vite并不识别这个配置项。

正确配置方法

1. 配置React Router的basename

首先，需要在react-router.config.ts文件中设置basename属性，这个值应该与你的部署子路径一致：

export default {
  basename: "/myapp/", // 注意结尾的斜杠
  ssr: false,
} satisfies Config;

basename属性告诉React Router所有路由都应该基于这个基础路径。结尾的斜杠很重要，它能确保路由匹配的正确性。

2. 配置Vite的base选项

接下来，在vite.config.ts文件中，需要设置base属性，这个值必须与basename保持一致：

export default defineConfig({
  plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
  base: '/myapp/' // 同样需要结尾斜杠
});

这个配置会告诉Vite：

• 所有静态资源(JS、CSS等)的引用路径都会以这个base为前缀
• 生成的index.html中会使用正确的前缀路径加载资源

3. 构建与验证

完成上述配置后，执行构建命令：

npm run build

检查生成的build/client/index.html文件，应该能看到资源路径都正确加上了前缀：

<link rel="modulepreload" href="/myapp/assets/manifest-9789c1e8.js"/>

为什么这样做有效

Vite的base配置是专门为这种场景设计的，它会影响：

1. 资源加载路径：所有静态资源引用都会自动加上base前缀
2. 路由系统：与React Router的basename配合，确保前端路由能正确处理
3. 开发服务器：在开发时也能模拟子路径部署的环境

常见问题与解决方案

1. 路径404错误：确保basename和base配置完全一致，包括结尾斜杠
2. 开发环境与生产环境不一致：可以在vite.config.ts中根据环境变量动态设置base
3. 路由跳转问题：检查所有组件是否使用了相对路径，避免硬编码绝对路径

总结

在Vite构建的React Router项目中，正确配置子路径部署需要同时设置：

• React Router的basename
• Vite的base选项

这两个配置必须保持完全一致，包括结尾的斜杠。通过这种方式，可以确保应用在子路径下能够正确加载资源和处理路由。相比传统的webpack/CRA项目，Vite提供了更直接和明确的配置方式，避免了package.json中homepage配置的混淆。