adonisjs 5+ 调试需严格匹配 esm 模块系统：package.json 必须含 "type": "module"，launch.json 设 "type": "node"、"program": "${workspacefolder}/bin/server.js"、"cwd": "${workspacefolder}"，ts 项目加 "runtimeargs": ["--loader", "ts-node/esm"]，启用 sourcemap 并配 "env": {"node_options": "--enable-source-maps"}，热重载须用 "request": "attach" 模式连接 nodemon 启动的 --inspect 进程。
AdonisJS 5+ 是 ESM 项目，package.json 必须有 "type": "module"，否则 VSCode 调试器会按 CommonJS 解析所有 import，直接报 Cannot use import statement outside a module——这不是插件或路径问题，是模块系统不匹配的根本错误。
launch.json 的 type 和 program 必须严格对应 AdonisJS 入口
VSCode 调试器不认 src/server.ts 或 start/server.ts，它只执行已加载的 JavaScript。AdonisJS 官方 CLI 入口是 bin/server.js，这是最稳定的选择。
-
"type": "node"（固定值，不是"nodejs"或"adonis"） -
"program": "${workspaceFolder}/bin/server.js"（开发期首选；若用npm run build，则必须改为build/server.js） -
"cwd": "${workspaceFolder}"（显式设工作目录，避免require('./config')因路径解析失败而报Cannot find module） - 纯 JS 项目可省略
runtimeArgs；TS 项目必须加"runtimeArgs": ["--loader", "ts-node/esm"]
sourceMap 不生效？检查 tsconfig.json 和输出结构
断点落在 app/Controllers/Http/UserController.ts 上却跳过，大概率是因为调试器读的是 build/app/Controllers/Http/UserController.js，但没找到对应的 .js.map 文件。
-
tsconfig.json中必须启用："sourceMap": true、"outDir": "build"、"rootDir": "src" - 编译后，
build/server.js和build/server.js.map必须在同一目录 - 更可靠的方式是加
"env": {"NODE_OPTIONS": "--enable-source-maps"}，比仅靠sourceMaps: true更强
用 nodemon 热重载时，别用 launch 模式硬启
把 runtimeExecutable 指向 nodemon 是常见陷阱：VSCode 启动 nodemon 进程后，无法稳定附加到它 fork 出来的子 Node 进程，导致断点跳过、process.env 丢失、require 报错。
- 终端先运行：
npm run dev -- --inspect-brk（AdonisJS 默认devscript 已含 nodemon +--inspect） -
launch.json新增配置："request": "attach"、"port": 9229（端口需与命令行一致） - 确保
package.json中"scripts.dev"类似："adonis serve --dev --inspect"
最容易被忽略的一点：VSCode 内置终端里运行 node -v 必须有输出。如果报 command not found，说明它根本没读你的 shell 初始化文件（如 ~/.zshrc），PATH 缺失——此时配再完美的 launch.json 都白搭。
