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

问题背景

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

技术原理分析

React Router 的 SSR 实现依赖于 createStaticHandler 和 createStaticRouter 这两个核心 API。在服务端渲染流程中，数据加载(loader)的执行与路由匹配密切相关，而 basename 的设置会直接影响路由匹配的结果。

当 basename 被设置为非根路径(如"/app")时，服务端路由匹配会基于这个基础路径进行。如果在数据加载完成后才设置 basename，会导致以下问题：

1. 初始路由匹配时没有考虑 basename，可能导致错误的匹配结果
2. 数据加载器(loader)执行时使用的路径与实际渲染路径不一致
3. 最终 useLoaderData 无法获取到正确的加载数据

解决方案

正确的做法是在创建静态处理器(createStaticHandler)时就明确指定 basename，而不是在数据加载完成后才设置。具体实现方式如下：

const handler = createStaticHandler(routes, {
  basename: "/app" // 在此处直接指定basename
});

const webRequest = createFetchRequest(req);
const context = await handler.query(webRequest);

如果 basename 需要动态确定，应该在创建处理器前就计算出正确的 basename 值，而不是在中间件处理过程中后期添加。

深入理解

这个问题的本质在于 React Router 的数据加载机制与服务端渲染流程的时序关系：

1. 数据加载发生在路由匹配阶段
2. basename 影响路由匹配结果
3. 因此 basename 必须在数据加载前确定

这种设计确保了数据加载与最终渲染使用相同的路由上下文，避免了数据与视图不一致的情况。

最佳实践建议

1. 尽量在应用初始化阶段确定 basename
2. 如果 basename 必须动态确定，应该在创建静态处理器前完成计算
3. 避免在中间件处理过程中修改已创建的处理器或上下文
4. 对于复杂的动态路由场景，考虑使用更高级的状态管理方案

总结

React Router 的 SSR 实现对于 basename 的处理有其特定的时序要求。理解这一机制有助于开发者避免类似 useLoaderData 失效的问题，构建更健壮的服务器渲染应用。关键在于确保路由匹配、数据加载和最终渲染使用一致的上下文环境。