Storybook 核心包 storybook 解析：从 CLI、Manager 到 Preview API 的完整组件版图

本文以 Storybook 仓库中的 code/core/README.md 为核心素材，系统梳理 storybook 核心包（当前版本 10.6.0-beta.1）的组成结构与职责边界：它包含哪些 CLI、UI、运行时与工具库，如何通过 exports 字段划分公开 API 与内部 API，以及每个模块在 源码目录 中的落点。读完本文，你将能够准确回答“某个功能（控件、交互调试、测试工具、主题）到底在 Storybook 的哪个包里”，并知道如何沿着仓库源码继续深入。

一、核心包总览：README 定义的五大组成

Storybook 仓库是一个大型 monorepo，而 code/core 目录下的 storybook 包是整个体系的枢纽。README 给出的定位非常明确，该包包含以下五类内容：

1. Storybook 的 CLI 与开发服务器（CLI and development server）；
2. Storybook 的主界面（即 "the manager"，左侧导航树与顶栏所在的界面层）；
3. 核心功能：组件控件（controls）、工具栏（toolbar）、行为日志（actions）、视口控制（viewport）、交互调试器（interaction debugger）；
4. 面向用户的工具库：storybook/test、theming、viewport 等；
5. 被框架、插件、构建器生态复用的基础库。

此外，README 还特别指出包内有一个 storybook/internal 命名空间，存放 CSF、MDX、Docs 等基础设施工具。下面结合 code/core/src 的实际目录结构，逐条印证这些组成在源码中的位置。

二、源码目录结构与 README 组成的对应关系

code/core/src 下的顶层目录几乎与 README 描述一一对应：

README 中的组成	源码落点（相对仓库根目录）
CLI 与开发服务器	src/cli（detect.ts、helpers.ts、globalSettings.ts、AddonVitestService.ts 等）、src/core-server
主界面（manager）	src/manager、src/manager-api
组件控件	src/controls
工具栏 / 行为日志 / 视口	src/toolbar、src/actions、src/viewport
交互调试器（instrumentation）	src/instrumenter
storybook/test 工具库	src/test
theming 主题库	src/theming
CSF / Docs / MDX 基础设施	src/csf、src/csf-tools、src/docs-tools、src/babel、src/oxc-parser
通信与路由基础	src/channels、src/router
类型定义	src/types

除了上表，还可以看到几个值得注意的实现细节：

• manager-api 正在向 store 化与“开放服务”演进。从 manager-api/index.ts 可以看到，除了导出根组件 root.tsx，包还以 experimental_ 前缀暴露了 UniversalStore、useUniversalStore、状态/测试提供方 store，以及一套 open-service（manager relay hub）的 API（getService、registerService、useServiceCommand、useServiceQuery）。从源码结构看，manager 侧正在把全局状态从 React Context 抽象为可复用的 store 层。
• storybook/test 的 expect 是被插桩过的。test/index.ts 中，expect 来自本地 expect.ts 的实现，并被 storybook/internal/instrumenter 的 instrument 包装（过滤 chai Assertion 的内部键、拦截断言方法），这正是交互测试（play function / test-runner）能记录断言成败并展示在 UI 中的底层机制；同时该文件还以 sb.mock 占位形式暴露模块 mock 入口，并再导出 testing-library。
• 预览侧的运行时位于 src/preview 与 src/preview-api。

三、Preview API：四个历史包的合并体

preview-api/README.md 明确记录了该子包的历史：它曾由多个独立包合并而成——

• @storybook/addons（旧文档见同目录 README-addons.md）
• @storybook/core-client（README-core-client.md）
• @storybook/preview-web（README-preview-web.md）
• @storybook/store（README-store.md）

也就是说，用户在 story 文件中用到的 preview.ts 入口 API（addDecorator、addParameters 等）背后的实现，如今统一收敛在 code/core 这一处，目录内还保留了 addons.ts、store.ts、preview-web.ts 等模块文件，与历史上的包名呼应。理解这一点后，排查“装饰器 / 参数 / loader 不生效”这类问题，只需在 code/core/src/preview-api 与 code/core/src/preview 两个目录内查找即可。

四、exports 导出体系：公开 API 与内部 API 的分界

package.json 是整个包的“对外契约”。它有四个关键事实：

1. 包名与入口。包名即 storybook（package.json#L2-L3），bin 字段指向 ./dist/bin/dispatcher.js（package.json#L268）。storybook dev / storybook build 等命令最终都由这个 dispatcher 分发，对应源码侧的 src/cli 目录。

2. 公开子路径 API（不带 internal 前缀），用户可以直接 import：

子路径	用途	源码入口
./actions	action() 行为日志、装饰器（./actions/decorator）	src/actions
./backgrounds	背景色/网格参数处理	src/backgrounds
./highlight	元素高亮	src/highlight
./theming / ./theming/create	主题系统与主题创建	src/theming
./test	expect、spy、userEvent 等测试工具	src/test
./viewport	视口参数处理	src/viewport
./preview-api	预览侧公开 API（装饰器、参数、全局等）	src/preview-api
./manager-api	Manager 侧公开 API（store、hooks、组件注册）	src/manager-api
./open-service	服务注册/调用的开放服务层	src/shared/open-service

3. ./internal/* 内部子路径（仅供 Storybook 生态内部消费，不应被下游项目依赖）。从 package.json 的 exports 段 可以看到完整的内部 API 清单，按用途归类：

• 服务与工具链：./internal/cli、./internal/core-server（含 common-override-preset）、./internal/tools（CLI 工具 SDK）与 ./internal/tools/child-host、./internal/bin/dispatcher 与 ./internal/bin/loader；
• CSF/Docs 基础设施：./internal/csf、./internal/csf/csf-utils、./internal/csf-tools、./internal/docs-tools、./internal/babel、./internal/oxc-parser、./internal/docgen-worker（docgen 的 worker 入口）；
• 运行时与状态：./internal/preview-api、./internal/preview/runtime、./internal/manager/manager-stores、./internal/manager/globals(-runtime)、./internal/channels、./internal/router；
• 其他：./internal/telemetry、./internal/mocking-utils（模块 mock 运行时）、./internal/component-meta、./internal/components、./internal/types、各类错误定义（manager-errors、preview-errors、server-errors）以及 ./internal/skills（CLI 技能内容）。

4. 条件导出（conditional exports）。每个条目都给出 types / code / default 三种条件：default 指向编译产物 dist/，code 指向 TS 源码（供 monorepo 内消费），types 指向 .d.ts。配合 "type": "module" 与 "sideEffects": false，该包是纯 ESM 且可被 tree-shaking 的——这对“在项目中按需引入 theming、test 等子路径”尤为重要。

五、模板与测试资产：core 自带的“自举”验证场

code/core 除了实现代码，还带有一整套用于自举验证的模板与测试：

• template/ 目录是 Storybook 开发模式下生成预览页的模板素材，其中 template/stories 收录了大量“故事书里的故事”：argTypes.stories.ts、args.stories.ts、decorators.stories.ts、loaders.stories.ts、parameters-actions.stories.ts、component-play.stories.ts、expect.stories.tsx 等，按主题分目录的还有 controls、backgrounds、toolbars、viewport 与 test 的模块 mock 用例。它们是回归核心功能（args 映射、装饰器顺序、play 函数、mock 等）的活样例；
• 测试配置位于 code/core/vitest.config.ts 与 code/core/vitest.d.ts，各模块源码旁普遍存在 *.test.ts（如 cli/AddonVitestService.test.ts、cli/detectLanguage.test.ts）；
• 构建元数据 code/core/project.json 表明该包由仓库统一的 nx 体系编排。

六、core 与仓库其余部分的协作关系

storybook 核心包的价值在于“被依赖”：README 提到的“框架、插件、构建器生态复用的库”在此具体化为仓库内的兄弟包——

• 构建器：code/builders/builder-vite 与 code/builders/builder-webpack5 消费 core 的 internal/core-server、csf-tools 等能力来编译 stories；
• 框架适配：code/frameworks/ 下的 react-vite、vue3-vite、svelte-vite、nextjs 等基于 core 提供的 preview/manager 运行时接入各自框架；
• 插件：code/addons/ 下的 docs、a11y、vitest、themes 等通过 manager-api / preview-api 注册面板与装饰器。

这种分层解释了为什么用户项目里只需安装框架包（如 @storybook/react-vite）：其余能力都通过 core 的公开子路径间接提供。

七、如何继续阅读源码

• 想理解 CLI 行为（框架探测、语言探测、目录约定）：从 src/cli/index.ts 的再导出入手，重点是 detect.ts 与 helpers.ts；
• 想理解 story 执行与参数注入：阅读 src/preview-api 下的 store.ts 与 addons.ts，并参考其目录下四份旧包 README（README-addons.md 等）了解演进脉络；
• 想理解 manager 面板/工具注册：阅读 src/manager-api 的 root.tsx、store.ts 与 stores/；
• 想验证某个核心特性是否有测试保障：在对应源码目录找同名 *.test.ts，模板级行为则查 code/core/template/stories。

小结

code/core 的 storybook 包是 Storybook 的“操作系统内核”：README 所列的 CLI/服务器、manager UI、controls/actions/viewport 等核心交互、test/theming/viewport 用户库，全部落位于 code/core/src；package.json 的 exports 则用“公开子路径 + ./internal/* 前缀”清晰划定了生态边界；而 template 与遍布的测试文件构成了对这套核心能力的自举式回归验证。掌握这张版图，再深入 Storybook 任何一个上层框架或插件时，都能快速定位其依赖的核心机制。