Storybook refs 配置详解通过 main.js 组合多个 Storybook构建统一 UI 组件工作台Storybook 的refs是主配置文件.storybook/main.js|ts中的一项配置用于实现Storybook 组合Composition在一个 Storybook 里通过 URL 引用并浏览另一个独立 Storybook 的全部组件、故事与文档无论对方使用什么技术栈、框架或部署位置。读完本文你将掌握refs的完整类型签名与字段含义、三种声明方式对象、函数、禁用并能结合仓库源码理解组合在底层的解析与校验逻辑。一、refs是什么主配置字段与组合能力Storybook 主配置文件定义了项目行为refs就是其中与 Storybook 组合对应的配置字段在 main-config-refs API 参考中给出如下类型{ [key: string]: | { title: string; url: string; expanded?: boolean, sourceUrl?: string } | (config: { title: string; url: string; expanded?: boolean, sourceUrl: string }) { title: string; url: string; expanded?: boolean, sourceUrl?: string } | { disable: boolean } }可以看到每个key即 ref 的唯一标识名对应三种可选形态之一形态说明静态对象固定声明一个外部 Storybook包含title、url以及可选的expanded、sourceUrl函数运行时接收 Storybook 配置对象含configType按环境动态返回 ref 集合{ disable: boolean }针对某个已通过依赖包自动组合进来的 ref 显式关闭配置完成后外部 Storybook 的故事会出现在当前 Storybook 的侧边栏中与本地故事并列展示。这也是一些典型团队工作流的来源UI 开发者可以免切换地参考团队历史组件设计系统可以将自身组合进下游使用方前端平台团队也能在一个界面中横向审计组件在多个项目中的使用情况。需要注意组合进来的 Storybook 中插件addons并不会像在原生 Storybook 中那样正常工作。这属于组合机制的固有限制详见 Storybook 组合说明。二、基础用法在 main 配置里声明一个外部 Storybook在.storybook/main.js|ts中添加refs字段即可组合一个已发布或本地运行中的 Storybook。下面这段示例来自 main-config-refs.mdcommon/CSF3 语法的 JS 版本export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], refs: { design-system: { title: Storybook Design System, url: https://master--5ccbc373887ca40020446347.chromatic.com/, expanded: false, // Optional, true by default sourceUrl: https://github.com/storybookjs/storybook, // Optional }, }, };使用 TypeScript 的 CSF3 写法时将配置声明为StorybookConfig类型即可获得字段的静态校验// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { StorybookConfig } from storybook/your-framework; const config: StorybookConfig { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], refs: { design-system: { title: Storybook Design System, url: https://master--5ccbc373887ca40020446347.chromatic.com/, expanded: false, // Optional, true by default, sourceUrl: https://github.com/storybookjs/storybook, // Optional }, }, }; export default config;各字段的含义与取值约束url必填被组合 Storybook 的可访问地址。官方支持两类一类是静态构建后发布到公网的 Storybook例如由 Chromatic 或 CI 部署产出的地址另一类是本地正在运行的其他 Storybook例如不同端口下的 React/Angular 实例可在 组合指南 中查看本地组合的写法。title必填显示在侧边栏中的标题。实际上如果省略源码中还会有一个基于 key 自动推断标题的兜底逻辑见下文实现分析但类型签名仍将其声明为必填。expanded可选默认true控制该 ref 下各分组在侧边栏中的展开状态置为false时默认折叠展示。sourceUrl可选指向外部组件源码仓库的地址便于在 UI 中一键跳转到故事来源。三、CSF Next 语法用 defineMain 声明 refs如果项目启用了实验性的 CSF Next 配置写法主配置改为从对应框架的node子路径导入defineMainrefs的结构完全一致。例如 main-config-refs.md 中 React 的 TS 变体// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; export default defineMain({ framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], refs: { design-system: { title: Storybook Design System, url: https://master--5ccbc373887ca40020446347.chromatic.com/, expanded: false, // Optional, true by default, sourceUrl: https://github.com/storybookjs/storybook, // Optional }, }, });defineMain在各框架下仅需替换导入路径与framework名称refs内部写法保持一致。参考当前仓库中各框架的入口vue3-vite 从storybook/vue3-vite/node导入angular 从storybook/angular/node导入web-components 从storybook/web-components-vite/node导入JavaScript 版本的导入规则相同。四、按环境动态组合把 refs 声明为函数不同开发阶段可能需要引用不同的外部 Storybook例如开发期组合本地运行中的各框架实例生产期组合线上已发布版本。此时可以把refs改为函数。原文档 main-config-refs-with-function.md 给出了完整示例export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], // Retrieve the current environment from the configType argument refs: (config, { configType }) { if (configType DEVELOPMENT) { return { react: { title: Composed React Storybook running in development mode, url: http://localhost:7007, }, angular: { title: Composed Angular Storybook running in development mode, url: http://localhost:7008, }, }; } return { react: { title: Composed React Storybook running in production, url: https://your-production-react-storybook-url, }, angular: { title: Composed Angular Storybook running in production, url: https://your-production-angular-storybook-url, }, }; }, };两点说明函数接收的第二个参数中解构出configType官方示例用它区分DEVELOPMENT与其他生产环境从而返回不同的 ref 集合与主配置文件中的其他字段一致refs作为函数时其首个参数是包含 Storybook 完整配置对象的config便于你基于项目配置动态推导 url。TS 类型版本CSF3 及 CSF Next均支持可参考 main-config-refs-with-function.md 中完整的StorybookConfig/defineMain写法。五、关闭自动组合{ disable: true }某些包依赖会自动把自己的 Storybook 组合进当前项目即包级组合package-composition。如果你不希望某个包被自动组合进来可以在refs中针对该包名显式关闭export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], refs: { package-name: { disable: true }, }, };完整 TypeScript 版本见 main-config-refs-disable.md。六、源码级解析refs 是如何被读取、补全与校验的仓库的 get-storybook-refs.ts 集中实现了 refs 的解析逻辑从源码可以把上文各配置项的幕后行为看得更清楚自动组合来自依赖包清单getAutoRefs向上查找最近的package.json遍历dependencies与devDependencies读取每个依赖自己的 manifest只要其暴露了manifest.storybook.url字段就会生成一个 ref 条目。这正是某些包会自动组合的机制来源。合并用户配置并按 key 归一化getRefs先通过options.presets.apply(refs, await getAutoRefs(options))把用户在main.js里声明的 refs 与自动发现的 refs 合并随后遍历每个条目遇到value.disable就直接从结果中删除该 ref关闭自动组合的实现入口其余条目会被统一key 转为小写并作为id同时执行title: value.title || toTitle(value.id || key)的标题兜底以及stripTrailingSlash(value.url)去掉 url 末尾的/。可达性校验解析完成后源码会对每个url发起checkRef请求请求${url}/iframe.html并校验是否返回需要认证的loginUrl为每个 ref 标注type: server-checked | unknown。也就是说Storybook 启动时就会探测被组合实例是否公开可达对不可达的 ref后续会改在运行时按需加载 stories 数据否则组合不可用。理解了这段源码你就能明白为什么expanded默认是true、为什么 url 末尾多余的斜杠无碍、为什么显式关闭某个包名即可阻止自动组合也就能更准确地排查组合不生效这一类问题。七、组合工作流与故障排查要点把以上内容落到实际工作流中可以归纳为几条可操作的经验发布 Storybook 时确保生成最新的index.json。组合机制依赖目标实例输出的 stories 数据。对于无法升级到最新版 Storybook、或者有特殊项目约束的场景可依靠官方组合文档的 Troubleshooting 一节在部署时用对应版本 Storybook CLI 生成index.json后再组合由于extract命令在 Storybook 8.0 及以上已不可用历史版本做法需参考 组合指南 中给出的旧版文档。开发多框架项目时可直接组合本地实例React 与 Angular 各起一个 Storybook如 7007/7008 端口在main.js中引用后侧边栏会自动合并两者的故事任一方改动另一方界面也能随之同步刷新便于跨框架协同开发。区分配置合并成功与实例可达两个层面前者依赖main.js中 refs 声明的正确性key 唯一、url 可用后者依赖目标地址可公开访问并输出了正确的iframe.html与 stories 元数据。启动时对server-checked类型的探活即是对后者的快速验证。延伸阅读main-config-refs API 参考本主题对应的完整 API 页面Storybook Composition 指南组合能力总览、本地组合、按环境组合与故障排查package-composition包依赖自动组合与disable关闭机制main 配置总览refs与framework、stories、addons等字段的上下文关系创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考