必须在VSCode中打开含pnpm-workspace.yaml的根目录，配置根tsconfig.json的baseUrl和paths映射子包路径，确保子包package.json含有效types字段并已构建，重启TS Server且调试时正确设置outFiles和sourceMap。
Pnpm Workspace 是目前最稳妥的本地多包管理方案，但直接在 VSCode 里开 Node 项目加 workspace 容易卡住、路径报错、require 找不到模块——根本原因是 VSCode 默认不识别 pnpm-workspace.yaml 的符号链接规则，也不自动激活 pnpm 的 node_modules 软链逻辑。
VSCode 启动时没加载 pnpm 的 node_modules 软链
现象：新开 VSCode 窗口后，TS 类型提示失效、import 报红、Ctrl+Click 进不去 workspace 内部包；运行时报 Error: Cannot find module 'xxx'。
- VSCode 默认使用系统或项目根目录下的
node_modules，而 pnpm 把真实依赖放在~/.pnpm-store，项目内只存软链接——必须让 VSCode 明确知道该用哪个node_modules - 确保项目根目录有
pnpm-workspace.yaml，且内容含packages:字段（如packages: ['packages/*']），否则 pnpm 不会建立 workspace 级别链接 - 执行
pnpm install后，检查根目录是否生成了node_modules/.pnpm子目录，以及node_modules/xxx是否为指向../packages/xxx的软链接（Linux/macOS 用ls -l，Windows 用dir） - 在 VSCode 设置中关闭
typescript.preferences.includePackageJsonAutoImports，避免 TS Server 错误解析package.json中的exports字段导致路径混乱
tsconfig.json 必须配 baseUrl + paths 才能跨包跳转
即使 pnpm 建好了软链，TypeScript 默认仍按相对路径解析 import，对 workspace 内部包（比如 import { foo } from '@myorg/utils'）无法推导类型或跳转。
- 在根目录
tsconfig.json中加入：{ "compilerOptions": { "baseUrl": ".", "paths": { "@myorg/utils": ["packages/utils/src/index.ts"], "@myorg/api": ["packages/api/src/index.ts"] } } } -
paths的 key 必须和packages/*/package.json中的name字段完全一致（包括 scope），否则 TS 不匹配 - 所有子包的
tsconfig.json需继承根配置（用"extends": "../tsconfig.json"），否则各自编译时路径不统一 - 改完
tsconfig.json后，重启 VSCode 的 TS Server：命令面板输入Restart TS server
pnpm run 在 VSCode 终端里不生效？检查 Shell 和 corepack 冲突
在 VSCode 内置终端执行 pnpm run build 报 command not found，或执行的是 npm 而非 pnpm，常见于 macOS/Linux 的 zsh 或 Windows 的 PowerShell。
- VSCode 终端默认复用系统 shell，但可能没把 pnpm 加入 PATH；运行
which pnpm确认路径，若为空，需手动安装：corepack enable（Node ≥16.14）或npm install -g pnpm - 若已用
corepack，检查.node-version或.nvmrc是否触发了 Node 版本切换，导致 corepack 激活失败 - VSCode 设置里搜索
terminal integrated env，添加环境变量："terminal.integrated.env.linux": { "PATH": "/home/xxx/.local/share/pnpm:$PATH" }（路径按实际调整） - 避免在
scripts中写pnpm run xxx嵌套调用——workspace 下应直接用pnpm --filter @myorg/utils run build
调试时断点进不了 workspace 包源码
用 VSCode Debugger 启动 index.ts，F11 进函数却停在编译后的 .js 文件，而非 packages/utils/src/xxx.ts。
- 确认子包
package.json中有"types": "dist/index.d.ts"且构建产物含sourceMap（tsc 的sourceMap: true） - 根目录
.vscode/launch.json中的outFiles必须包含所有子包的 dist 路径，例如："outFiles": [ "${workspaceFolder}/dist/**/*.js", "${workspaceFolder}/packages/*/dist/**/*.js" ] - 关键：每个子包的
tsconfig.json必须设"inlineSources": true或生成独立.map文件，并确保sourceRoot指向正确（推荐设为"sourceRoot": "../../../"，使 map 文件里的路径能回溯到根目录） - 不要依赖
node_modules/@myorg/utils的软链接做调试——VSCode Debugger 读的是物理路径，必须指向原始src/目录
真正麻烦的不是配置本身，而是 VSCode 缓存和 TypeScript Server 对 workspace 符号链接的感知延迟；每次增删包、改 pnpm-workspace.yaml 或重装依赖后，务必手动重启 TS Server + 清除 .vscode/.svelte（如有）和 node_modules/.pnpm 下对应链接。
