Storybook 贡献开发全流程解析从本地构建、测试、问题复现到发布的 CONTRIBUTING 指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookCONTRIBUTING.old.md是 Storybook 仓库中保存的旧版贡献者指南完整记录了一位社区贡献者从跑起本地仓库到发布版本所需掌握的全部实操路径基于 yarn workspaces 的 monorepo 引导、单元测试与 Linter 配置、最小复现问题monorepo 内外两条路线、PR 提交与评审规范、Issue 分诊标签体系以及面向维护者的预发布/正式发版命令序列。读完本文你既能复现这份文档的每一步操作又能对照当前仓库的 根 package.json、scripts/package.json、本地注册表实现 等源码理解这些流程在今天的 Storybook 仓库中是如何演化落地的。一、文档定位一份面向贡献者的端到端操作手册这份文档开篇即声明 Storybook 是社区驱动项目欢迎从讨论、文档到 bugfix、功能改进的各类贡献。其目录结构本身就勾勒出贡献者的完整工作流Issues如何提 Issue、如何针对main分支验证问题、如何制作最小复现monorepo 内 / monorepo 外两条路径、测试更新规范Pull Requests (PRs)提交前检查、PR 提交者/评审者的职责Issue Triage回复、打标、关闭 Issue 的规则Development Guide环境前置条件、初始搭建yarn bootstrap、按包构建、kitchen sink 示例应用、在自己的项目中 link Storybook 包Release Guide预发布prerelease与正式发布full release的命令序列。文档同时给出了关键前提仓库使用yarn workspaces管理因此必须安装 yarn 作为包管理器。二、Issues提 Issue 与针对main分支验证2.1 提 Issue 前的标准动作文档要求贡献者在提 Issue 前先搜索现有 Issue 列表若发现相同问题用thumbs-up reaction投票以便维护者优先级排序否则新建 Issue需包含清晰的标题越短越好、清晰的描述、错误日志与截图为进一步加速修复提供一个能复现问题的 sample repo。2.2 针对main分支测试的完整步骤文档给出了clone → 构建 → 测试/lint的标准流程git clone https://github.com/storybookjs/storybook.git cd storybook yarn bootstrap文档特别提示在 Windows 上可能需要先运行一次yarn再执行yarn bootstrap。yarn bootstrap会交互式询问要引导bootstrap哪些代码区块保持默认即可也可以直接用 CLI 参数指定例如yarn bootstrap --core。单元测试2a 节yarn test会列出所有可运行的测试套与选项支持--watch监听模式、--coverage覆盖率、--runInBand串行运行等参数也可以用--update或jest -u更新快照。其中yarn test默认执行rootdir/app/react、rootdir/app/vue与rootdir/lib三处的测试运行前需先用yarn bootstrap --core完成 core 引导。Windows 用户还需注意将core.autocrlf设为falsegit config --global core.autocrlf false避免覆盖快照中的换行符文档还建议尽量在 WSL2 中运行测试规避 unix 风格路径问题。Linter2b 节仓库对所有代码含 TypeScript统一使用 ESLint运行yarn lint即可。文档还附上了 VsCode 的推荐配置启用保存时自动修复与缓存{ editor.codeActionsOnSave: { source.fixAll.eslint: true }, eslint.packageManager: yarn, eslint.options: { cache: true, cacheLocation: .cache/eslint, extensions: [.js, .jsx, .json, .html, .ts, .tsx, .mjs] }, eslint.alwaysShowStatus: true }对照当前仓库今天的仓库已迁移到 yarn 4见 根 package.json 中的packageManager: yarn4.18.0测试器从 jest 换成了 vitest——根目录test脚本为NODE_OPTIONS--max_old_space_size4096 vitest runvitest.config.ts 通过projects字段聚合了code/core、code/addons/*、code/frameworks/*、code/renderers/*、scripts等子项目的 vitest 配置lint 也从 ESLint 换成了 oxlintcode工作区的lint:js:cmd为oxlint --report-unused-disable-directives-severityerror见 code/package.json。旧文档的跑测试 跑 lint工作流思想完全延续只是具体工具链演进到了 vitest/oxlint。三、Reproductions两条最小复现路径3.1 在 monorepo 内复现文档推荐的最佳复现方式是直接在本仓库内嵌的官方示例应用上做改动。步骤为git clone https://github.com/storybookjs/storybook.git cd storybook yarn yarn bootstrap --core # 在示例应用中做改动以尝试复现问题如添加组件 stories cd examples/official-storybook yarn storybook # 若成功复现提交到一个描述性分支 git checkout branch-describing-issue git add -A git commit -m reproduction for issue #123 # 将 storybook 仓库 fork 到你自己的账号添加 remote 后推送 git remote add your-username https://github.com/your-username/storybook.git git push -u your-username next之后在 Issue 中链接到该 fork 仓库即可。文档还特别提醒若问题涉及 webpack 配置create-react-app 会阻止你修改应用自身的 webpack 配置但可以修改 storybook 侧的配置来镜像你应用的情况或者在 CRA 应用里yarn eject以获得可修改的 webpack 配置。对照当前仓库仓库中的示例目录已从examples/演进为test-storybooks/如test-storybooks/portable-stories-kitchen-sink/、test-storybooks/mcp/并通过code/sandbox/下的大量*.json沙盒配置react-vite、vue3-vite、nextjs、svelte-vite 等配合 scripts 中的沙盒生成脚本 统一管理。kitchen sink这一概念被完整保留并体系化。3.2 在 monorepo 外复现本地 npm 注册表当你的 Storybook 深度嵌入自有工程、难以做独立最小复现时文档介绍了仓库内置的本地注册表脚本它的工作原理是在你本机启动一个 npm 注册表把你的默认 registry 指向这个本地注册表构建 Storybook 仓库中的所有包将所有包以latest版本发布到本地注册表。只要保持注册表进程运行你就可以随时从它安装 Storybook 包修改 Storybook 代码后重新触发构建yarn dev或yarn bootstrap --core保证转译在注册表终端按Enter触发重新发布再回到你的项目重装依赖并重启 Storybook 即可。文档还解释了为何不直接用npm linklink 繁琐且与基于 registry 的安装存在细微差异可能掩盖真实问题。源码级印证这条路线在今天的仓库中对应 scripts/run-registry.ts由 scripts/package.json 的local-registry: jiti ./run-registry.ts脚本暴露也可从code工作区用yarn local-registry触发。阅读其实现可以看到它比文档描述更精巧使用Verdaccio作为本地注册表监听 6002 端口在 6001 端口再起一个代理服务器URL 中包含storybook、/sb或方法为PUT发布的请求 302 转发到本地 Verdaccio其余流量直接转发到公共 npm 注册表——源码注释解释这样做的动机是把所有流量都走 Verdaccio 代理会很慢用这个启发式规则可以两全其美Verdaccio 的具体包路由规则定义在 scripts/verdaccio.yaml所有storybook/*、storybook、sb、create-storybook、eslint-plugin-storybook等包不代理到上游注册表源码注释明确允许我们在测试期间重新发布任意版本而*/*与**则统一proxy: npmjs。这份 yaml 同时列出了数十个 legacy/外部storybook/*包如storybook/bench、storybook/addon-styling、storybook/testing-library与run-registry.ts一起构成了一条可验证的文档流程 → 仓库实现证据链。四、Updating Tests 与 PR 规范4.1 测试更新约定文档要求任何 PR 提交前必须新增或更新有意义的测试带失败测试的 PR 会被视为Work in Progress在所有测试通过之前不予合并。新建单元测试文件需遵循目录与命名约定# js 测试文件的正确命名与结构 -- parentFolder | -- [filename].js | -- [filename].test.js4.2 PR 提交者与评审者提交者提交前必须确保yarn test通过测试失败不要提交 PRPR 需关联对应 Issue、附简短贡献描述代码类改动需附上手动测试步骤文档提到这些要求由 PR 模板非正式地强制。若评审认为只差琐碎修改如小笔误且你有 commit 权限可以自己改完合并。分支策略文档特别注明——虽然最新稳定版对应main分支但几乎全部 Storybook 开发发生在next分支因此 PR 应从next拉出并指向next。评审者通读改动、指出潜在问题、按提交者给的手动测试步骤实际验证若步骤缺失、模糊或过于复杂可要求提交者补充除非 PR 带有do not merge标签批准评审且无其他待办后应直接合并。五、Issue Triage标签体系与关闭规则文档将 Issue 分诊归纳为三层操作回复 Issue带question / support或needs reproduction标签的 Issue 是最佳切入点——回答别人的问题既能帮提问者也方便后来者搜索命中需要复现的 Issue 可以引导报告者按上文复现技术制作复现或自己动手。打标签标签分为三类——维度取值示例说明typebug、feature、question / support、discussion、dependencies、maintenance每个 Issue 必须有且仅一个 type 标签dependencies用于依赖升级maintenance是清理/重构的兜底类areaaddon: x、addons-api、stories-api、ui等一个或多个用于按模块过滤statusneeds reproduction、needs PR、in progress等一个或多个用于控制开放 Issue 总量对bug类 Issue若没有你亲自确认过的清晰复现应打上needs reproduction并请作者制作复现或自己尝试。关闭规则重复 Issue 附原 Issue 链接后关闭无法复现且报告者失联约两周后关闭bug合入后打merged标签修复并发布后关闭question / support在问题被回答后关闭失联者同样等待两周discussion由维护者酌情关闭。这一整套 triage 机制在 CONTRIBUTING.md 的现行版本中依然延续了标签 状态的思路属于 Storybook 社区治理中长期稳定的部分。六、Development Guide本地开发环境搭建6.1 前置条件与初始搭建前置条件最新稳定版的 node 与 yarn文档注明遇到搭建问题时确认 node/npm/yarn 均为最新yarn 至少 v1.3.2。初始步骤git clone https://github.com/storybookjs/storybook.git建议用你自己的 forkcd storybookyarn bootstrap --coreWindows 上可能需要在第 2、3 步之间先跑一次yarn。bootstrap会静态构建整个项目。为了让 Storybook 代码的改动实时反映到examples下的示例应用中文档给出两种方式yarn dev监听全部包——文档坦承这极其慢yarn build package1 package2 --watch只监听指定的固定包列表例如yarn build add-docs components --watch对应storybook/addon-docs与storybook/components在较慢的机器上更实用。完整 bootstrap慢yarn bootstrap --all→ 休息片刻 →yarn test验证一切正常。按包构建文档给出了yarn build的完整 CLI 语义——裸跑yarn build交互式列出可构建的包供选择并支持 watch 模式选项yarn build package-name构建指定包包名用短名如storybook/addon-docs对应yarn build addon-docsyarn build --all构建全部追加--watch按名构建或全量构建时进入 watch 模式如yarn build core addon-docs --watch。对照当前仓库当前code工作区code/package.json的构建入口为yarn build委托到scripts/build-package.ts日常开发则统一走 nx 驱动的yarn task见 scripts/task.ts根 package.json 中的start脚本即yarn task --task dev --template react-vite/default-ts --start-frominstall。yarn bootstrap/yarn build时代已让位于task流水线但选包构建 watch 模式的交互语义是一致的。6.2 在 kitchen sink 应用中开发文档指出仓库examples目录下为 Storybook 支持的各种平台提供了厨房抽屉kitchen sink级实现示例它们不仅展示了大量选项与 add-on而且自动链接到所有开发中的包文档强烈建议贡献者在其中开发/测试自己的改动。以 React 和 Vue 为例cd examples/official-storybook yarn storybook # 验证本地版本工作正常当前仓库中这一角色由 test-storybooks/ 目录portable-stories-kitchen-sink、mcp、external-docs、yarn-pnp等与code/sandbox/下的 40 余个沙盒配置共同承担e2e 测试code/e2e-sandbox/、code/e2e-internal/则跑在这些沙盒之上。6.3 在自己的应用中 link Storybook文档以storybook/react为例说明分包安装的 link 流程Link 步骤注意必须进入子项目目录内执行yarn link不要在 storybook 根目录执行cd app/react yarn link把自己的项目接入前提是yarn dev正在运行在你的项目中getstorybook安装 Storybook 并yarn storybook验证本地版本可用回到 storybook 根目录等待yarn dev的输出停止改动会转译到 dist 并在此记录进入你的沙盒项目目录执行yarn link storybook/react再yarn storybook。文档提醒link 后若看不到 add-on多半是版本问题需把你用到的每个 add-on 也逐一 link这对 kitchen sink 应用和自有项目都适用。最后到http://localhost:9011或 Storybook 实际运行端口验证改动生效若看不到改动则重跑yarn storybook。6.4 文档开发文档说明Storybook 官方文档站点由独立的 frontpage 项目承载但文档源文件位于本仓库今天对应 docs/ 目录。查看开发中文档的改动需使用 frontpage 项目文档中描述的linking方式。七、Release Guide维护者发布流程这一节面向执行发布的 Storybook 维护者前提假设yarn 1.3.2且已从 storybookjs/pr-log 项目 link 了pr-log工具。文档声明这是面向未来 CI 自动化的手动序列并自注未完成不懂勿试。核心序列为生成并人工核对 changelog → 推送 changelog 到 main 或 release 分支 → clean、build、publish → 把 changelog 粘贴到 GitHub Release 页面并标记为预发布。文档还指出一个关键细节首次发布一个 scoped 包storybook/x时其 package.json 必须包含publishConfig: { access: public }7.1 Prerelease预发布序列# 确保与 origin/next 同步 git checkout next git status # 生成 changelog产生一个 Next 小节并按需编辑 yarn changelog:next x.y.z-alpha.a # 按需编辑 changelog/PR 列表后提交 git commit -m x.y.z-alpha.a changelog # 干净构建 yarn bootstrap --reset --core # 发布并打 tag yarn run publish:next # 更新 GitHub Release 页面7.2 Full release正式发布序列# 确保与 origin/main 同步 git checkout main git status # 生成 changelog产生一个 vNext 小节并按需编辑 yarn changelog x.y.z # 按需编辑后提交 git commit -m x.y.z changelog # 干净构建 yarn bootstrap --reset --core # 发布并打 tag yarn run publish:latest # 更新 GitHub Release 页面对照当前仓库changelog/changelog:next这两个脚本名在 code/package.json 中依然存在pr-log --sloppy --cherry-pick与pr-log --sloppy --since-prerelease而发布环节已脚本化为一组release:*命令见 scripts/package.jsonrelease:version、release:write-changelog、release:get-changelog-from-file、release:is-prerelease、release:is-pr-frozen、release:publish等核心发布逻辑在 scripts/release/publish.ts。从源码可以看到它强制要求-T, --tag参数注释解释留空会以 latest tag 发布故必须显式指定并通过yarn workspaces foreach --all --parallel --no-private ... npm publish --provenance --tolerate-republish --tag tag完成带 provenance 的并行发布还内置了 3 次重试与 15 分钟注册表轮询等待REGISTRY_POLL_TIMEOUT_MS。旧文档先 changelog、后 clean build、再 publish、最后更新 Release 页面的四段式流程正是这套自动化的雏形。另外可参照仓库内的发布记录文件了解真实版本节奏CHANGELOG.md正式版本、CHANGELOG.prerelease.md预发布以及现行 CONTRIBUTING.md 中面向自动化发布流程的配套说明。八、小结这份旧指南留下的可复用资产Monorepo 贡献方法论bootstrap --core引导 → 选包 watch 构建 → kitchen sink 应用验证 → 测试与 lint 全绿后提 PR这套本地全链路验证的思路至今不变本地注册表复现方案文档中起本地 registry 发布为 latest 代理分流的设计在 scripts/run-registry.ts 与 scripts/verdaccio.yaml 中得到源码级落实6001 代理端口/6002 Verdaccio 端口的分流启发式至今仍在使用社区治理三件套Issue 标签体系type/area/status、测试不过不合并的 PR 门槛、维护者 changelog-driven 的发布序列构成了 Storybook 作为大型开源 monorepo 的协作基础设施。对于今天想参与 Storybook 开发的读者建议将本文作为历史基线再结合现行 CONTRIBUTING.md 与 AGENTS.md 获取最新的命令与流程变更——旧指南中的每个环节都能在现行仓库的脚本与配置中找到对应实现。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考