WebStorm需打开含pnpm-workspace.yaml或workspaces字段的仓库根目录，配置tsconfig.json的baseUrl、paths、composite和references，并确保pnpm install与构建完成，才能正确识别workspace并支持跨包跳转、类型推导和调试。
WebStorm 打开根目录后不识别 workspace
根本原因：WebStorm 没检测到合法的 workspace 声明文件，就当普通文件夹处理，所有子包被隔离。
- 必须用 WebStorm 打开整个仓库根目录（即含
pnpm-workspace.yaml或package.json中有workspaces字段的目录），不能只打开packages/my-lib -
pnpm-workspace.yaml要存在且格式正确，例如：packages:<br/> - "packages/*"<br/> - "apps/*"
- 重启 WebStorm 后右下角应出现「Workspace detected」提示；没出现就手动执行
File → Reload project from disk - 删过
node_modules后，必须先运行pnpm install（右键根目录package.json→ Run），再重启 IDE —— 否则.pnpm软链接缺失，workspace 关系无法建立
跨包 import 报红但 tsc 不报错
这是 TypeScript 编译器和 WebStorm 的路径解析没对齐，不是代码写错了。
- 根目录
tsconfig.json必须配置baseUrl和paths，例如："baseUrl": ".",<br/>"paths": {<br/> "@demo/utils": ["packages/utils/src"],<br/> "@demo/components": ["packages/components/src"]<br/>} - Settings → Languages & Frameworks → TypeScript → Compiler → 勾选
Use path mappings from tsconfig.json - 同时在 Settings → Languages & Frameworks → JavaScript → Libraries → Add，把
packages/utils/src、packages/components/src等实际源码路径加为Source Folders - 别在子包里另配
tsconfig.json覆盖baseUrl，除非明确需要隔离；否则 WebStorm 会忽略根配置，路径映射失效
Ctrl+Click 跳转失败或补全只显示当前包
本质是 TypeScript 语言服务没把多个包当成一个整体，类型引用链断了。
- 根目录
tsconfig.json必须设"composite": true，并显式声明references："references": [<br/> { "path": "packages/utils" },<br/> { "path": "apps/web" }<br/>] - 每个子包自己的
tsconfig.json也必须设"composite": true，否则 TS 语言服务拒绝参与跨项目解析 - 避免用 File Watcher 单独监听每个子包的
**/*.ts—— 容易触发嵌套编译雪崩；统一用根目录tsc --build驱动 - 如果用了
tsc --build，确保子包tsconfig.json中有"composite": true和"declaration": true，否则生成的.d.ts不会被引用
调试时断点不命中或跳进 node_modules
源码和构建产物路径没对上，WebStorm 找不到原始 src/ 文件。
- 子包
package.json的main和types字段必须指向构建产物，比如："main": "lib/index.js"、"types": "lib/index.d.ts"，不能写"main": "src/index.ts" - 根目录
tsconfig.json加"sourceRoot": "./"和"inlineSources": true，确保生成的.map包含原始路径信息 - Run Configuration 中勾选
Enable source maps，且Project root必须设为仓库根目录，不是某个子包路径 - 调试前确认子包已构建（
pnpm build或tsc --build），否则lib/目录为空，source map 无从映射
真正卡住人的地方不在配置项本身，而在顺序和依赖关系：先有 workspace 声明，才有路径映射；先有 composite + references，才有跨包类型推导；先有构建产物和正确的 main 字段，才有可调试的源码映射。漏掉任一环，现象都一样——“看起来配好了，但就是不工作”。
