React Router 中客户端渲染模式下 window 对象的使用问题解析

问题背景

在使用 React Router 7.1.5 版本进行客户端渲染(CSR)开发时，开发者可能会遇到一个常见问题：当尝试在组件模块顶层直接访问 window 对象时，系统会抛出 window is not defined 的错误。这种情况即使在配置了相关选项为 false 的情况下仍然会发生。

问题本质

这个问题的根源在于 React Router 的构建机制。即使我们明确设置了服务器端渲染(SSR)为 false，React Router 仍然需要构建一个服务器端 bundle 来生成基础的 HTML 文件，以便能够进行静态服务。在这个过程中，所有模块都会被服务器端环境加载和解析，而服务器端环境中自然不存在浏览器特有的 window 对象。

解决方案

React Router 官方推荐使用 .client 模块来解决这个问题。.client 模块是一种特殊命名的文件，它只会被客户端 bundle 包含，而不会被服务器端 bundle 加载。这种方式可以确保浏览器特有的 API 只在客户端环境中被访问。

具体实现方式是将需要使用浏览器 API 的代码移动到以 .client.js 或 .client.ts 结尾的文件中。例如：

// myComponent.client.js
export function useWindowSize() {
  // 安全地使用 window 对象
  const [size, setSize] = useState({
    width: window.innerWidth,
    height: window.innerHeight
  });
  
  useEffect(() => {
    const handleResize = () => {
      setSize({
        width: window.innerWidth,
        height: window.innerHeight
      });
    };
    
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);
  
  return size;
}

最佳实践

1. 模块分离：将使用浏览器 API 的逻辑单独封装到 .client 模块中
2. 延迟加载：对于必须在顶层使用 window 的第三方库，考虑使用动态导入
3. 环境判断：在必须直接访问浏览器 API 的地方，可以先判断 typeof window !== 'undefined'
4. 错误边界：为可能抛出错误的组件添加错误边界处理

深入理解

理解这一机制的关键在于认识到现代前端框架的构建过程。即使我们进行的是客户端渲染，构建工具仍然需要在服务器环境下执行模块解析和代码拆分。这种设计带来了更好的开发体验和构建优化，但也引入了运行环境差异的问题。

React Router 的 .client 模块方案实际上是一种编译时条件加载机制，它通过文件命名约定告诉构建工具哪些模块应该只在客户端 bundle 中包含。这种方式比运行时环境判断更加高效，因为它完全避免了将服务器端不需要的代码发送到客户端。

总结

在 React Router 项目中处理浏览器特有 API 时，开发者需要特别注意模块的加载环境。通过合理使用 .client 模块和遵循官方推荐的最佳实践，可以避免 window is not defined 这类错误，同时保持代码的清晰性和可维护性。理解框架背后的构建原理有助于我们写出更加健壮的前端应用。