React Router框架模式下禁用SSR的注意事项与解决方案

背景介绍

在使用React Router框架模式开发单页应用(SPA)时，开发者可能会遇到一个常见问题：即使明确设置了ssr: false禁用服务器端渲染，某些浏览器API(如localStorage)仍然会在开发环境的服务器端执行，导致报错。这种现象与传统的SPA开发体验有所不同，需要开发者特别注意。

问题本质

在React Router的框架模式下，开发服务器仍然会作为应用框架运行，即使禁用了SSR。这是因为：

1. 开发环境下需要支持热模块替换(HMR)等开发特性
2. 服务器需要提供基本的应用服务功能
3. 开发服务器需要处理路由请求并返回正确的页面结构

这与生产环境不同，在生产环境中构建输出是纯粹的静态文件，由客户端完全接管路由和渲染。

解决方案

1. 使用条件判断保护浏览器API

对于必须使用浏览器API的代码，添加运行环境判断：

if (typeof window !== 'undefined') {
  // 安全使用localStorage等浏览器API
  const token = localStorage.getItem('token');
}

2. 使用clientLoader加载数据

React Router提供了专门的客户端数据加载方案：

export async function clientLoader() {
  // 这里可以安全使用浏览器API
  const data = localStorage.getItem('userData');
  return data;
}

3. 延迟加载策略

对于非关键性的浏览器API调用，可以考虑在组件挂载后执行：

useEffect(() => {
  // 组件挂载后执行，确保在浏览器环境
  const settings = localStorage.getItem('appSettings');
}, []);

开发与生产环境差异

开发者需要注意，这种服务器端执行的情况主要存在于开发环境。生产环境构建后：

1. 所有代码都在客户端执行
2. 路由完全由客户端处理
3. 不需要担心服务器端执行浏览器API的问题

最佳实践建议

1. 将浏览器API相关逻辑集中管理，便于维护和环境判断
2. 对于认证令牌等敏感信息，考虑使用HttpOnly Cookie而非localStorage
3. 使用TypeScript时，可以为window对象添加类型声明，避免类型错误
4. 在项目文档中明确标注浏览器API的使用限制

通过以上方法，开发者可以在React Router框架模式下既享受开发便利性，又避免浏览器API在服务器端执行的问题。