README.md

py-breakpoint-debugger

Python Breakpoint Debugger — VSCode 一键附加 debugpy 调试插件

一、插件介绍

一款配合 debug_hook.py 使用的 VSCode 调试辅助插件，解决手动写 attach 配置、手动输端口调试的繁琐流程。 核心能力：

1. 内置 HTTP 服务监听 Python 进程上报；
2. 侧边栏树形列表自动展示所有触发 breakpoint() 的 Python 进程；
3. 单击进程自动生成 pathMappings 附加调试；
4. 支持 Python 侧自定义多组路径映射，兼容本地子目录、容器、盘符映射场景；
5. 附加成功后自动清理侧边栏进程条目。

前置依赖

1. VSCode 官方扩展：Python、Python Debugger(ms-python.debugpy)；
2. Python 环境安装依赖：

pip install debugpy requests

二、配套工具：debug_hook.py

将此文件放入你的项目根目录，业务代码直接导入使用。 完整源码：

import sys
import debugpy
import os
import requests
from typing import Optional, List, Dict

PathMapping = Dict[str, str]

class DebugHook:
    PLUGIN_URL = "http://127.0.0.1:10086/report-debug"
    _initialized = False
    _port = 0

    def __init__(self):
        # 默认不启用自定义映射
        self.custom_path_mappings: Optional[List[PathMapping]] = None

    def set_path_mappings(self, mappings: Optional[List[PathMapping]]):
        """
        外部动态设置路径映射
        :param mappings: 映射数组，None=使用插件默认映射
        """
        self.custom_path_mappings = mappings

    def _get_debug_port(self) -> int:
        base = 5678
        pid = os.getpid()
        return base + (pid % 1000)

    def hijack_breakpoint(self):
        if self._initialized:
            debugpy.wait_for_client()
            debugpy.breakpoint()
            return

        # 首次初始化
        port = self._get_debug_port()
        self._port = port
        debugpy.listen(("127.0.0.1", port))
        pid = os.getpid()
        abs_file = os.path.abspath(sys.argv[0])

        post_data = {
            "pid": pid,
            "port": port,
            "filePath": abs_file
        }
        # 携带自定义映射数组
        if self.custom_path_mappings is not None:
            post_data["customPathMappings"] = self.custom_path_mappings

        # 上报插件
        try:
            requests.post(self.PLUGIN_URL, json=post_data, timeout=0.2)
            print(f"[WAITING_VSCODE_DEBUG_ATTACH] pid={pid},port={port},file={abs_file}", flush=True)
        except Exception:
            pass

        self._initialized = True
        # 阻塞等待附加 + 触发断点
        debugpy.wait_for_client()
        debugpy.breakpoint()

# 全局单例，方便项目全局复用
debug_hook = DebugHook()
# 全局劫持系统 breakpoint()
sys.breakpointhook = debug_hook.hijack_breakpoint

三、Python 代码使用教程

1. 基础用法（默认路径映射）

无需自定义路径映射，直接导入即可，使用插件默认映射 local="${workspaceFolder}" remote="${workspaceFolder}"

from debug_hook import debug_hook

print("测试默认映射")
breakpoint()
print("断点放行后执行")

2. 自定义单组路径映射

localRoot 支持两种写法：变量 ${workspaceFolder} 或硬盘绝对物理路径，二选一即可。

写法A：使用 ${workspaceFolder} 变量（推荐，多项目通用）

from debug_hook import debug_hook

debug_hook.set_path_mappings([
    {
        "localRoot": "${workspaceFolder}/service",
        "remoteRoot": "D:/code/project/service"
    }
])

breakpoint()

写法B：直接写死本地绝对路径（固定本机目录专用，无需依赖工作区）

不需要 ${workspaceFolder}，直接填写完整磁盘路径，适合本机固定项目调试：

from debug_hook import debug_hook

# localRoot 写完整绝对路径，不使用任何内置变量
debug_hook.set_path_mappings([
    {
        "localRoot": "D:/code/project/service",
        "remoteRoot": "D:/code/project/service"
    }
])

breakpoint()

Windows 路径注意：统一使用正斜杠 /；不要用单反斜杠 \，会被识别为转义字符。

3. 多组路径映射（容器/多模块项目）

同时兼容多个不同目录源码，混合「变量路径」「绝对物理路径」都支持：

from debug_hook import debug_hook

debug_hook.set_path_mappings([
    # 子目录变量写法
    {
        "localRoot": "${workspaceFolder}/service",
        "remoteRoot": "D:/code/project/service"
    },
    # 纯绝对路径写法
    {
        "localRoot": "D:/code/project/core",
        "remoteRoot": "D:/code/project/core"
    }
])

breakpoint()

4. 恢复默认映射

from debug_hook import debug_hook

# 传入 None 关闭自定义映射，使用插件内置默认规则
debug_hook.set_path_mappings(None)

breakpoint()

关键特性说明

1. 全局劫持 sys.breakpointhook，项目中所有原生 breakpoint() 都会自动接管；
2. 进程仅在第一次执行 breakpoint() 时上报端口信息，后续重复调用只阻塞等待调试器；
3. 端口由 PID 哈希生成，多进程/多脚本不会端口冲突；
4. 若 VSCode 插件未启动，HTTP 上报静默失败，不阻塞业务代码运行；
5. localRoot 无强制要求必须使用 ${workspaceFolder}，完整绝对磁盘路径完全合法，两种写法适配器都会正常识别。

四、VSCode 插件使用教程

1. 安装插件

1. 打包插件：npm run package 生成 .vsix 文件；
2. VSCode 扩展面板 → 从 VSIX 安装，选中生成文件；
3. 重启 VSCode，插件随编辑器自动启动。

2. 插件界面说明

1. 左侧活动栏新增「Python Break Debug」图标，点击打开侧边栏；
2. 列表自动展示所有已上报的 Python 调试进程；
3. 列表顶部导航按钮：
   • 清空按钮：一键清空全部进程列表；
4. 进程条目悬浮提示：
   • 展示 PID、端口、脚本完整路径；
   • 区分「默认映射」/「自定义路径映射」详情；
5. 右键/单击进程条目：一键附加调试。

3. 完整调试流程

1. VSCode 打开项目文件夹作为工作区；
2. 项目内放入 debug_hook.py；
3. 编写业务代码并写入 breakpoint()；
4. 运行 Python 脚本，代码走到断点会自动上报进程信息；
5. 侧边栏出现对应进程条目；
6. 点击条目自动生成 attach 配置并启动调试；
7. 调试附加成功后，该进程自动从列表移除；
8. 在调试面板点击「继续」即可放行断点。

五、端口与通信说明

1. 插件本地监听：http://127.0.0.1:10086；
2. 上报接口：POST /report-debug；
3. 查询进程列表接口：GET /list；
4. 请勿占用本机 10086 端口，否则插件无法接收进程上报。

六、常见问题

1. 侧边栏看不到 Python 进程

   • 确认 VSCode 插件已启用；
   • 确认本机 10086 端口未被其他程序占用；
   • 确认 Python 已安装 requests、debugpy；
   • 先打开插件侧边栏，再运行 Python 脚本。

2. 断点命中打开只读临时文件，无法编辑本地源码

   • Python 侧配置正确的 customPathMappings；
   • VSCode 打开对应项目根目录作为工作区；
   • 路径分隔符统一使用 /，避免 Windows 反斜杠转义问题；
   • 若使用绝对路径，保证 localRoot 磁盘目录真实存在。

3. 多进程调试冲突 工具基于 PID 生成独立端口，多进程互不干扰，侧边栏会区分多条进程条目。

七、开源信息

插件名称：py-breakpoint-debugger 作者：yuntong.li 功能：自动捕获 breakpoint() 进程，一键 attach debugpy 调试，支持自定义路径映射，localRoot 同时支持 ${workspaceFolder} 变量与绝对物理路径两种格式。