如何通过WebStorm调试Storybook中的NextJS/React应用

1. 单独配置Storybook的Source Map #

哪怕NextJS应用的source map正常，Storybook需要单独配置确保源码映射正确：

• 打开.storybook/main.js（或main.ts），修改webpack配置：

module.exports = {
  webpackFinal: async (config) => {
    config.devtool = 'eval-cheap-module-source-map'; // 也可选用'source-map'，按需调整
    return config;
  },
};

• 修改后重启Storybook，打开浏览器DevTools的Sources面板，确认组件的本地源码文件能正常加载，这是断点生效的前提。

2. 创建专属的WebStorm调试配置 #

别用“附加到已运行浏览器”的方式，直接通过npm调试配置绑定进程：

1. 打开WebStorm的Run/Debug Configurations，点击+选择npm
2. 在Scripts下拉框中选择storybook（对应你package.json里的脚本）
3. Browser选项固定选Chrome（WebStorm调试仅支持Chromium内核浏览器）
4. 勾选JavaScript debugger选项
5. 保存配置后，点击Debug按钮启动Storybook，不要手动打开浏览器

3. 调整Storybook启动脚本参数 #

修改package.json中的脚本，强制以开发模式启动并禁止自动打开浏览器：

{
  "scripts": {
    "storybook": "NODE_ENV=development storybook dev -p 6006 --no-open"
  }
}

让WebStorm全权控制浏览器启动，确保调试器与Storybook进程完全绑定。

4. 排查组件文件映射问题 #

• 确认Storybook加载的是本地源码组件，而非node_modules中的编译产物
• 断点必须打在自己编写的源文件上，避免误打在编译后的文件中
• 若使用TypeScript，检查.storybook/main.js是否正确配置了TS loader，保证TS代码能生成有效的source map

5. 几个容易忽略的细节 #

• 关闭WebStorm的Safe Write功能：路径为Settings → Appearance & Behavior → System Settings，取消勾选"Use safe write"，避免文件更新延迟导致source map失效
• 清除Storybook缓存：执行npx storybook clean后重启服务
• 禁用Chrome缓存：打开DevTools的Network面板，勾选"Disable cache"，确保加载最新的source map

内容的提问来源于stack exchange，提问作者Alex Dobson-Pleming