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

问题背景

在使用 React Router 7.1.5 版本时，开发者遇到了一个常见但令人困惑的问题：即使在明确设置了客户端渲染模式（ssr: false）的情况下，代码中直接使用 window 对象仍然会抛出"window is not defined"的错误。

问题本质

这个问题的根源在于 React Router 的构建机制。即使我们配置了客户端渲染模式，构建过程中仍然需要生成服务器端 bundle 来渲染基础 HTML 文件。这是因为：

1. 静态站点生成(SSG)需要服务器端渲染基础框架
2. 首屏内容需要被预先渲染到 HTML 文件中
3. 路由配置需要在构建时被解析

解决方案

React Router 官方推荐使用 .client 模块来解决这个问题。这种特殊命名的模块有以下特点：

1. 仅在客户端 bundle 中被包含
2. 不会参与服务器端渲染过程
3. 可以安全使用浏览器特有的 API

最佳实践

对于需要在客户端使用的浏览器特有 API，建议采用以下模式：

1. 将相关代码分离到 .client.js 或 .client.ts 文件中
2. 在这些文件中可以自由使用 window、document 等对象
3. 通过常规的 import 语句在其他组件中引用这些模块

深入理解

这种设计实际上是现代前端框架中常见的模式，它体现了：

1. 同构渲染的复杂性处理
2. 构建时优化的考虑
3. 代码分割的最佳实践

开发者需要理解，即使配置了客户端渲染，现代前端框架仍然会在构建时进行一定程度的服务器端处理，这是为了优化性能和用户体验。

总结

React Router 的这种设计虽然初看起来有些反直觉，但实际上是为了提供更好的开发体验和运行时性能。通过使用 .client 模块，开发者可以清晰地划分代码的执行环境，避免常见的环境相关错误，同时还能享受到框架提供的各种优化。