VSCode安装Storybook扩展 组件驱动VSCode隔离开发模式

Storybook for VS Code 扩展仅提供跳转、右键菜单和嵌入预览页功能，不启动服务；“隔离开发”依赖 Storybook 自身沙箱与 HMR，需手动运行 npm run storybook 并确保 .storybook/main.js 配置正确。

装了Storybook for VS Code扩展，并不意味着组件就能直接在VSCode里实现“隔离开发”——它更像是一个跳板，真正的隔离能力，来自Storybook自身的运行时沙箱和VSCode的文件监听协同工作。

Storybook for VS Code 扩展到底干了什么

这个扩展既不启动服务，也不编译代码，更不托管预览页。它只做三件事：解析 .storybook/main.js 中的 stories 路径配置，匹配当前打开的组件文件名，然后生成跳转URL；提供右键菜单项（比如 Open Story for Current File）；在侧边栏嵌入一个Webview，加载已经运行起来的 http://localhost:6006 页面。

一个常见的误解是，装完扩展就能点一下预览。但实际情况是，必须先手动执行 npm run storybook，否则Webview打开后只会是一片空白，或者报错 ERR_CONNECTION_REFUSED。

• 扩展不会自动启动Storybook，VSCode本身也没有内置Node.js运行时来托管它。
• 如果 .storybook/main.js 里的 stories 是空数组，或者glob路径写错了（比如漏了 **/ 或拼错了后缀），右键菜单会直接消失。
• 在monorepo项目中，扩展只认当前工作区根目录下的 .storybook/，子包里的配置是不起作用的。

为什么“隔离开发”依赖Storybook启动方式而非扩展

所谓“隔离”，指的是组件渲染环境与主应用解耦：没有全局状态污染、没有路由干扰、没有API请求副作用。这些全都由Storybook的 preview.js 和框架适配器（比如 @storybook/react）控制，跟扩展的功能没有关系。

你改一个 useState 的初始值，能立刻看到效果，靠的是Storybook内部启用的HMR（热模块替换），而VSCode只是触发了保存事件。如果热更新失效了，问题一定出在 .storybook/main.js 的 webpackFinal 或Vite的 watchOptions 配置上，跟扩展无关。

话说回来，其实问题的关键往往不在这里。比如，检查一下 .storybook/main.js 是否包含了 features: { previewMdx: true }（旧版）或 previewAnnotations（v8+），否则MDX文档页是加载不出来的。Vite用户也要留个心眼：vite.config.ts 里如果设置了 server.hmr.overlay = false，热更新会悄无声息地失败。还有，不要在 *.stories.tsx 里调用未导出的工具函数或 require() 动态导入，这类代码会让HMR断连。

右键跳转 404 的真实原因和修复路径

点击 Open Story for Current File 后跳转到 http://localhost:6006/stories/button--primary 却显示404，90%的情况是story文件命名或导出不规范，导致Storybook无法注册这个story ID。

那么，问题出在哪里？Storybook的匹配逻辑是：从文件路径提取basename（比如 Button.stories.tsx → Button），再匹配默认导出的组件名或 default.title。一旦不一致，ID就对不上。

• 文件名必须包含 .stories.（两个点），Button.story.tsx 或 Button.test.stories.tsx 都不被识别。
• 导出必须是 export default { title: 'Components/Button' } 或 export default Button（且Button是命名导出或默认导出的React组件）。
• 如果用了 defineStory 或自定义ID，需要确保 id 字段与跳转URL中的slug完全一致。

真正卡住“隔离开发”的，从来不是VSCode插件装没装，而是 .storybook/main.js 配置是否让Storybook正确加载、识别、沙箱化你的组件。扩展只是把“写代码 → 看效果”之间的鼠标移动距离缩短了2秒，但那2秒背后，是整个构建链路的稳定性。