不存在真正意义上的“一键重构依赖链”，所谓“一键”实际是把npm install、package.json修正、类型定义补全、VSCode缓存刷新这四步串起来——漏掉任意一环，就会出现import标红但运行正常、或断点失效但控制台能输出的割裂现象。
不存在真正意义上的“一键重构依赖链”，所谓“一键”实际是把 npm install、package.json 修正、类型定义补全、VSCode 缓存刷新这四步串起来——漏掉任意一环，就会出现 import 标红但运行正常、或断点失效但控制台能输出的割裂现象。
node -v 和 npm -v 在系统终端失败，所有后续操作都无效
这是最常被跳过的前置验证。VSCode 里装再多插件，只要系统终端连 node -v 都报错，依赖链就根本没机会建立。
- Windows 用户检查安装时是否勾选了 Add to PATH；没勾选就重装，别试图手动改环境变量——Node.js 安装器会自动写 registry 和 PATH 两处，只改其一常导致不一致
- macOS/Linux 用户用
nvm的，必须在 VS Code 启动前完成nvm use，否则集成终端可能继承的是系统默认 Node（如 /usr/bin/node），而非 nvm 管理的版本 - 验证方式不是只看 VS Code 内置终端，而是新开一个系统终端（cmd / Terminal / PowerShell），执行
node -v和npm -v有输出才算过关
package.json 里写了依赖，但 import 仍标红
VSCode 不会自动读取 package.json 并加载类型定义，它依赖 jsconfig.json 或 tsconfig.json 显式声明模块解析规则。
- JS 项目必须在根目录放
jsconfig.json，内容至少含：{"compilerOptions": {"allowSyntheticDefaultImports": true, "moduleResolution": "node"}} - TS 项目若用了
@types/xxx，需确认tsconfig.json中"types"字段包含对应包名，或删掉该字段让 TypeScript 自动扫描node_modules/@types - ESM 项目（
"type": "module"）中用require()加载 CommonJS 包，会导致类型提示丢失——优先改用import，或临时加"resolveJsonModule": true配合import pkg from './package.json' assert { type: 'json' }
npm install 后 VSCode 仍提示 Cannot find module
这不是网络或权限问题，是 VSCode 没重载语言服务缓存。它不会监听 node_modules 变更，也不会自动刷新路径索引。
- 执行完
npm install或npm update后，必须关闭所有已打开的 JS/TS 文件，再重新打开——否则编辑器仍持旧 AST 引用 - 大型项目建议直接重启 VSCode（不是 Reload Window），尤其当
node_modules/.vscode目录存在时，该目录是旧版插件残留的缓存，可安全删除 - 如果用了
pnpm或yarn pnp，需额外安装对应插件（如Yarn PnP Support），否则 VSCode 默认按node_modules平铺结构解析，会找不到链接后的路径
调试时断点不生效，但 node app.js 能跑
说明运行时没问题，但调试器没正确接入模块解析链。常见于使用 ts-node、esbuild-node 或自定义 loader 的场景。
- launch.json 中不要硬塞
"runtimeExecutable": "ts-node"—— 这会让调试器误以为是普通可执行文件，跳过 Node.js 原生调试协议 - TS 项目应配
"runtimeArgs": ["--loader", "ts-node/esm"]，并确保ts-node是全局安装或node_modules/.bin下可执行 - 若用
nodemon，不要放进runtimeExecutable；改用preLaunchTask启动监听进程，再让调试器 attach 到其子进程
真正的瓶颈不在命令多寡，而在每一步是否严格满足上下文约束：PATH 必须对、jsconfig.json 必须存在、node_modules 修改后必须关文件再开、调试配置必须匹配实际启动方式——四个条件缺一不可，少一个，“一键”就变成手动排障。
