Monorepo中npm脚本执行失败主因是WebStorm默认用系统npm而非项目实际包管理器（如pnpm/yarn）；需在Settings→Languages & Frameworks→JavaScript→Runtime中手动指定正确包管理器路径，并确保pnpm install已执行、.pnpm软链接完整，子包配置需显式设置Working directory及source maps映射。
Monorepo里npm脚本执行失败，根本不是命令写错了
WebStorm默认用系统全局npm，但Monorepo项目大概率用的是pnpm或yarn。右下角没显示pnpm图标，就说明它正在用错包管理器——哪怕你本地装了pnpm，WebStorm也可能完全无视。
- 进
Settings → Languages & Frameworks → JavaScript → Runtime，确认Package manager路径指向pnpm或yarn可执行文件，不是npm - 删过
node_modules后，必须先运行pnpm install（右键根目录package.json→Run 'pnpm install'），再重启WebStorm；否则.pnpm软链接不全，脚本找不到依赖 - 子包里的
npm run dev报command not found？别点编辑器里自动识别的脚本行——那是按主项目根目录执行的。必须新建npm配置，显式指定Package.json path为子包路径，Working directory也设成该子包目录
想同时跑前端+后端服务，别手动开两个终端
WebStorm支持“复合运行配置”，本质是把多个独立配置打包成一键启动的组合。它不是简单顺序执行，而是并行拉起所有服务，每个都在自己独立的选项卡里输出日志。
- 先为每个服务单独建好npm配置：比如
apps/web配pnpm run dev，apps/api配pnpm run start - 再新建一个
Compound配置，名字叫dev-all，把上面两个加进去 - 关键细节：
dev-all本身没有“工作目录”概念，它只是调度器；每个子配置必须各自设好Working directory，否则会全部在根目录下找package.json - 调试时，断点只对当前激活的选项卡生效；想切到API服务断点，得先点击对应日志选项卡
调试时断点不命中，90%是因为源码映射没对上
Monorepo里子包通常以workspace:方式被引用，实际加载的是构建后的lib/，但你写的断点在src/。WebStorm若没被告知“源码在哪”，就会跳进node_modules里找，或者干脆不触发。
- 子包
package.json的main和types字段必须指向构建产物，比如"main": "lib/index.js"、"types": "lib/index.d.ts"，不能写src/index.ts - 根目录
tsconfig.json加"sourceRoot": "./"和"inlineSources": true，确保生成的.map文件包含原始路径信息 - Run Configuration里勾选
Enable source maps，且Project root必须设为仓库根目录，不是某个子包路径 - 如果用了
tsc --build，确保子包tsconfig.json里有"composite": true，否则TypeScript不会生成可用的.map
代码补全失效、Ctrl+Click跳转失败，不是WebStorm卡了
这是Monorepo最典型的“作用域隔离”问题：WebStorm看到packages/utils/package.json，就默认把它当独立项目，不再向上查找根目录的类型定义和路径别名。
- 根目录
tsconfig.json必须设"composite": true，并用"references"显式列出所有子包路径，比如{"path": "packages/utils"} - 每个子包自己的
tsconfig.json也必须设"composite": true，否则TS语言服务拒绝参与跨项目解析 -
baseUrl和paths只在根tsconfig.json里配一次，子包别覆盖；WebStorm要读这个配置，就得在Settings → Languages & Frameworks → TypeScript → Compiler里勾选Use path mappings from tsconfig.json - 别用File Watcher逐个编译子包——改一个文件可能触发N次重编。统一用根目录
tsc --build驱动，参数加--verbose方便排查哪一环断了
真正麻烦的从来不是配置项数量，而是这些设置之间存在隐式依赖：比如references没生效，paths映射就找不到目标；pnpm install没跑完，.pnpm软链接缺失，baseUrl再对也跳转失败。每一步都得验证结果，而不是只看配置是否存在。
