VS Code语言服务器扩展指南缺失"Attach"启动配置问题

1. 配置服务器以调试模式启动 #

要让语言服务器处于可调试状态，需修改客户端扩展的启动代码（通常为client/src/extension.ts），为服务器的debug模式添加端口参数：

import * as path from 'path';
import { ExtensionContext } from 'vscode';
import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from 'vscode-languageclient/node';

let client: LanguageClient;

export function activate(context: ExtensionContext) {
  const serverModule = context.asAbsolutePath(
    path.join('server', 'out', 'server.js')
  );

  // 区分运行/调试模式的服务器配置
  const serverOptions: ServerOptions = {
    run: { module: serverModule, transport: TransportKind.ipc },
    debug: {
      module: serverModule,
      transport: TransportKind.ipc,
      // 开启Node.js调试端口9229
      execArgv: ['--inspect=9229']
    }
  };

  const clientOptions: LanguageClientOptions = {
    documentSelector: [{ scheme: 'file', language: 'your-language-id' }],
    synchronize: {
      fileEvents: context.workspace.createFileSystemWatcher('**/.clientrc')
    }
  };

  client = new LanguageClient(
    'languageServerExample',
    'Language Server Example',
    serverOptions,
    clientOptions
  );

  client.start();
}

export function deactivate(): Thenable<void> | undefined {
  return client?.stop();
}

2. 修正launch.json中的Attach配置 #

替换你手动添加的Attach配置，必须指定服务器编译输出的outFiles路径——这是解决unbound breakpoint问题的核心：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Client",
            "type": "extensionHost",
            "request": "launch",
            "runtimeExecutable": "${execPath}",
            "args": ["--extensionDevelopmentPath=${workspaceRoot}"],
            "outFiles": ["${workspaceRoot}/client/out/**/*.js"],
            "preLaunchTask": {
                "type": "npm",
                "script": "watch"
            }
        },
        {
            "name": "Language Server E2E Test",
            "type": "extensionHost",
            "request": "launch",
            "runtimeExecutable": "${execPath}",
            "args": [
                "--extensionDevelopmentPath=${workspaceRoot}",
                "--extensionTestsPath=${workspaceRoot}/client/out/test/index",
                "${workspaceRoot}/client/testFixture"
            ],
            "outFiles": ["${workspaceRoot}/client/out/test/**/*.js"]
        },
        {
            "name": "Attach to Server",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "skipFiles": ["<node_internals>/**"],
            // 指向服务器编译后的JS文件，需与实际输出路径一致
            "outFiles": ["${workspaceRoot}/server/out/**/*.js"]
        }
    ]
}

3. 确保编译脚本同时监控客户端和服务器 #

修改package.json的scripts，让watch命令同时编译两端的TypeScript代码，避免因代码未及时编译导致服务异常退出：

{
  "scripts": {
    "vscode:prepublish": "npm run compile",
    "compile": "npm run compile:client && npm run compile:server",
    "compile:client": "tsc -p client/tsconfig.json",
    "compile:server": "tsc -p server/tsconfig.json",
    "watch": "npm run watch:client & npm run watch:server",
    "watch:client": "tsc -w -p client/tsconfig.json",
    "watch:server": "tsc -w -p server/tsconfig.json"
  }
}

4. 正确的调试流程 #

1. 运行Launch Client配置，VS Code会启动新窗口，客户端将以debug模式启动语言服务器（开启9229端口）。
2. 在原窗口的Run and Debug视图选择Attach to Server，按F5附加调试器。
3. 此时在server/src/server.ts中添加的断点将正常绑定，不会再出现"unbound breakpoint"提示。

5. 服务秒退的额外排查点 #

• 检查服务器的tsconfig.json是否开启sourceMap: true，这是断点映射到TypeScript文件的必要条件：

  {
    "compilerOptions": {
      "sourceMap": true,
      // 其他配置项...
    }
  }
  

• 手动执行npm run watch，确认没有编译错误，确保preLaunchTask的脚本正常运行。

内容的提问来源于stack exchange，提问作者Pete Gardner