VSCode调试CLI工具卡顿、断点失效、argv为空等问题源于Node.js启动方式与CLI参数传递链路未对齐：ESM需显式配置loader和sourceMaps；commander需在launch.json中明确args并避免提前读取process.argv；yargs异步handler要正确声明async且断点打在await行末尾。
VSCode 调试 yargs 或 commander 项目时卡在入口文件不进断点、argv 为空、异步命令里 handler 不触发 —— 这些不是配置漏了，而是 Node.js 启动方式和 CLI 参数传递链路没对齐。
为什么 launch.json 里 program 指向 .mjs 文件却进不了断点
Node.js 对 ESM（.mjs）的调试支持依赖于 --loader 和源码映射，但 VSCode 默认调试器不自动注入这些。如果你的 yargs 示例用的是 import + export，又没显式启用 ESM 支持，断点会直接跳过。
- 确认
package.json中有"type": "module"，否则.mjs文件会被当成 CommonJS 加载，导致import报错或静默失败 -
launch.json中必须加"runtimeArgs": ["--loader", "ts-node/esm"]（若用 ts-node）或"runtimeArgs": ["--experimental-specifier-resolution=node"]（纯 JS 场景） -
sourceMaps设为true的同时，确保构建产物（如dist/）里有对应.map文件；若直接调试源码，删掉outFiles字段，避免路径匹配失败
commander 的 program.parse() 不触发 handler 怎么办
常见现象是调试器跑完 program.parse() 就退出，handler 函数根本没执行 —— 本质是 process.argv 在调试启动时被 VSCode 截断或覆盖了。
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
- 不要依赖默认
process.argv：在launch.json的args字段里明确传参，例如["--help"]或["init", "--force"] - 避免在
program.parse()前调用console.log(process.argv)—— 它可能触发 Node.js 的 argv 缓存机制，导致后续 parse 读到空数组 - 如果用了
program.addHelpText()或自定义action，确保它们没提前process.exit()；调试时可临时注释掉 exit 调用
yargs 异步 handler 中断点失效的根源
async 函数本身不会阻止断点，但 yargs 内部的 Promise 链调度会让 VSCode 的“单步进入”行为失效 —— 你点了 step into，结果跳到了 node:internal/process/task_queues，而不是你的 await fetch() 行。
- 把断点打在
await行的**右侧**（即语句末尾分号前），而不是async函数签名行 - 禁用
skipFiles: ["<node_internals>/**"]</node_internals>可能反而更糟；保留它，但把"node_modules/yargs/**"加进skipFiles，避免陷进 yargs 内部 Promise 处理逻辑 - 若 handler 返回 Promise 但没
await，VSCode 会认为函数已同步返回，断点失效；务必写成handler: async (argv) => { ... }，不要漏掉async
调试时 argv 始终为空或结构异常
这不是 yargs 解析失败，而是 VSCode 启动进程时没把参数正确注入到子进程环境。尤其当项目用 #!/usr/bin/env node + chmod +x 方式运行 CLI 时，调试器根本绕过了 shebang，导致参数丢失。
- 调试一律用
node --inspect-brk启动，别直接运行 CLI 可执行文件 - 检查
launch.json中program是否指向真实的入口文件（如src/cli.js），而不是bin/cli这类软链接或包装脚本 - 如果用了
yargs.scriptName("mycli")，调试时args数组第一个元素必须是"mycli"，否则 yargs 会忽略后续参数
真正卡住人的地方往往不是语法或配置，而是 Node.js 调试器对 CLI 参数生命周期的理解偏差：它不模拟 shell 执行链，只注入 argv 到当前进程。一旦你依赖了 shebang、npm run script 包装、或跨平台路径解析，就得手动对齐参数格式和加载时机。
