MDX项目在Storybook中的配置问题解析与解决方案

在使用MDX与Storybook结合开发时，开发者可能会遇到一个常见的编译错误："Unexpected FunctionDeclaration in code: only import/exports are supported"。这个问题通常出现在升级到Storybook 8.x版本后，特别是在使用Create React App(CRA)作为基础框架的项目中。

问题背景

当开发者尝试在.stories.tsx文件中导入.mdx文件时，Webpack构建过程会抛出上述错误。这通常表明MDX加载器在处理文件内容时遇到了不符合预期的语法结构。错误信息明确指出，当前上下文中只支持import/export语句，而代码中却包含了函数声明等不被支持的结构。

根本原因分析

这个问题主要源于以下几个技术因素：

1. Storybook 8.x的架构变化：新版Storybook对MDX处理流程进行了优化，对内容结构有更严格的限制。

2. CRA的兼容性问题：由于CRA已经停止维护，其Webpack配置可能无法完全适配新版Storybook的MDX处理要求。

3. 文件命名约定：Storybook对不同类型的文件有不同的处理规则，.mdx和.stories.mdx文件会被不同的管道处理。

解决方案

经过实践验证，有以下几种可行的解决方案：

1. 使用正确的文件扩展名：

   • 将普通.mdx文件重命名为.stories.mdx
   • Storybook会为不同类型的文件应用不同的处理逻辑

2. 升级构建工具：

   • 考虑从CRA迁移到Vite等现代构建工具
   • 新版构建工具能更好地处理MDX与现代前端工具的集成

3. 检查MDX文件内容：

   • 确保文件中只包含合法的MDX语法
   • 避免在顶层作用域中包含函数声明等非MDX标准语法

最佳实践建议

1. 遵循Storybook官方文档推荐的MDX使用方式，避免自定义配置。

2. 对于文档型MDX内容，使用.stories.mdx扩展名。

3. 对于组件型MDX内容，确保其结构符合MDX规范。

4. 考虑项目长期维护性，尽早规划从CRA到现代构建工具的迁移。

技术深度解析

从技术实现层面看，这个错误源于MDX编译器的处理阶段限制。MDX编译器在解析文件时，会先进行语法分析，然后转换为JSX结构。在这个过程中，它期望文件顶层只包含导入/导出语句，而其他内容应该被包含在MDX组件或标记中。

新版Storybook加强了这个限制，以提高编译效率和确定性。这也是为什么简单的文件重命名就能解决问题的原因——Storybook会对.stories.mdx文件应用更宽松的处理规则。

总结

MDX与Storybook的集成虽然强大，但也需要注意版本兼容性和配置细节。通过理解工具链的工作原理和遵循最佳实践，开发者可以避免这类编译错误，充分发挥MDX在文档驱动开发中的优势。随着前端工具生态的快速发展，保持工具链的更新和维护是确保开发效率的关键因素。