Semi-Design 在 Next.js 中 document is not defined 问题深度解析

问题背景

Semi-Design 作为字节跳动开源的 React UI 组件库，在 Next.js 应用中出现了 document is not defined 的错误。这个问题主要出现在 Next.js 的 App Router 模式下，当使用 Node.js 21.6.1 及以上版本时尤为明显。

问题表现

开发者在 Next.js 14.2.5 版本的应用中引入 Semi-Design 2.62.0 及以上版本时，控制台会抛出 ReferenceError: document is not defined 的错误。这个问题在 Node.js 20.10.0 及以下版本不会出现，但在 Node.js 21.6.1 及以上版本会稳定复现。

根本原因分析

这个问题的本质在于 Next.js 的服务端渲染(SSR)机制与浏览器 API 的兼容性问题：

1. SSR 环境差异：Next.js 在服务端渲染时没有 document 对象，这是浏览器环境特有的 API
2. Node.js 版本影响：不同 Node.js 版本对模块解析和代码执行的处理方式有差异，导致在较新版本中更容易暴露这个问题
3. 组件库兼容性：Semi-Design 的部分组件可能直接或间接依赖了浏览器环境特有的 API

解决方案

临时解决方案

1. 降级 Node.js 版本：使用 Node.js 20.x 版本可以暂时规避此问题
2. 锁定 Semi-Design 版本：使用 2.61.0 版本可以避免此问题

长期解决方案

1. 动态导入组件：使用 Next.js 的动态导入功能，设置 ssr: false 选项

   import dynamic from 'next/dynamic';
   const SemiForm = dynamic(() => import('@douyinfe/semi-ui').then(mod => mod.Form), { ssr: false });
   

2. 条件渲染：在组件中通过 useEffect 或 typeof window 检查确保只在客户端渲染

   if (typeof window === 'undefined') {
     return null;
   }
   

3. 等待官方修复：关注 Semi-Design 官方更新，等待对最新 Node.js 版本的完全兼容

技术深度解析

这个问题实际上反映了现代前端开发中一个常见的挑战：如何正确处理同构应用中的环境差异。Next.js 作为服务端渲染框架，会在构建时和服务端执行时运行组件代码，而浏览器 API 在这些环境中是不可用的。

Semi-Design 作为企业级组件库，通常会对性能有较高要求，可能会使用一些直接操作 DOM 的优化手段。在 Node.js 21+ 版本中，模块系统和代码执行上下文的变化使得这些优化在 SSR 环境下更容易暴露问题。

最佳实践建议

1. 环境隔离：将依赖浏览器 API 的代码明确隔离到客户端专用模块中
2. 渐进增强：采用渐进式加载策略，先渲染基础内容，再加载交互增强
3. 版本控制：保持 Node.js 和依赖库版本的稳定性，避免过早使用最新版本
4. 错误边界：使用 React 错误边界捕获并优雅处理这类环境差异导致的错误

总结

Semi-Design 在 Next.js 中的 document is not defined 问题是一个典型的环境兼容性问题。开发者可以通过版本控制、动态加载和环境判断等多种方式解决。理解这个问题的本质有助于开发者更好地处理同构应用中的环境差异问题，提升应用的稳定性和兼容性。