Cortex-Debug 1.12.1 无法识别 pyOCD 0.44.1 启动日志的修复

创天蓝

Cortex-Debug 1.12.1 无法识别 pyOCD 0.44.1 启动日志的修复

在 Air001 项目中，Cortex-Debug 已经启动 pyOCD，终端也显示 GDB server 正在监听端口，VS Code 仍在等待，最后报错：

1. Failed to launch PyOCD GDB Server: Timeout.

复制代码

这次现场使用的是 pyOCD。OpenOCD 是另一个 GDB server，两者不能混用名称。报错文字和 servertype: "pyocd" 都能确认实际对象。

修复只需覆盖 Cortex-Debug 用来判断 server 已就绪的正则表达式：

1. "overrideGDBServerStartedRegex": "GDB server listening on port"

复制代码

故障现象

环境为 Cortex-Debug 1.12.1、pyOCD 0.44.1 和 Air001。执行 F5 后，pyOCD 输出：

1. GDB server listening on port 3333 (core 0)

复制代码

这行日志说明 pyOCD 已经运行，3333 端口也已进入监听状态。此时出现 Timeout，排查重点应放在 Cortex-Debug 的“就绪判断”，无需继续折腾探针驱动或增加等待时间。

启动日志与内置正则

Cortex-Debug 启动 GDB server 后，会等待一行符合内置正则的日志。1.12.1 中 pyOCD 的内置正则是：

1. GDB server started (at|on) port

复制代码

pyOCD 0.44.1 的实际文字是：

1. GDB server listening on port

复制代码

started at/on 与 listening on 无法匹配。进程虽然已经启动，Cortex-Debug 收不到“已就绪”信号，只能一直等待到超时。

最小修复配置

下面是可以直接放进 .vscode/launch.json 的最小示例：

1. {
   
2.   "version": "0.2.0",
   
3.   "configurations": [​
   
4.     {
   
5.       "name": "Air001: Cortex-Debug with pyOCD",
   
6.       "type": "cortex-debug",
   
7.       "request": "launch",
   
8.       "cwd": "${workspaceFolder}",
   
9.       "executable": "${workspaceFolder}/build/Project.elf",
   
10.       "servertype": "pyocd",
    
11.       "targetId": "Air001",
    
12. 
    
13.       // 本次修复的核心配置
    
14.       "overrideGDBServerStartedRegex": "GDB server listening on port",
    
15. 
    
16.       "runToEntryPoint": "main"
    
17.     }
    
18.   ​]
    
19. }

复制代码

如果 pyocd 没有加入 PATH，可再通过 Cortex-Debug 的 serverpath 或全局 cortex-debug.pyocdPath 指定可执行文件。路径配置与本次超时根因属于两件事。

修复生效机制

overrideGDBServerStartedRegex 不负责启动 pyOCD，也不会修改 GDB 端口。它只替换 Cortex-Debug 的就绪匹配规则。

修改前的流程停在第二步：

1. 启动 pyOCD → 等待旧日志文字 → 超时

复制代码

修改后的流程能够继续：

1. 启动 pyOCD → 匹配 listening on port → GDB 连接 3333 端口

复制代码

因此，这项修复不依赖 PowerShell、后台进程或固定时长的 sleep。pyOCD 真正启动失败时不会输出匹配文字，Cortex-Debug 仍会正常报错。

验证结果与适用边界

加入覆盖正则后，Cortex-Debug 能越过 GDB server 启动阶段，不再报告 Failed to launch PyOCD GDB Server: Timeout。

这项修复只解决 Cortex-Debug 1.12.1 与 pyOCD 0.44.1 的启动日志不兼容。项目最终按调试需求采用 VS Code C/C++ 扩展的 cppdbg，入口断点和 GDB 启动时序记录在另一篇文章中。

如果日志明确写的是 OpenOCD，应先查看 OpenOCD 的实际启动文字，再为 overrideGDBServerStartedRegex 编写对应规则。不要直接复制本文的 pyOCD 正则。

---

build 28 July 2026 14:10 (UTC+8)