VSCode中调试基于pygls的Python语言服务器扩展问题求助

核心问题拆解 #

你的问题本质是VSCode扩展（Node.js进程）与pygls语言服务器（Python进程）的跨进程调试关联问题——默认扩展调试配置只会跟踪Node进程，不会自动附加到独立运行的Python服务器进程，导致Python断点无法触发。

具体调试步骤建议 #

1. 拆分调试流程，手动关联进程 #

• 先单独启动Python语言服务器并开启调试监听：
  在你的服务器入口文件（如json_server.py）开头添加调试器初始化代码，仅用于开发阶段：

  import debugpy
  # 开启本地调试监听端口
  debugpy.listen(("localhost", 5678))
  print("等待调试器附加...")
  debugpy.wait_for_client()
  

• 启动VSCode扩展的调试会话（使用默认扩展调试配置），等Python控制台打印“等待调试器附加”后，再通过VSCode的Python调试配置附加到5678端口，此时断点即可触发。

2. 配置VSCode调试文件，实现自动附加 #

修改.vscode/launch.json，添加两个关联配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "启动扩展",
      "type": "extensionHost",
      "request": "launch",
      "runtimeExecutable": "${execPath}",
      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
      "outFiles": ["${workspaceFolder}/out/**/*.js"],
      "preLaunchTask": "npm: watch"
    },
    {
      "name": "附加到Python语言服务器",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "justMyCode": false
    }
  ]
}

• 先启动“启动扩展”，待Python服务器进入等待状态后，启动“附加到Python语言服务器”即可完成跨进程调试关联。

3. 确认pygls回调函数注册正确性 #

验证你的completions函数注册是否符合pygls规范，避免因函数名或注解错误导致断点未触发：

from pygls.lsp import COMPLETION, CompletionParams, CompletionList, CompletionItem
from pygls.server import LanguageServer

ls = LanguageServer()

@ls.feature(COMPLETION)
def completions(params: CompletionParams):
    # 在此处设置断点
    return CompletionList(
        is_incomplete=False,
        items=[CompletionItem(label="sample-item")]
    )

if __name__ == "__main__":
    ls.start_io()

确保使用@ls.feature(COMPLETION)注解，而非教程中可能存在的旧版completion名称。

4. 排查进程通信与启动问题 #

• 用VSCode进程管理器（Ctrl+Shift+P → 显示进程）确认Python语言服务器进程是否正常启动，记录PID可辅助调试。
• 检查扩展package.json和extension.js中的服务器启动命令，确保未使用detached模式（该模式会让Python进程脱离Node进程的调试上下文）：

  const cp = require('child_process');
  // 正确启动方式：不添加detached选项
  const serverProcess = cp.spawn('python', ['./json_server.py']);
  

5. 用pygls日志定位请求流转 #

替换print语句为pygls自带的日志功能，可更精准判断completions函数是否被调用：

import logging
logging.basicConfig(filename='pygls_debug.log', level=logging.DEBUG)

查看日志文件，确认VSCode的补全请求是否正常传递到服务器，以及函数是否进入执行流程。

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