vscode调试时模块报错但终端能运行，是因javascript/typescript语言服务默认不解析node_modules中的软链接（如pnpm/yarn workspaces生成的.symlinks），导致intellisense和调试器无法定位真实路径；解决方案包括：在tsconfig.json中配置moduleresolution="node"与paths映射物理路径、在launch.json中注入path环境变量使调试进程识别软链接、或改用pnpm hoisted模式。
VSCode调试时模块报错但终端能跑，是软链接没被识别
VSCode的JavaScript/TypeScript语言服务默认不解析node_modules里的符号链接（symlink），尤其在pnpm或yarn workspaces项目中，node_modules/.pnpm或node_modules/.yarn/sdks下大量使用软链接。结果就是：终端里node -r ts-node/register index.ts能跑通，但VSCode调试或IntelliSense却提示Cannot find module 'xxx'。
这不是代码问题，是VSCode没把软链接当真实路径处理。它只扫描物理存在的文件，跳过readlink后的目标路径。
- 确认是否为软链接问题：在项目根目录运行
ls -la node_modules/xxx，如果输出类似xxx -> .pnpm/xxx@1.2.3/node_modules/xxx，就是软链接 - 临时验证：把
node_modules/xxx删掉，手动cp -r .pnpm/xxx@1.2.3/node_modules/xxx node_modules/，再重启TS Server（Ctrl+Shift+P →Developer: Restart TS Server），如果错误消失，基本锁定是软链接解析失败 - 不要改
NODE_PATH——它会干扰模块解析顺序，反而让问题更隐蔽
tsconfig.json里加moduleResolution和paths绕过软链接
VSCode的TS语言服务依赖tsconfig.json做路径映射，而不是靠node_modules结构。对pnpm/yarn项目，直接告诉TS“这个包实际在哪儿”，比等它去遍历软链接靠谱得多。
在项目根目录tsconfig.json的compilerOptions里加：
{
"compilerOptions": {
"moduleResolution": "node",
"baseUrl": ".",
"paths": {
"lodash": ["node_modules/.pnpm/lodash@4.17.21/node_modules/lodash"],
"@myorg/utils": ["packages/utils/src"]
}
}
}
注意：paths值必须是相对于baseUrl的物理路径，不能写node_modules/lodash这种逻辑路径；版本号要和.pnpm目录里实际文件夹名一致（可用ls node_modules/.pnpm确认）。
- 只对TS项目有效；纯JS项目需配
jsconfig.json，且moduleResolution设为node才生效 -
moduleResolution: "node"是必须项，否则paths会被忽略 - 别用通配符如
"*": ["node_modules/.pnpm/*"]——TS不支持，会直接失效
launch.json里加env让调试进程继承软链接环境
VSCode调试器启动的Node进程，默认不加载shell的完整环境变量，也就看不到nvm或pnpm设置的PATH和PWD，导致require()找不到软链接指向的真实路径。
在.vscode/launch.json的配置里显式注入关键环境变量：
{
"configurations": [{
"type": "pwa-node",
"request": "launch",
"name": "Launch via NPM",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"env": {
"NODE_OPTIONS": "--enable-source-maps",
"PNPM_HOME": "${env:PNPM_HOME}",
"PATH": "${env:PATH}"
}
}]
}
-
"PATH": "${env:PATH}"是关键——它把当前终端的PATH带进调试进程，让Node能沿正确路径找到.pnpm目录 - 如果用了nvm-windows，确保
PATH里包含D:\nvm4w\nodejs，否则即使写了${env:PATH}也无效 - 不要加
NODE_PATH：它会让Node跳过node_modules层级查找，反而绕过软链接目标
pnpm用户必须关掉node-linker或换用hoisted
pnpm默认用isolated模式（即每个包独立node_modules + 软链接），这是模块找不到的根源。VSCode不兼容这种结构，但pnpm提供替代方案。
在项目根目录.pnpmfile.cjs里强制切换链接策略：
module.exports = {
nodeLinker: 'hoisted'
};
然后删掉node_modules和pnpm-lock.yaml，重新pnpm install。此时node_modules变成扁平结构，所有包都在一层，VSCode能直接扫描到。
-
hoisted模式牺牲了磁盘空间节省，但换来VSCode兼容性——对开发机来说值得 -
node-linker: 'hoisted'只影响当前项目，不影响全局pnpm配置 - 如果团队强制用
isolated，那就只能靠tsconfig.json映射+launch.json环境注入双保险
软链接不是bug，是包管理器的设计选择；VSCode不认它，也不是缺陷——只是两者对“模块位置”的理解不在同一层。真正卡住人的，往往是以为改了PATH就万事大吉，却没意识到TS语言服务和调试器各自走的是完全不同的路径解析链。
