React Router框架模式下SSR禁用与浏览器API使用指南

前言

在使用React Router框架模式开发单页应用(SPA)时，开发者经常会遇到一个典型问题：即使明确设置了ssr: false禁用服务器端渲染，应用代码仍然会在服务器环境中执行。这种现象会导致依赖浏览器API(如localStorage)的代码在服务器端运行时抛出错误。

问题本质分析

React Router框架模式在开发环境下仍然会使用服务器作为应用框架，主要出于以下考虑：

1. 提供开发服务器功能
2. 支持热模块替换(HMR)
3. 保持开发和生产环境一致性

这种设计意味着即使在SPA模式下，开发服务器仍然会执行部分应用代码来建立完整的开发环境。而在生产环境中，构建输出将是纯粹的客户端代码，由静态服务器直接提供。

解决方案

1. 使用环境判断保护浏览器API

对于直接使用浏览器API的代码，最简单的解决方案是添加环境判断：

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

2. 使用clientLoader加载数据

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

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

export function Component() {
  const data = useLoaderData();
  // 渲染组件
}

3. 状态管理替代方案

对于需要持久化的状态，考虑使用以下替代方案：

1. 将状态提升到React Context或状态管理库(如Redux)
2. 使用cookie替代localStorage(需注意安全性)
3. 实现同构存储方案，在服务器端使用内存存储

最佳实践建议

1. 明确区分环境：始终考虑代码可能运行的执行环境
2. 延迟加载敏感代码：将依赖浏览器API的代码放在useEffect或类似生命周期钩子中
3. 抽象数据访问层：创建统一的数据访问接口，内部处理环境差异
4. 测试多环境：确保在开发和生产环境下的行为一致

总结

React Router框架模式下的这种行为是设计使然，而非缺陷。理解其背后的设计理念有助于开发者构建更健壮的应用。通过采用适当的环境判断和数据加载策略，可以确保应用在各种环境下都能正常工作，同时保持代码的清晰和可维护性。

对于从传统SPA迁移到框架模式的开发者，建议逐步重构数据访问逻辑，采用React Router推荐的客户端数据加载模式，这将为应用带来更好的长期可维护性。