Storybook中处理Next.js服务端组件与server-only模块的最佳实践

在开发Next.js应用时，我们经常会遇到需要在Storybook中测试包含服务端组件或server-only模块的组件的情况。本文将深入探讨如何优雅地解决这类问题。

问题背景

当我们在Next.js应用中使用server-only标记的模块时，这些模块本应只在服务端运行。然而，Storybook默认运行在客户端环境，这会导致组件在Storybook中加载失败。典型错误包括"defineLive can only be used in React Server Components"等。

解决方案

1. 启用实验性RSC支持

Storybook 8.5+版本提供了对Next.js服务端组件的实验性支持。通过在.storybook/main.ts配置文件中添加以下配置开启：

features: {
  experimentalRSC: true
}

这一配置允许Storybook正确处理服务端组件和客户端组件的边界。

2. 模块别名与模拟

对于无法直接使用的服务端模块，我们可以通过Webpack别名机制进行模拟替换：

webpackFinal: async (config) => {
  config.resolve.alias = {
    ...config.resolve.alias,
    "server-only": require.resolve("./.storybook/mocks/server-only.js"),
    "@/app/actions": path.resolve(__dirname, "../src/app/actions.mock.ts")
  };
  return config;
}

3. 创建模拟文件

对于不同的服务端模块，我们需要创建对应的模拟实现：

server-only模拟 (./.storybook/mocks/server-only.js):

module.exports = {}

actions模拟 (src/app/actions.mock.ts):

export const search = async () => {
  return [
    { title: "Mock Title 1", slug: { current: "mock-slug-1" } },
    { title: "Mock Title 2", slug: { current: "mock-slug-2" } }
  ];
};

高级技巧

环境变量处理

服务端组件常依赖环境变量，Storybook中可通过以下方式注入：

env: (config) => ({
  ...config,
  API_READ_TOKEN: 'mock-token'
})

组件边界处理

对于混合使用服务端和客户端逻辑的组件，建议：

1. 将服务端逻辑提取到单独文件
2. 在客户端组件中通过props接收数据
3. 在Storybook中直接模拟props数据

常见问题排查

1. 模块未正确模拟：检查Webpack别名配置路径是否正确
2. RSC标志未生效：确保Storybook版本≥8.5且配置正确
3. 环境变量缺失：在Storybook配置中显式声明所需变量
4. 组件层级问题：确保服务端组件不会被客户端组件直接导入

最佳实践建议

1. 保持模拟实现的简洁性，避免复杂逻辑
2. 为每个服务端模块创建专门的模拟文件
3. 在团队文档中记录模拟策略
4. 考虑使用TypeScript确保模拟实现与真实API的类型兼容

通过以上方法，开发者可以在Storybook中无缝测试依赖服务端功能的Next.js组件，同时保持开发体验的一致性和高效性。