Storybook 如何启用变更检测并用 Review 过滤器快速定位新增与修改的 Stories【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook在多人协作或大型前端项目中一次提交往往只改动少数几个组件但你很难在 Storybook 侧边栏里一眼看出哪些 Story 受这次改动影响。Storybook 的变更检测Change detection功能会在开发期间监视 git 工作树和构建器的模块依赖图把新增与修改的 Story 标记在侧边栏上并提供一个 Review 按钮点一下就能把故事树过滤为只包含这些条目。本文介绍如何确认变更检测处于启用状态、读懂状态图标并使用 Review 过滤器与筛选菜单快速定位新增与修改的 Stories。需要注意变更检测目前处于 preview 生命周期阶段见 docs/releases/features.mdx未来版本中的体验可能会调整。前提条件git 仓库与受支持的构建器变更检测是一个仅开发环境的功能运行storybook dev时激活静态构建产物storybook build中不可用。以下两个条件必须同时满足变更检测才能工作git 仓库Storybook 通过git diff检测变更文件受支持的构建器Storybook 沿构建器的模块导入图追踪变更文件目前支持 Vite 和 webpack5 两种构建器。其他构建器可以通过实现 change-detection adapter 获得支持。启用与配置变更检测变更检测默认启用通常无需任何配置。如果它没有按预期工作检查.storybook/main.js或main.ts中的features.changeDetection是否被设置为false。该配置项的类型为boolean默认值为true。以下是文档中给出的完整配置示例用于演示如何关闭该功能your-framework需按文档说明替换为你实际使用的框架包如react-vite、nextjs、vue3-vite// 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)], features: { changeDetection: false, }, }; export default config;只要删除features段或将值改为true变更检测就会按默认状态启用。读懂侧边栏的三种状态图标检测到变更时Storybook 会在侧边栏相应 Story 旁显示状态图标图标状态含义✦ Sparklenew该 Story 文件在 git 中未被跟踪或为新增文件● Filled circlemodifiedStory 自身的文件或它直接导入的文件被修改无图标relatedStory 依赖链上游更远的文件被修改传递依赖同一 Story 命中多个状态时按优先级new modified related显示。变更检测状态与测试状态并列显示在侧边栏中用 Review 按钮一键过滤新增与修改的 Stories只要存在至少一个新增或修改的 Story侧边栏的搜索栏与故事树之间就会出现Review按钮。点击它会一次性切换new和modified两个过滤器故事树随即只保留这两类条目——这就是“快速定位本次改动影响范围”的主路径启动storybook dev修改或新增组件代码回到浏览器侧边栏确认目标 Story 旁出现 ✦ 或 ● 图标点击Review按钮故事树过滤为仅显示新增与修改的 Story再次点击可取消过滤恢复完整故事树。文档对此有一个明确的设计说明为什么变更检测过滤器默认是关闭的因为判定 modified 和 related 的启发式算法以快速、零配置为目标并不完美可能产生误报false positives。例如修改一个被广泛引用的工具函数时几十个 Story 可能被标为 related即使改动并未真正影响它们。为避免在大仓库中状态图标泛滥Storybook 默认让这些过滤器保持关闭状态图标只在你要审查变更时才呈现。用筛选菜单单独控制每个状态如果只需要看新增的 Story例如确认新文件都被正确收录可以打开搜索栏旁边的筛选菜单逐项勾选或取消勾选各个状态图标不出现时按这几项排查如果侧边栏从未出现状态指示器依次确认以下内容dev server 终端日志中带有Change detection:前缀的消息——启动错误、构建器不受支持的警告、解析失败都会输出到这里你确实在对受支持的构建器Vite 或 webpack5运行storybook dev项目位于一个 git 仓库内配置中features.changeDetection没有被设为false。可选分支monorepo 与 barrel 文件导致的追踪偏差以下两个问题只在特定工程结构下出现不属于默认路径按需查看。工作区兄弟包未被追踪monorepo当 Story 导入一个工作区兄弟包如package.json中声明为workspace:*的myorg/ui时该依赖可能不被追踪改动它不会触发 Story 重载。文档指出两个根因构建产物在开发时缺失exports/main指向尚未构建的dist输出以及各包自己的tsconfig.json屏蔽了根目录的 paths 映射。解决办法是在根tsconfig.json中加入指向工作区包源码目录的paths条目以下路径为文档示例需替换为你自己工作区包的实际命名与目录{ compilerOptions: { paths: { myorg/*: [./packages/myorg/*/src] } } }Storybook 在按文件解析失败时会把这些映射作为回退。一次改动后大量无关 Story 被标为 related修改一个组件如Breadcrumb后所有从共享包如myorg/ui导入的 Story 都被标为related通常说明该包使用了 barrel 文件一个 re-export 一切的index.ts。Storybook 会做 barrel 感知的命名导入解析把import { Button } from myorg/ui追踪到真正的源文件Button.tsx。受支持的模式包括直接命名 re-exportexport { Button } from ./Button与通配 re-exportexport * from ./Button两步 re-exportimport { Button } from ./Button; export { Button }和命名空间 re-exportexport * as components from ./components不受完全支持此时会退化为追踪 barrel 文件本身。如果必须追求最精确的追踪也可以直接从组件源路径导入取决于你的库是否发布了 deep-import 路径// Instead of the barrel import: import { Button } from myorg/ui; // Import directly from the components source: import { Button } from myorg/ui/Button;可选分支导出依赖图快照调试需要诊断“某个 Story 为什么被或没被标为 modified”时可以设置环境变量STORYBOOK_CHANGE_DETECTION_DEBUG让 Storybook 在启动时导出依赖图的 JSON 快照副作用会在项目中生成一个 JSON 文件STORYBOOK_CHANGE_DETECTION_DEBUG1— 在项目根目录写入storybook-graph-debug.jsonSTORYBOOK_CHANGE_DETECTION_DEBUG/path/to/output.json— 写入指定路径路径需替换为你自己的输出位置。快照包含启动时追踪的全部 Story 到依赖的边、反向索引哪些 Story 依赖哪个文件含 BFS 深度、以及 barrel 解析追踪哪些命名导入被解析到哪些源文件。限制与下一步变更检测的判定基于启发式文档明确说明它可能产生误报因此在共享依赖很多的仓库中不要把 related 状态当作严格的“受影响”结论。它只在storybook dev下生效storybook build产物中没有这一能力。对 React 项目还有一个建立在changeDetection之上的实验功能experimental agentic reviewfeatures.experimentalReview默认false用于审查 AI agent 在 Storybook 中所做的改动启用时变更检测必须保持开启。完整特性说明见 Change detection 与 features 配置参考。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考