require('./utils')报cannot find module主因是vscode调试时cwd与预期不符，node按process.cwd()解析路径而非program位置；需在launch.json中显式配置"cwd": "${workspacefolder}/src"。
为什么 require('./utils') 在 VSCode 调试时总报 Cannot find module
根本不是路径写错了，而是 VSCode 启动调试进程时的当前工作目录（cwd）和你预期的不一致。Node.js 的 require() 是相对 process.cwd() 解析的，不是相对于 program 文件位置。
- 默认情况下，VSCode 调试器的
cwd是项目根目录（${workspaceFolder}），但如果没显式声明，某些插件或旧版 launch.json 会 fallback 到用户主目录或空路径 - 比如你
program指向src/server.js，但server.js里写了require('./utils')，实际会去${workspaceFolder}/utils找，而不是${workspaceFolder}/src/utils - 解决办法：在
launch.json的 configuration 里加"cwd": "${workspaceFolder}/src"，让require()基于src目录解析 - ESM 项目更敏感——
import路径必须是相对或绝对路径，不能省略扩展名（./utils.js），且cwd错了会导致package.json#exports映射失效
package.json 里 "type": "module" 开了，但断点还是跳不到源码
VSCode 调试器默认按 CommonJS 模式加载文件，即使你用了 ESM，它仍可能忽略 source map 或错误解析 import 路径。
- 必须同时满足三个条件：①
package.json有"type": "module"；②launch.json中"type": "pwa-node"（不是旧版"node"）；③sourceMap正确生成并和.js文件同目录 - 如果用 TypeScript 编译 ESM，
tsconfig.json得设"module": "nodenext"或"module": "es2022"，且"outDir"和"rootDir"对齐，否则.js.map里的sources字段指向错误路径 - 别信
code-runner插件——它无视"type": "module"，强行用node命令跑，结果就是Cannot use import statement outside a module
本地 node -r dotenv/config 生效，但 VSCode 调试里环境变量不加载
VSCode 调试器不会自动继承你在 shell 里通过 dotenv 注入的环境变量，它只读 launch.json 的 env 字段或系统级环境变量。
- 不要依赖
node -r dotenv/config启动方式——调试器不走这个入口，-r参数不会被传递 - 正确做法：在
launch.json的 configuration 里加"env": {"NODE_ENV": "development"}，再手动加载.env文件（例如在server.js开头加require('dotenv').config()） - 如果要用
dotenv/config，得改用runtimeExecutable指向node，并把runtimeArgs设为["-r", "dotenv/config", "src/server.js"]，但这样会失去 source map 支持 - 注意：Windows 用户若用 PowerShell 启动 VSCode（
code .），.env文件里的换行符要是CRLF，否则dotenv解析失败，process.env为空
nodemon --inspect-brk 能热重载，但 VSCode 断点经常失效
不是 nodemon 问题，是 VSCode 的 attach 模式没等进程真正监听调试端口就提前连接，导致断点注册失败。
- 不要在
launch.json里直接设"runtimeExecutable": "nodemon"——这是最常见误配，VSCode 会尝试启动 nodemon 进程而非附加到它 - 推荐方案：终端先运行
nodemon --inspect-brk=9229 src/server.js，然后在launch.json新建一个"request": "attach"配置，指定"port": 9229，再手动点击「开始调试」 - 加
"restart": true和"timeout": 5000可提升 attach 稳定性，避免因端口未就绪而失败 - 如果用
npm run dev封装了 nodemon，确保 script 是"dev": "nodemon --inspect-brk=9229 src/server.js"，而不是"dev": "nodemon src/server.js"——缺--inspect-brk就无法调试
require 和 import 在运行时表现一致，VSCode 调试器也会因启动方式不同而触发完全不同的解析链。
