2026/9/10 7:26:27
FEATURED · 精选文章 
Storybook 迁移指南使用migrate mdx-to-csf将.stories.mdx中的故事迁移到 CSF【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南以 Storybook 官方提供的migrate mdx-to-csf迁移命令为核心讲解如何将旧版.stories.mdx即 CSF in MDX文件中定义的故事自动转换为独立的 CSFComponent Story Format故事文件并完成.storybook/main.js配置更新、手动清理等后续收尾步骤。读完本文你将掌握在 npm、pnpm、yarn 三种包管理器下执行迁移的完整命令、migrate子命令的全部参数用法以及从源码层面理解该 codemod 的实际执行原理与失败兜底机制。为什么需要迁移.stories.mdx已被移除在 Storybook 7 之前.stories.mdx文件允许开发者在同一个文件中同时编写组件文档与定义故事这一模式被称为 CSF in MDX。然而这种混合格式把故事定义与文档撰写耦合在一起既不利于类型安全也增加了工具的解析负担。Storybook 7.0 开始正式弃用该能力并将文档文件后缀统一为.mdx到了 Storybook 8.0.stories.mdx格式与 MDX1 支持被彻底移除Storybook 不再加载任何.stories.mdx文件。仓库中的 MIGRATION.md 明确记载了这一变更In Storybook 7, we deprecated the ability to use MDX for both documentation and story definition in the same .stories.mdx file. It is now removed, and Storybook wont support.stories.mdxfiles anymore. We provide migration scripts to help you onto the new format.替代方案是清晰的职责分离用 CSF 文件.stories.js|ts定义故事用独立的.mdx文件撰写文档并通过Meta/StoryDoc Block 将两者关联。官方文档 MDX 编写指南 对这一分工做了说明CSF擅长简洁地定义故事组件示例配合 TypeScript 还能获得类型安全与自动补全MDX擅长编写结构化文档并可自由嵌入交互式 JSX 元素。核心命令一键将 MDX 中的故事转换为 CSF迁移的核心动作是运行 Storybook 自带的mdx-to-csfcodemod。官方在 storybook-migrate-mdx-to-csf.md 中给出了三种包管理器下的等价命令# npm npx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx# pnpm pnpm dlx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx# yarn yarn dlx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx命令解读部分含义storybooklatest始终拉取最新稳定版 Storybook CLI确保使用最新的迁移逻辑migrateStorybook CLI 的迁移子命令用于执行各类 codemodmdx-to-csf本次要执行的 codemod 名称将 MDX 内嵌故事转换为 CSF--glob src/**/*.stories.mdx指定要处理的文件匹配模式此处匹配src目录下所有.stories.mdx文件注意--glob的值建议加上引号包裹避免 shell 自行展开通配符确保 glob 模式原样传给 Storybook 处理。migrate子命令的完整参数说明mdx-to-csf是migrate子命令的一种 codemod因此你可以组合使用 CLI 参数文档 中定义的所有选项。其命令语法为storybook[version] migrate [codemod] [options]常用参数如下选项说明-h,--help输出用法信息-c,--config-dir [dir-name]指定 Storybook 配置目录如storybook migrate --config-dir .storybook-n,--dry-run预演模式只校验迁移是否存在并列出将受影响的文件不做任何实际修改例如storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx --dry-run-l,--list列出所有可用的 codemod如storybook migrate --list-g,--glob指定应用 codemod 的文件 glob 模式如storybook migrate --glob src/**/*.stories.mdx-p,--parser设置 jscodeshift 解析器可选babel、babylon、flow、ts、tsx-r,--rename [from-to]将受影响的文件按 旧后缀:新后缀 规则重命名如storybook migrate --rename .mdx:.mdx--debug输出更多日志以辅助调试最佳实践正式执行前先用--dry-run预览受影响文件清单确认 glob 匹配范围无误后再实际运行。仓库内其他迁移命令也遵循同一模式例如 CSF2 转 CSF3 的 storybook-migrate-csf-2-to-3.md 使用--glob**/*.stories.tsx --parsertsx以及 storybook-migrate-stories-of-to-csf.md可见--glob与--parser是所有 codemod 共用的基础参数。源码视角codemod 是如何工作的要理解迁移命令的行为边界可以查看仓库中 codemod 运行器的实现 code/lib/codemod/src/index.ts。核心流程如下校验 codemod 是否存在通过listCodemods()扫描storybook/codemod包dist/transforms目录下所有编译产物若传入的mdx-to-csf不在列表中直接抛出Unknown codemod错误。归一化 glob 并匹配文件使用tinyglobby对--glob模式做匹配路径统一使用正斜杠兼容 Windows并自动排除node_modules与dist目录若没有命中任何文件日志输出No matching files for glob: ...并直接返回。推断解析器根据 glob 的文件扩展名自动推断 jscodeshift 解析器.ts/.tsx等能识别的扩展名会直接透传无需手动指定--parser。调用 jscodeshift 执行转换以子进程方式运行jscodeshift传入--no-babel、--extensions、--fail-on-error以及转换脚本路径和文件列表避免用 Babel 二次转换自身源码造成性能损耗。失败兜底mdx-to-csf 专属源码中对mdx-to-csf做了特殊处理——当 jscodeshift 返回退出码1时不会中止任务而是将无法转换的文件重命名为.mdx.broken并提示开发者手工修复后再改回.mdxif (codemod mdx-to-csf result.status 1) { logger.log( The codemod was not able to transform the files mentioned above. We have renamed the files to .mdx.broken. Please check the files and rename them back to .mdx after you have either manually transformed them to mdx csf or fixed the issues so that the codemod can transform them. ); }这一设计意味着迁移并非总是全自动成功。遇到复杂的 JSX 结构或非标准写法时codemod 会优先保全你的源文件改名而非删除把决定权交还给你。迁移后的手工收尾关键步骤MIGRATION.md 特别强调仅运行命令是不够的还需完成以下三步才能平滑迁移更新 stories glob 配置在.storybook/main.js或main.ts的stories配置中加入新建的.mdx与.stories.js|ts文件匹配规则。默认 glob 已能匹配.mdx与.stories.*文件但如果你自定义过stories数组需要显式补全例如export default { stories: [ ../src/**/*.mdx, // 新增纯文档 MDX 文件 ../src/**/*.stories.(js|jsx|mjs|ts|tsx), // 新增/确认CSF 故事文件 ], };手动删除原.stories.mdx中的故事定义codemod 默认不会删除原文件中的故事内容只负责抽出故事生成新的 CSF 文件因此原文件需要你手工清理只保留文档部分并改名为普通.mdx。移除 MDX1 遗留配置若此前使用过 legacy MDX1 格式需要删除.storybook/main.js中的legacyMdx1feature flag并卸载storybook/mdx1-csf依赖同时jsxOptions配置也已随此变更移除。新格式速览CSF 定义故事MDX 撰写文档迁移完成后推荐的文档组织方式是CSF 文件 附属 MDX 文档页。在 MDX 文件中通过Meta块关联 CSF 文件用Story块渲染其中的故事import { Meta, Story } from storybook/blocks; import * as ComponentStories from ./some-component.stories; Meta of{ComponentStories} / Story of{ComponentStories.Primary} /依据 MIGRATION.md 的说明ofprop 仅在纯.mdx文件中受支持.stories.mdx中不可用——这也是必须完成迁移的原因之一每个组件可以拥有多个 MDX 文档页默认以.mdx文件名命名如Introduction.mdx生成Introduction文档入口若文档文件与组件同名如Button.mdx则会使用默认 autodocs 名称Docs并覆盖自动文档MDX 文档页默认排在组件故事列表最前可通过故事排序调整顺序。这样拆分后故事文件保持纯净的 CSF 结构便于单元测试复用与类型推导文档文件则聚焦叙述与 JSX 组合二者各司其职。小结mdx-to-csf迁移的本质是将旧版文档与故事混杂的.stories.mdx拆解为CSF 定义故事 MDX 撰写文档的现代双文件结构。执行迁移时记住三个要点用npx/pnpm dlx/yarn dlx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx触发转换先用--dry-run预演迁移后检查.storybook/main.js的storiesglob、手工清理原文件残留的故事、移除legacyMdx1相关配置若个别文件被重命名为.mdx.broken说明 codemod 无法处理需手工改写后恢复扩展名。完成这些步骤后你的项目即可彻底摆脱对.stories.mdx的依赖平滑运行在 Storybook 8 的现代文档体系之上。【免费下载链接】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 迁移指南：使用 `migrate mdx-to-csf` 将 `.stories.mdx` 中的故事迁移到 CSF
Storybook 迁移指南使用migrate mdx-to-csf将.stories.mdx中的故事迁移到 CSF【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南以 Storybook 官方提供的migrate mdx-to-csf迁移命令为核心讲解如何将旧版.stories.mdx即 CSF in MDX文件中定义的故事自动转换为独立的 CSFComponent Story Format故事文件并完成.storybook/main.js配置更新、手动清理等后续收尾步骤。读完本文你将掌握在 npm、pnpm、yarn 三种包管理器下执行迁移的完整命令、migrate子命令的全部参数用法以及从源码层面理解该 codemod 的实际执行原理与失败兜底机制。为什么需要迁移.stories.mdx已被移除在 Storybook 7 之前.stories.mdx文件允许开发者在同一个文件中同时编写组件文档与定义故事这一模式被称为 CSF in MDX。然而这种混合格式把故事定义与文档撰写耦合在一起既不利于类型安全也增加了工具的解析负担。Storybook 7.0 开始正式弃用该能力并将文档文件后缀统一为.mdx到了 Storybook 8.0.stories.mdx格式与 MDX1 支持被彻底移除Storybook 不再加载任何.stories.mdx文件。仓库中的 MIGRATION.md 明确记载了这一变更In Storybook 7, we deprecated the ability to use MDX for both documentation and story definition in the same .stories.mdx file. It is now removed, and Storybook wont support.stories.mdxfiles anymore. We provide migration scripts to help you onto the new format.替代方案是清晰的职责分离用 CSF 文件.stories.js|ts定义故事用独立的.mdx文件撰写文档并通过Meta/StoryDoc Block 将两者关联。官方文档 MDX 编写指南 对这一分工做了说明CSF擅长简洁地定义故事组件示例配合 TypeScript 还能获得类型安全与自动补全MDX擅长编写结构化文档并可自由嵌入交互式 JSX 元素。核心命令一键将 MDX 中的故事转换为 CSF迁移的核心动作是运行 Storybook 自带的mdx-to-csfcodemod。官方在 storybook-migrate-mdx-to-csf.md 中给出了三种包管理器下的等价命令# npm npx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx# pnpm pnpm dlx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx# yarn yarn dlx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx命令解读部分含义storybooklatest始终拉取最新稳定版 Storybook CLI确保使用最新的迁移逻辑migrateStorybook CLI 的迁移子命令用于执行各类 codemodmdx-to-csf本次要执行的 codemod 名称将 MDX 内嵌故事转换为 CSF--glob src/**/*.stories.mdx指定要处理的文件匹配模式此处匹配src目录下所有.stories.mdx文件注意--glob的值建议加上引号包裹避免 shell 自行展开通配符确保 glob 模式原样传给 Storybook 处理。migrate子命令的完整参数说明mdx-to-csf是migrate子命令的一种 codemod因此你可以组合使用 CLI 参数文档 中定义的所有选项。其命令语法为storybook[version] migrate [codemod] [options]常用参数如下选项说明-h,--help输出用法信息-c,--config-dir [dir-name]指定 Storybook 配置目录如storybook migrate --config-dir .storybook-n,--dry-run预演模式只校验迁移是否存在并列出将受影响的文件不做任何实际修改例如storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx --dry-run-l,--list列出所有可用的 codemod如storybook migrate --list-g,--glob指定应用 codemod 的文件 glob 模式如storybook migrate --glob src/**/*.stories.mdx-p,--parser设置 jscodeshift 解析器可选babel、babylon、flow、ts、tsx-r,--rename [from-to]将受影响的文件按 旧后缀:新后缀 规则重命名如storybook migrate --rename .mdx:.mdx--debug输出更多日志以辅助调试最佳实践正式执行前先用--dry-run预览受影响文件清单确认 glob 匹配范围无误后再实际运行。仓库内其他迁移命令也遵循同一模式例如 CSF2 转 CSF3 的 storybook-migrate-csf-2-to-3.md 使用--glob**/*.stories.tsx --parsertsx以及 storybook-migrate-stories-of-to-csf.md可见--glob与--parser是所有 codemod 共用的基础参数。源码视角codemod 是如何工作的要理解迁移命令的行为边界可以查看仓库中 codemod 运行器的实现 code/lib/codemod/src/index.ts。核心流程如下校验 codemod 是否存在通过listCodemods()扫描storybook/codemod包dist/transforms目录下所有编译产物若传入的mdx-to-csf不在列表中直接抛出Unknown codemod错误。归一化 glob 并匹配文件使用tinyglobby对--glob模式做匹配路径统一使用正斜杠兼容 Windows并自动排除node_modules与dist目录若没有命中任何文件日志输出No matching files for glob: ...并直接返回。推断解析器根据 glob 的文件扩展名自动推断 jscodeshift 解析器.ts/.tsx等能识别的扩展名会直接透传无需手动指定--parser。调用 jscodeshift 执行转换以子进程方式运行jscodeshift传入--no-babel、--extensions、--fail-on-error以及转换脚本路径和文件列表避免用 Babel 二次转换自身源码造成性能损耗。失败兜底mdx-to-csf 专属源码中对mdx-to-csf做了特殊处理——当 jscodeshift 返回退出码1时不会中止任务而是将无法转换的文件重命名为.mdx.broken并提示开发者手工修复后再改回.mdxif (codemod mdx-to-csf result.status 1) { logger.log( The codemod was not able to transform the files mentioned above. We have renamed the files to .mdx.broken. Please check the files and rename them back to .mdx after you have either manually transformed them to mdx csf or fixed the issues so that the codemod can transform them. ); }这一设计意味着迁移并非总是全自动成功。遇到复杂的 JSX 结构或非标准写法时codemod 会优先保全你的源文件改名而非删除把决定权交还给你。迁移后的手工收尾关键步骤MIGRATION.md 特别强调仅运行命令是不够的还需完成以下三步才能平滑迁移更新 stories glob 配置在.storybook/main.js或main.ts的stories配置中加入新建的.mdx与.stories.js|ts文件匹配规则。默认 glob 已能匹配.mdx与.stories.*文件但如果你自定义过stories数组需要显式补全例如export default { stories: [ ../src/**/*.mdx, // 新增纯文档 MDX 文件 ../src/**/*.stories.(js|jsx|mjs|ts|tsx), // 新增/确认CSF 故事文件 ], };手动删除原.stories.mdx中的故事定义codemod 默认不会删除原文件中的故事内容只负责抽出故事生成新的 CSF 文件因此原文件需要你手工清理只保留文档部分并改名为普通.mdx。移除 MDX1 遗留配置若此前使用过 legacy MDX1 格式需要删除.storybook/main.js中的legacyMdx1feature flag并卸载storybook/mdx1-csf依赖同时jsxOptions配置也已随此变更移除。新格式速览CSF 定义故事MDX 撰写文档迁移完成后推荐的文档组织方式是CSF 文件 附属 MDX 文档页。在 MDX 文件中通过Meta块关联 CSF 文件用Story块渲染其中的故事import { Meta, Story } from storybook/blocks; import * as ComponentStories from ./some-component.stories; Meta of{ComponentStories} / Story of{ComponentStories.Primary} /依据 MIGRATION.md 的说明ofprop 仅在纯.mdx文件中受支持.stories.mdx中不可用——这也是必须完成迁移的原因之一每个组件可以拥有多个 MDX 文档页默认以.mdx文件名命名如Introduction.mdx生成Introduction文档入口若文档文件与组件同名如Button.mdx则会使用默认 autodocs 名称Docs并覆盖自动文档MDX 文档页默认排在组件故事列表最前可通过故事排序调整顺序。这样拆分后故事文件保持纯净的 CSF 结构便于单元测试复用与类型推导文档文件则聚焦叙述与 JSX 组合二者各司其职。小结mdx-to-csf迁移的本质是将旧版文档与故事混杂的.stories.mdx拆解为CSF 定义故事 MDX 撰写文档的现代双文件结构。执行迁移时记住三个要点用npx/pnpm dlx/yarn dlx storybooklatest migrate mdx-to-csf --glob src/**/*.stories.mdx触发转换先用--dry-run预演迁移后检查.storybook/main.js的storiesglob、手工清理原文件残留的故事、移除legacyMdx1相关配置若个别文件被重命名为.mdx.broken说明 codemod 无法处理需手工改写后恢复扩展名。完成这些步骤后你的项目即可彻底摆脱对.stories.mdx的依赖平滑运行在 Storybook 8 的现代文档体系之上。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
