VitePress 项目中解决 "window is not defined" 错误指南

问题背景

在使用 VitePress 构建项目时，开发者可能会遇到 "ReferenceError: window is not defined" 的错误。这个错误通常发生在服务端渲染(SSR)环境中，因为 Node.js 环境下不存在浏览器特有的 window 对象。

错误原因分析

这个错误的核心在于代码中直接使用了浏览器环境特有的全局变量 window，而 VitePress 在构建过程中会先在 Node.js 环境下执行服务端渲染。当代码尝试访问不存在的 window 对象时，就会抛出这个错误。

解决方案

1. 检查客户端专用代码

首先需要检查项目中所有直接使用 window 的地方。常见场景包括：

• 直接调用 window.xxx 方法
• 使用 window 判断浏览器环境
• 浏览器特有的 API 调用

2. 使用环境判断

对于必须在浏览器中执行的代码，应该添加环境判断：

if (typeof window !== 'undefined') {
  // 浏览器环境专用代码
}

3. 动态导入

对于较大的浏览器专用模块，可以使用动态导入：

if (typeof window !== 'undefined') {
  const module = await import('./browser-module.js')
  // 使用模块
}

4. 调试技巧

当错误信息不够明确时，可以：

1. 设置环境变量 DEBUG=true 后重新运行构建命令
2. 检查 .temp/app.js 文件中报错的行号
3. 根据行号定位到原始代码位置

最佳实践建议

1. 隔离浏览器代码：将浏览器专用代码单独放在特定目录或文件中
2. 使用兼容性写法：避免直接使用 window，改用 globalThis 或环境判断
3. 代码审查：在代码提交前检查是否有直接使用浏览器 API 的情况
4. 测试验证：同时运行开发服务器和构建命令，确保两种环境下都能正常工作

总结

VitePress 作为基于 Vite 的静态站点生成器，同时支持客户端渲染和服务端渲染。开发者需要特别注意代码的 SSR 兼容性，避免直接使用浏览器特有的全局对象。通过环境判断和代码隔离，可以优雅地解决这类问题，确保项目在各种环境下都能正常运行。

对于复杂的项目，建议建立代码规范，明确区分通用代码和浏览器专用代码，从源头上避免这类问题的发生。