Storybook addon-docs FAQ 深入解析框架支持边界、Addons 交互机制与 MDX 调试实战【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文围绕 Storybook 官方addon-docs包内置的 FAQ 文档展开系统回答三个高频实战问题Docs 到底支持哪些框架、Docs 页面与其他 addons 面板为何互斥、以及 MDX 故事渲染不符合预期时如何调试。文章在完整继承 FAQ 原始内容的基础上结合code/addons/docs目录下的 preset、编译器与构建插件源码讲清这些行为背后的编译管线与配置机制帮助你在搭建组件文档站点时快速定位问题、规避已知限制。Docs 支持哪些框架FAQ 给出的结论非常明确Docs 目前不支持 React Native除此之外Storybook 支持的所有框架 Docs 均支持包括 React、Vue 3、Angular、Ember、Svelte 等视图层。也就是说Docs 的框架能力边界基本与 Storybook 核心保持一致唯一的例外就是 React Native。这一结论与 README 中的 Framework support 章节相互印证所有主要视图层都可用同时部分框架还享有框架专属能力例如 props 表格props tables和内联故事渲染inline story rendering。各框架的具体接入方式与功能差异可以进一步查阅 addon-docs 自带的框架文档通用接入说明ReactVue 3AngularEmberWeb Components如果你的框架不在上述列表内多框架开发指南 描述了如何为新框架补齐 Docs 增强能力如 docgen、内联渲染的实现路径。Docs 与既有 Addons 的交互为什么面板会消失FAQ 对 Docs 如何与已有 addons 交互 的回答是当 Docs 页面可见时addons 面板右栏会被隐藏。背后的原因在于假设冲突几乎所有 addon 面板Controls、Actions、Viewport 等都假设当前屏幕上只有一个故事而 Docs 页面在同一个视图中可能渲染多个故事DocsPage 会把该组件下所有故事聚合在一页。面板不知道该把参数和控件绑定到哪一个故事上因此 addon-docs 直接选择隐藏整个面板而不是呈现一个行为未定义的状态。FAQ 同时指出团队曾提出 knobs v2 方案来单独解决 knobs 在多故事场景下的参数绑定问题但在更通用的层面即任意 addon 与 Docs 的共存尚无定案该问题在当时的 issue 讨论中一直处于开放状态。从源码结构看Docs 可见时隐藏面板的行为由 preview 侧的 Docs 渲染组件承担Docs 渲染入口 接管了整个预览区的文档视图。理解这一点后实操建议就很直接了——当你需要交互式的 Controls/Actions 时切换到 Canvas故事视图进行操作当你在 Docs 页面中需要控制某个故事的参数时优先使用 Docs 内嵌的Controlsdoc block 或args这两者是为 Docs 视图设计的参数入口。调试 MDX 故事从编译产物入手这是 FAQ 中最具实战价值的一节。典型症状是故事在 Docs 中能渲染但渲染结果与预期不符——样式错乱、props 没传进去、事件监听失效等。调试核心思路检查 MDX 编译出的 JavaScriptMDX 文件在构建阶段会被编译成 JavaScript。FAQ 给出的调试路径是打开浏览器开发者工具查看 dev serverwebpack 场景下即 webpack dev server实际下发的源码在webpack分包目录里定位到你的故事文件可能需要在类似webpack . path/to/your/stories的层级下找一找但编译后的代码一定在那里检查编译产物中故事对应的组件定义是否符合预期。为什么这招有效MDX 与 CSF 的一一映射FAQ 的关键论断是MDX 中的Story块本质上是Component Story Format (CSF)的语法糖因此存在一条从 MDX 到 CSF 的一对一映射。以 FAQ 中的示例为例Story namesolo story Button onClick{action(clicked)}solo/Button /Story其等价的 CSF 写法是export const soloStory () ( Button onClick{action(clicked)}solo/Button );这意味着一个非常有效的排错手段把 MDX 编译出的代码或等价的手写 CSF复制到一个新的.stories.js文件里脱离 Docs 环境在 Canvas 中单独运行从而在更低的层级定位问题出在故事本身还是 Docs 的聚合/装饰逻辑上。MDX 与 CSF 的完整映射规则可参考 MDX 参考文档。从源码看 MDX 编译管线FAQ 提到 MDX 被编译成 JavaScript具体由哪段代码完成从code/addons/docs/src的源码可以确认整条管线preset.ts 是 addon-docs 的预设入口。webpack 构建下它向构建配置注入一条test: /\.mdx$/的 module rule使用storybook/addon-docs/mdx-loader处理 MDX 文件并把react、react-dom、mdx-js/react统一 alias 到同一份 React 依赖避免双份 React/emotion 实例导致 Docs 组件渲染失败Vite 构建下则由 mdx-plugin.ts 以enforce: pre的 transform 钩子完成同等工作。两条路径最终都调用 compiler/index.ts 中的compile/compileSync底层直接调用mdx-js/mdx的编译器默认providerImportSource指向storybook/addon-docs/mdx-react-shim对mdx-js/react的运行时垫片。preset 还会强制追加两个 rehype 插件rehype-slug为标题生成锚点Docs 目录导航依赖它和rehype-external-links外部链接加新窗口属性。这条管线解释了 FAQ 调试法的合理性你在开发者工具中看到的正是mdx-js/mdx的编译产物而 preset 又提供了mdxLoaderOptions这一预设扩展点presets.apply(mdxLoaderOptions, ...)允许其他 preset 或用户配置介入编译选项——当怀疑编译行为异常时这也是一个可切入的检查点。preset 配置选项csfPluginOptions 与 mdxPluginOptions调试中如果发现是 CSF 源码增强 或 MDX 编译 环节的默认行为不符合项目需要addon-docs 的 preset 提供了两个官方配置项完整示例见 README 的 Preset options 章节export default { addons: [ { name: storybook/addon-docs, options: { // 设为 null 则禁用 CSF 源码增强source enrichment csfPluginOptions: null, // 透传给 MDX 编译器的 CompileOptions mdxPluginOptions: {}, }, }, ], };csfPluginOptions控制 addon-docs 用于 docgen/源码提取的 CSF 增强插件。从 preset.ts 可见webpack 路径下非null时会注入csfPluginWebpack插件Vite 路径下对应csfPluginVite设为null时完全不注入该插件即 addon-docs 不再对你的 CSF 文件做增强处理。如果你的项目自带 docgen 或自定义 loader可借此避免双重处理。mdxPluginOptions的类型是CompileOptions定义于 compiler/types.ts其中的mdxCompileOptions会展开进mdx-js/mdx的编译配置可用于调整 MDX 编译行为。注意 preset 的默认值会在你的配置之后追加providerImportSource与两个 rehype 插件理解其合并顺序有助于定制插件链。更多资源FAQ 最后给出的资料索引结合当前仓库的实际文件整理如下已转换为仓库内路径参考文档README / DocsPage / MDX / FAQ / Recipes / Theming / Props 表格框架文档多框架开发指南以及 code/addons/docs/docs/frameworks 目录下的 COMMON / REACT / VUE3 / ANGULAR / EMBER / WEB_COMPONENTS 各框架说明源码与测试preset 入口、MDX 编译器封装、MDX Vite 插件、DocsPage 默认聚合实现、Docs 单元测试、e2e 文档渲染用例小结addon-docs 的 FAQ 虽然篇幅不长但三条问答分别对应三个关键决策点选型时确认框架支持边界除 React Native 外全量覆盖、交互设计时理解 Docs 与 addons 面板的互斥机制、以及排错时掌握 查看 MDX 编译产物 转写为 CSF 独立验证 的调试闭环。配合 preset 的csfPluginOptions/mdxPluginOptions配置项和mdxLoaderOptions扩展点这套机制足以覆盖绝大多数 Docs 搭建与维护场景。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Storybook addon-docs FAQ 深入解析：框架支持边界、Addons 交互机制与 MDX 调试实战
Storybook addon-docs FAQ 深入解析框架支持边界、Addons 交互机制与 MDX 调试实战【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文围绕 Storybook 官方addon-docs包内置的 FAQ 文档展开系统回答三个高频实战问题Docs 到底支持哪些框架、Docs 页面与其他 addons 面板为何互斥、以及 MDX 故事渲染不符合预期时如何调试。文章在完整继承 FAQ 原始内容的基础上结合code/addons/docs目录下的 preset、编译器与构建插件源码讲清这些行为背后的编译管线与配置机制帮助你在搭建组件文档站点时快速定位问题、规避已知限制。Docs 支持哪些框架FAQ 给出的结论非常明确Docs 目前不支持 React Native除此之外Storybook 支持的所有框架 Docs 均支持包括 React、Vue 3、Angular、Ember、Svelte 等视图层。也就是说Docs 的框架能力边界基本与 Storybook 核心保持一致唯一的例外就是 React Native。这一结论与 README 中的 Framework support 章节相互印证所有主要视图层都可用同时部分框架还享有框架专属能力例如 props 表格props tables和内联故事渲染inline story rendering。各框架的具体接入方式与功能差异可以进一步查阅 addon-docs 自带的框架文档通用接入说明ReactVue 3AngularEmberWeb Components如果你的框架不在上述列表内多框架开发指南 描述了如何为新框架补齐 Docs 增强能力如 docgen、内联渲染的实现路径。Docs 与既有 Addons 的交互为什么面板会消失FAQ 对 Docs 如何与已有 addons 交互 的回答是当 Docs 页面可见时addons 面板右栏会被隐藏。背后的原因在于假设冲突几乎所有 addon 面板Controls、Actions、Viewport 等都假设当前屏幕上只有一个故事而 Docs 页面在同一个视图中可能渲染多个故事DocsPage 会把该组件下所有故事聚合在一页。面板不知道该把参数和控件绑定到哪一个故事上因此 addon-docs 直接选择隐藏整个面板而不是呈现一个行为未定义的状态。FAQ 同时指出团队曾提出 knobs v2 方案来单独解决 knobs 在多故事场景下的参数绑定问题但在更通用的层面即任意 addon 与 Docs 的共存尚无定案该问题在当时的 issue 讨论中一直处于开放状态。从源码结构看Docs 可见时隐藏面板的行为由 preview 侧的 Docs 渲染组件承担Docs 渲染入口 接管了整个预览区的文档视图。理解这一点后实操建议就很直接了——当你需要交互式的 Controls/Actions 时切换到 Canvas故事视图进行操作当你在 Docs 页面中需要控制某个故事的参数时优先使用 Docs 内嵌的Controlsdoc block 或args这两者是为 Docs 视图设计的参数入口。调试 MDX 故事从编译产物入手这是 FAQ 中最具实战价值的一节。典型症状是故事在 Docs 中能渲染但渲染结果与预期不符——样式错乱、props 没传进去、事件监听失效等。调试核心思路检查 MDX 编译出的 JavaScriptMDX 文件在构建阶段会被编译成 JavaScript。FAQ 给出的调试路径是打开浏览器开发者工具查看 dev serverwebpack 场景下即 webpack dev server实际下发的源码在webpack分包目录里定位到你的故事文件可能需要在类似webpack . path/to/your/stories的层级下找一找但编译后的代码一定在那里检查编译产物中故事对应的组件定义是否符合预期。为什么这招有效MDX 与 CSF 的一一映射FAQ 的关键论断是MDX 中的Story块本质上是Component Story Format (CSF)的语法糖因此存在一条从 MDX 到 CSF 的一对一映射。以 FAQ 中的示例为例Story namesolo story Button onClick{action(clicked)}solo/Button /Story其等价的 CSF 写法是export const soloStory () ( Button onClick{action(clicked)}solo/Button );这意味着一个非常有效的排错手段把 MDX 编译出的代码或等价的手写 CSF复制到一个新的.stories.js文件里脱离 Docs 环境在 Canvas 中单独运行从而在更低的层级定位问题出在故事本身还是 Docs 的聚合/装饰逻辑上。MDX 与 CSF 的完整映射规则可参考 MDX 参考文档。从源码看 MDX 编译管线FAQ 提到 MDX 被编译成 JavaScript具体由哪段代码完成从code/addons/docs/src的源码可以确认整条管线preset.ts 是 addon-docs 的预设入口。webpack 构建下它向构建配置注入一条test: /\.mdx$/的 module rule使用storybook/addon-docs/mdx-loader处理 MDX 文件并把react、react-dom、mdx-js/react统一 alias 到同一份 React 依赖避免双份 React/emotion 实例导致 Docs 组件渲染失败Vite 构建下则由 mdx-plugin.ts 以enforce: pre的 transform 钩子完成同等工作。两条路径最终都调用 compiler/index.ts 中的compile/compileSync底层直接调用mdx-js/mdx的编译器默认providerImportSource指向storybook/addon-docs/mdx-react-shim对mdx-js/react的运行时垫片。preset 还会强制追加两个 rehype 插件rehype-slug为标题生成锚点Docs 目录导航依赖它和rehype-external-links外部链接加新窗口属性。这条管线解释了 FAQ 调试法的合理性你在开发者工具中看到的正是mdx-js/mdx的编译产物而 preset 又提供了mdxLoaderOptions这一预设扩展点presets.apply(mdxLoaderOptions, ...)允许其他 preset 或用户配置介入编译选项——当怀疑编译行为异常时这也是一个可切入的检查点。preset 配置选项csfPluginOptions 与 mdxPluginOptions调试中如果发现是 CSF 源码增强 或 MDX 编译 环节的默认行为不符合项目需要addon-docs 的 preset 提供了两个官方配置项完整示例见 README 的 Preset options 章节export default { addons: [ { name: storybook/addon-docs, options: { // 设为 null 则禁用 CSF 源码增强source enrichment csfPluginOptions: null, // 透传给 MDX 编译器的 CompileOptions mdxPluginOptions: {}, }, }, ], };csfPluginOptions控制 addon-docs 用于 docgen/源码提取的 CSF 增强插件。从 preset.ts 可见webpack 路径下非null时会注入csfPluginWebpack插件Vite 路径下对应csfPluginVite设为null时完全不注入该插件即 addon-docs 不再对你的 CSF 文件做增强处理。如果你的项目自带 docgen 或自定义 loader可借此避免双重处理。mdxPluginOptions的类型是CompileOptions定义于 compiler/types.ts其中的mdxCompileOptions会展开进mdx-js/mdx的编译配置可用于调整 MDX 编译行为。注意 preset 的默认值会在你的配置之后追加providerImportSource与两个 rehype 插件理解其合并顺序有助于定制插件链。更多资源FAQ 最后给出的资料索引结合当前仓库的实际文件整理如下已转换为仓库内路径参考文档README / DocsPage / MDX / FAQ / Recipes / Theming / Props 表格框架文档多框架开发指南以及 code/addons/docs/docs/frameworks 目录下的 COMMON / REACT / VUE3 / ANGULAR / EMBER / WEB_COMPONENTS 各框架说明源码与测试preset 入口、MDX 编译器封装、MDX Vite 插件、DocsPage 默认聚合实现、Docs 单元测试、e2e 文档渲染用例小结addon-docs 的 FAQ 虽然篇幅不长但三条问答分别对应三个关键决策点选型时确认框架支持边界除 React Native 外全量覆盖、交互设计时理解 Docs 与 addons 面板的互斥机制、以及排错时掌握 查看 MDX 编译产物 转写为 CSF 独立验证 的调试闭环。配合 preset 的csfPluginOptions/mdxPluginOptions配置项和mdxLoaderOptions扩展点这套机制足以覆盖绝大多数 Docs 搭建与维护场景。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考