修复 Storybook MDX 中 “does not provide an export named ‘ArgsTable‘” 的实战

修复 Storybook MDX 中 "does not provide an export named 'ArgsTable'" 的实战 🐛➜✅

TL;DR: 在 Storybook 的 blocks 打包入口里显式重导出 ArgsTable（export { ArgsTable } from './.../ArgsTable'），并追加单元测试与兼容性说明，快速恢复 MDX 文档在 Vite 下的运行时兼容性；补丁已提交为 PR：github.com/storybookjs...

---

背景

在一个使用 Vite 与 Storybook 的组件库中（MDX 文档广泛使用 ArgsTable），运行 Storybook 时出现了如下运行时错误：

The requested module '.../blocks.js' does not provide an export named 'ArgsTable'

这导致载入 MDX 的文档页面失败，Args 表格无法渲染。

问题定位（快速说明）

• 现象：MDX 导入 ArgsTable 报错，且只在开启 Vite 优化（optimizeDeps）或预打包后的环境中出现。
• 检查 .vite-cache 下预打包产物后，发现 blocks 模块导出里存在 PureArgsTable，但缺少命名导出 ArgsTable。
• 推断原因：构建/预打包步骤（或导出重命名）将内部实现以 PureArgsTable 暴露，导致依赖 ArgsTable 的代码在运行时找不到对应命名导出。

小结：Vite pre-bundling 可能改变导出符号，导致 MDX 代码期待的命名导出不存在。

解决方案（我做了什么）

思路是做一个小而不侵入的兼容性修复：在 blocks 的入口处显式导出 ArgsTable，并添加一条针对性单元测试。

关键变更如下：

 *** Update File: code/addons/docs/src/blocks.ts
@@
-export { ArgsTable as PureArgsTable } from './blocks/components/ArgsTable/ArgsTable';
+export { ArgsTable as PureArgsTable } from './blocks/components/ArgsTable/ArgsTable';
+// Compatibility re-export so external imports of `ArgsTable` keep working.
+export { ArgsTable } from './blocks/components/ArgsTable/ArgsTable';

并新增测试：

// code/addons/docs/src/__tests__/blocks.test.ts
import * as blocks from '../blocks';

describe('blocks module compatibility exports', () => {
  test('exports ArgsTable', () => {
    expect(blocks.ArgsTable).toBeDefined();
  });

  test('ArgsTable equals PureArgsTable', () => {
    expect(blocks.ArgsTable).toBe(blocks.PureArgsTable);
  });
});

这是一种最小改动（non-breaking）的补丁，便于快速 review 和回滚。

本地验证步骤（可复现）

• 运行针对性测试：

  npm run test:jest -- code/addons/docs/src/tests/blocks.test.ts

• 启动 Storybook 并检查 MDX 页面：

  npm run storybook

  打开 http://localhost:6006/ 并打开含 ArgsTable 的 MDX 页面

• 备用临时方案（不改 upstream）：

  • 在项目内添加一个 ArgsTableFallback shim，然后在 MDX 中使用显式的表格数据；
  • 在 .storybook/main.ts 中把 @storybook/addon-docs 加入 optimizeDeps.exclude，并删除 .vite-cache 以避开预打包改名问题。

PR 与 Issue

• Issue: github.com/storybookjs...
• PR: github.com/storybookjs...

我已在 PR 中包含补丁、测试与 Changelog 说明，等待 upstream maintainer 审核。

后记与建议 ✅

• 这类问题表明：当你的开发环境（如 Vite）会进行依赖预打包或导出变换时，库的公共导出契约（named exports）很重要。保持显式导出可以减少消费端因编译器/打包器变化导致的问题。
• 我建议：库方接纳这个最小兼容补丁以快速恢复用户体验；若维护者更倾向于调整 package exports 或 build pipeline，也可以用该方向做进一步改进。

原文： https://juejin.cn/post/76002960