WebStorm识别Monorepo子包需打开根目录并配置workspace文件。必须确保根目录含pnpm-workspace.yaml或workspaces字段，启用tsconfig paths映射与composite+references，且调试时Project root指向根目录而非子包。
WebStorm 默认不把 packages/ 下的子包当项目成员，除非你明确告诉它“这是一个 workspace”，否则所有跨包跳转、类型提示、调试断点都会失效。
打开根目录 + 确认 workspace 配置文件存在
这是最基础也最容易被跳过的一步。如果你只打开了 packages/my-utils 这个文件夹，WebStorm 就只会把它当独立项目处理，node_modules 里没有其他本地包的软链接，tsconfig.json 的 paths 也找不到映射目标。
- 必须用 WebStorm 打开整个仓库根目录（即包含
pnpm-workspace.yaml或package.json中有workspaces字段的文件夹） - 确认根目录下有合法的 workspace 声明：pnpm 用户检查
pnpm-workspace.yaml是否存在且格式正确（如packages: ["packages/*", "apps/*"]）；npm/yarn 用户检查package.json的workspaces字段是否已声明 - 重启 WebStorm 后看右下角是否出现「Workspace detected」提示；没出现就手动触发
File → Reload project from disk
启用 tsconfig paths 映射并开启 WebStorm 解析支持
子包之间写 import { foo } from 'my-utils' 报红，不是路径写错了，而是 WebStorm 没启用 TypeScript 的路径别名解析规则。
Galileo TypeScript sdk
下载
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
- 确保根目录
tsconfig.json中配置了baseUrl和paths，例如："baseUrl": ".", "paths": { "my-utils": ["packages/my-utils/src"] } - 进
Settings → Languages & Frameworks → TypeScript → Compiler，勾选Use path mappings from tsconfig.json - 如果用了 pnpm，删过
node_modules后务必先运行pnpm install再重启 WebStorm —— 否则.pnpm软链接结构不完整，路径映射会失效 - 避免在子包里单独配
tsconfig.json覆盖根配置，除非明确需要隔离；否则极易导致类型路径错乱
设置 composite + references 实现跨包类型推导
代码补全只显示当前子包内容、Ctrl+Click 跳转失败、TS2307 报错，本质是 TypeScript 语言服务没把多个 package.json 当成一个整体看待。
- 根目录
tsconfig.json必须设"composite": true，并添加"references"显式声明依赖关系，例如："references": [{ "path": "packages/my-utils" }, { "path": "apps/web" }] - 每个子包自己的
tsconfig.json也要设"composite": true，否则 TS 语言服务拒绝参与跨项目解析 - 子包
tsconfig.json推荐用"extends": "../tsconfig.base.json"继承根配置，路径要对，不能漏掉../ - 改完配置后，必须手动重启 TypeScript Server：按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入Restart TS Server
调试和运行脚本时注意包管理器与路径一致性
点击虫子图标调试却卡住、断点不生效、或者运行的是 npm run dev 却实际调用了 yarn，根本原因是 WebStorm 没对齐“你写的脚本”“你装的包管理器”“你期望的执行路径”这三者。
- 右下角状态栏必须显示正确的包管理器图标（
pnpm/yarn），没显示就去Settings → Languages & Frameworks → JavaScript → Runtime手动指定可执行路径，不要依赖Auto-detect - 调试前端脚本（如
vite dev）时，进Run → Edit Configurations → Browser / Live Edit，勾选After launch并填入真实服务地址（如http://localhost:5173），否则只是执行命令，无法断点或热更新 - 运行调试前，确认子包
package.json的main/types字段指向构建后产物（如lib/index.js），而不是src/—— 否则调试器会在源码找断点，但实际执行的是编译后代码 -
Run → Edit Configurations → Node.js中，Project root必须指向仓库根目录，不是某个子包
Monorepo 的复杂性不在配置项数量，而在于多个配置层（workspace、tsconfig、package.json、IDE 设置）必须严格对齐；任意一层错位，就会表现为“看起来配好了，但就是不工作”。尤其要注意 WebStorm 不会自动热更新路径映射和 TS Server 状态，重启和手动触发是常态，不是例外。
