React Router SSR 中自定义 basename 导致 useLoaderData 失效问题解析

问题背景

在使用 React Router 进行服务端渲染(SSR)时，开发者可能会遇到一个特殊问题：当设置了自定义的 basename 后，在服务端渲染过程中 useLoaderData 钩子返回 undefined 而非预期的数据。这种情况通常发生在需要动态确定 basename 的服务端环境中。

问题现象

在 SSR 实现中，当开发者按照以下流程操作时会出现问题：

1. 首先创建静态处理器(createStaticHandler)并执行查询
2. 在获取到上下文(context)后设置 basename
3. 然后在组件中使用 useLoaderData 获取数据

此时服务端渲染会失败，因为 useLoaderData 无法获取到 loader 函数返回的数据。但如果将 basename 设置为根路径("/")，则一切工作正常。

问题根源

这个问题的根本原因在于 basename 的设置时机不正确。React Router 的设计要求 basename 必须在创建静态处理器时就确定，而不是在查询执行后才设置。这是因为：

1. 路由匹配过程依赖于 basename 来正确解析路径
2. 数据加载(loader)的执行发生在路由匹配阶段
3. 如果在路由匹配后才设置 basename，会导致路由系统无法正确关联 loader 返回的数据

解决方案

正确的做法是在创建静态处理器时就提供 basename 参数：

const { query } = createStaticHandler(routes, {
  basename: "/your-basename" 
});

如果 basename 需要动态确定，应该在创建处理器之前就计算出 basename 值，而不是在查询之后才设置。

深入理解

React Router 的服务端渲染流程大致如下：

1. 创建静态处理器(包含 basename 配置)
2. 处理器根据请求路径匹配路由
3. 执行匹配路由的 loader 函数
4. 收集所有 loader 返回的数据
5. 渲染应用并将数据注入到响应中

如果在流程后期才设置 basename，会导致路由匹配和数据加载阶段使用错误的路径基准，从而使数据加载与组件渲染脱节。

最佳实践

对于需要动态 basename 的场景，建议：

1. 在接收到请求时立即确定 basename
2. 基于确定的 basename 创建静态处理器
3. 然后执行正常的 SSR 流程

这样可以确保路由系统的各个阶段都使用一致的路径基准，避免数据加载与渲染不匹配的问题。

总结

React Router 的 basename 配置是路由系统的基石之一，必须在创建处理器时就确定。理解这一点对于实现正确的服务端渲染至关重要，特别是在需要支持多部署环境或动态路径基准的复杂应用中。通过遵循正确的配置顺序，可以避免 useLoaderData 失效等常见问题，构建出稳定可靠的 SSR 应用。