Storybook项目中composeStories在Next.js服务端渲染的问题解析

问题背景

在Storybook项目的实际应用中，开发者经常会使用composeStories函数来组合和重用故事组件。然而，当这些组件在Next.js框架中进行服务端渲染(SSR)时，会出现无法预期的错误。

问题现象

开发者在使用composeStories函数时，虽然客户端渲染的组件能够正常显示，但在服务端渲染过程中会抛出"TypeError: Cannot read properties of null (reading '0')"的错误。这个错误出现在webpack运行时环境中，表明在服务端渲染过程中某些依赖项无法正确加载。

根本原因

经过技术分析，发现问题的根源在于composeStories函数内部依赖了react-dom/test-utils模块。这个模块在服务端渲染环境中不可用，因为它主要设计用于客户端测试场景。具体来说，Storybook的act-compat.ts文件中直接引用了这个测试工具模块，导致在SSR环境下执行失败。

解决方案

目前推荐的临时解决方案是使用Next.js的动态导入功能，并显式禁用服务端渲染选项：

const Variants = dynamic(() => import("@storybook/react")
  .then(({ composeStories }) => composeStories(stories).Variants), {
  ssr: false, // 禁用服务端渲染
});

这种方法通过动态导入组件并设置ssr:false选项，确保组件只在客户端渲染，从而避免了服务端渲染时的依赖问题。

技术深入

1. 服务端渲染限制：在Node.js环境中，许多浏览器特有的API和模块不可用，react-dom/test-utils就是其中之一。

2. 动态导入优势：Next.js的动态导入功能允许代码分割和按需加载，特别适合处理这种环境依赖差异的情况。

3. 兼容性考虑：Storybook团队正在考虑长期解决方案，可能包括：

   • 提供SSR友好的替代实现
   • 重构act-compat模块以减少环境依赖
   • 提供明确的错误提示和文档指导

最佳实践建议

1. 对于需要在服务端渲染的Storybook组件，考虑提取核心逻辑到独立组件，避免直接使用composeStories。

2. 在Next.js项目中，合理规划哪些组件需要SSR，哪些可以仅客户端渲染。

3. 关注Storybook的更新日志，未来版本可能会原生支持SSR场景。

总结

这个问题展示了前端开发中环境差异带来的挑战，特别是在同构应用(SSR+CSR)开发中。通过理解底层原理和合理使用框架特性，开发者可以找到有效的解决方案。虽然目前需要采用临时方案，但这个问题也促使社区思考如何更好地支持各种渲染场景。