VSCode调试器开发指南_自定义运行时支持实现-VSCode-PHP中文网

VSCode调试器开发指南_自定义运行时支持实现

紅蓮之龍

发布： 2025-11-27 08:17:02

原创

370人浏览过

答案：通过实现Debug Adapter Protocol（DAP）并编写调试适配器，可在VSCode中为自研脚本引擎等自定义运行时环境添加完整调试支持。具体步骤包括使用yo code初始化扩展项目，在package.json中注册调试类型，编写Debug Adapter处理初始化、启动、断点设置等DAP请求，并通过事件机制与VSCode同步调试状态，最终实现媲美内置调试器的体验。

vscode调试器开发指南_自定义运行时支持实现

想让 VSCode 支持调试你自己的运行时环境？比如一个自研脚本引擎、嵌入式解释器，甚至是一个远程设备上的执行环境？VSCode 本身不直接支持这些，但通过扩展机制，你可以实现完整的调试体验。关键在于理解并实现 Debug Adapter Protocol (DAP) 和编写对应的调试适配器（Debug Adapter）。

理解 VSCode 调试架构

VSCode 的调试功能是模块化的。编辑器本身只负责用户界面（断点、变量查看、调用栈等），真正的调试逻辑由独立的 Debug Adapter 处理。两者通过标准协议通信：

Debug Adapter Protocol (DAP)：基于 JSON-RPC 的通信协议，定义了 VSCode（客户端）和 Debug Adapter（服务端）之间的消息格式。
Debug Adapter：一个独立进程，负责与实际的运行时（你的目标环境）交互，比如启动程序、设置断点、获取变量值，并将结果通过 DAP 返回给 VSCode。

创建自定义调试扩展

开发流程通常分为三步：注册调试类型、实现 Debug Adapter、连接前端与后端。

1. 初始化扩展项目

使用 yo code 脚手架，选择 “New Extension (TypeScript)” 或 “New Debug Adapter” 模板。
模板会生成基础文件结构，包括 package.json、src/extension.ts（VSCode 端）和 src/debugAdapter.ts（适配器端）。

2. 配置 package.json

在 package.json 的 contributes.debuggers 字段中声明你的调试器：

{
  "type": "myruntime",
  "label": "My Custom Runtime",
  "languages": ["mylang"],
  "adapterExecutableCommand": "my-debug-adapter", 
  "variables": { "configFile": "${workspaceFolder}/config.json" },
  "configurationAttributes": {
    "launch": {
      "required": ["program"],
      "properties": {
        "program": {
          "type": "string",
          "description": "The program to debug."
        },
        "host": {
          "type": "string",
          "default": "localhost"
        }
      }
    }
  }
}

登录后复制

这里定义了调试类型名为 myruntime，用户 launch.json 中的 type 必须匹配。如果适配器是独立可执行文件，用 adapterExecutableCommand 指定命令；如果是内联 Node.js 脚本，用 adapterProvider。

Ex驾校预约小程序

传统驾校预约方式步骤繁琐，效率低下，随着移动互联网科技和5G的革新，驾校考试领域迫切需要更加简洁、高效的预约方式，便捷人们的生活。因此设计基于微信小程序的驾校预约系统，改进传统驾校预约方式，实现高效的驾校学校预约。采用腾讯提供的小程序云开发解决方案，无须服务器和域名。驾校预约管理：开始/截止时间/人数均可灵活设置，可以自定义客户预约填写的数据项驾校预约凭证：支持线下到场后校验签到/核销/二维码自

查看详情

实现 Debug Adapter 核心逻辑

Debug Adapter 是核心，需处理 DAP 请求。常用 vscode-debugadapter 和 vscode-debugprotocol 库简化开发。

主要方法重写示例：

class MyDebugAdapter extends DebugSession {
  protected initializeRequest(
    response: DebugProtocol.InitializeResponse,
    args: DebugProtocol.InitializeRequestArguments
  ): void {
    this.sendResponse(response);
    // 告知客户端支持的能力，如是否支持条件断点
    this.sendEvent(new InitializedEvent());
  }

  protected launchRequest(
    response: DebugProtocol.LaunchResponse,
    args: ILaunchRequestArguments
  ): void {
    // 启动你的运行时，例如 spawn 子进程或连接远程设备
    this.runtime = new MyRuntime(args.program, args.host);
    this.runtime.on('stopOnEntry', () => {
      this.sendEvent(new StoppedEvent('entry', MyDebugAdapter.MAIN_THREAD));
    });
    this.sendResponse(response);
  }

  protected setBreakPointsRequest(
    response: DebugProtocol.SetBreakpointsResponse,
    args: DebugProtocol.SetBreakpointsArguments
  ): void {
    const filePath = this.convertClientPathToDebugger(args.source.path!);
    const actualBreakpoints = args.breakpoints!.map(bp => {
      const hit = this.runtime.setBreakPoint(filePath, bp.line, bp.condition);
      return { verified: hit, line: bp.line };
    });
    response.body = { breakpoints: actualBreakpoints };
    this.sendResponse(response);
  }
}

登录后复制

当运行时触发断点或异常时，适配器需主动发送 StoppedEvent 给 VSCode。当用户单步或继续，VSCode 会发送 continueRequest 或 nextRequest，适配器需转发给运行时。