必须实现initialize和launch方法，否则vs code会超时报错“cannot connect to runtime process”；initialize需返回supportsconfigurationdonerequest=true，launch须从request.arguments解构参数，且进程须5秒内发送initialized事件。
vscode-debugadapter 协议调试器必须实现 initialize 和 launch 方法
不实现这两个方法，VS Code 会直接报错 Cannot connect to runtime process (timeout after 10000ms)，而不是提示语法错误或配置缺失。这是因为调试会话启动流程严格依赖协议握手阶段的响应顺序。
实操建议：
-
initialize必须返回{ capabilities: { supportsConfigurationDoneRequest: true } }，否则后续configurationDone请求会被忽略 -
launch中若需读取args或env，务必从request.arguments解构，而非直接访问request对象顶层字段（VS Code 1.85+ 已移除该兼容层） - 调试器进程启动后，必须在 5 秒内发送
initializedevent，否则前端自动断连
Node.js 调试器开发中 vscode-debugadapter 与 vscode-debugprotocol 版本必须严格匹配
常见错误现象是断点命中但变量面板为空、stepOver 失效、或控制台输出乱码。根本原因是协议定义变更（如 2025 年底起 stackTraceResponse 中 frameId 改为 id），而旧版 adapter 仍按老结构解析。
实操建议：
- 用
npm ls vscode-debugprotocol检查实际安装版本，确保与package.json中声明的vscode-debugadapter主版本一致（例如都为1.49.x） - 不要在
devDependencies中混用不同大版本的调试协议包，VS Code 1.87+ 会拒绝加载不匹配的调试器 - 本地测试时，用
code --extensionDevelopmentPath=.启动调试实例，比直接 F5 更早暴露协议不兼容问题
调试器注册后无法触发 attach 流程？检查 activationEvents 是否包含 onDebug
插件激活失败最隐蔽的原因之一：即使 package.json 中写了 "debuggers" 字段，若 "activationEvents" 缺少 "onDebug"，VS Code 根本不会调用 activate()，自然也不会执行 vscode.debug.registerDebugConfigurationProvider。
实操建议：
- 确认
package.json中有且仅有这一条激活事件："onDebug"（不是"onDebug:xxx"，后者是旧版写法，已废弃） - 如果同时支持
launch和attach，无需额外声明；但若只做attach场景（如远程调试），仍需"onDebug"触发初始化 - 可通过命令面板运行
Developer: Toggle Developer Tools，在 Console 中搜索registerDebugConfigurationProvider是否被调用
中文日志乱码或断点位置偏移？优先排查 sourceMaps 路径映射和 locale 环境变量
调试器内部日志含中文时出现方块或问号，或断点总停在上一行/下一行，通常不是代码逻辑问题，而是路径编码或区域设置未对齐。
实操建议：
- 在
launch.json的env中显式添加"LANG": "zh_CN.UTF-8"（Linux/macOS）或"chcp 65001 > nul"（Windows CMD 启动前） -
sourceMapPathOverrides必须使用正则而非字符串替换，例如：{"webpack:///./src/*": "${workspaceFolder}/src/*"}，否则中文路径中的／与/会被误判 - 避免在调试器进程里用
console.log输出中文——改用logger.log('info', '中文消息')（通过vscode-debugadapter提供的 logger），它会自动处理编码
locale: "zh-cn"，只影响 UI 层；调试器进程仍按系统默认 locale 运行，除非你主动透传并重置。
