调试工作虽然看似复杂，但只要掌握了底层逻辑，本质上就是几个连续的操作步骤。首先确保项目处于Debug模式并携带调试符号进行编译，接着设置断点，启动调试会话后逐步执行，最后配合结构化日志输出，基本上就能覆盖绝大部分复杂场景下的问题定位与排查需求。
如果在Qoder开发过程中发现程序行为异常，比如变量值与预期不符，或者某个逻辑分支始终未能进入，那么很可能是调试功能未正确启用，或者排查路径本身不够清晰。下面就来系统梳理一下，如何使用Qoder进行断点调试与错误排查的完整操作流程。
一、启用Qoder项目Debug构建并加载调试符号
Qoder默认以Release模式运行，该模式下调试信息和符号表会被剥离。带来的后果是：设置的断点无法命中，变量值也无法查看。必须切换到Debug构建配置，并确保编译器已将完整的调试符号（如DWARF或PDB）嵌入生成文件，这样才能为源码级单步追踪和内存状态检查奠定基础。
1、在Qoder IDE左侧项目导航栏中，右键点击项目名称，选择【Properties】。
2、进入【Build Settings】→【Configuration】，将Active build configuration切换为Debug。
3、在【Compiler Flags】中，确认已启用-g参数（Linux/macOS）或/Zi（Windows），同时关闭-O2及以上的优化等级。
4、点击【Apply】后，执行Clean & Rebuild，确保生成的可执行文件包含完整的调试元数据。
二、在Qoder IDE中设置与管理断点
断点是让程序暂停、观察上下文状态的核心控制手段。Qoder IDE支持行断点、条件断点以及函数入口断点。但需要牢记：所有这些断点只有在Debug构建下才能被识别和触发。
1、在源码编辑区左侧的灰色标记栏中，点击目标代码行号旁边的空白处，出现红色实心圆即表示断点已添加。
2、右键点击该断点，选择【Edit Breakpoint】，输入表达式，例如i > 100 && result.isEmpty()，这样断点仅在条件满足时才会触发。
3、在函数声明行（如void processData()）上右键，选择【Break at Function Entry】，系统将自动在函数第一条可执行语句处插入断点。
4、通过【Breakpoints】侧边栏，可以查看所有断点列表。勾选或取消勾选，即可动态启用或禁用某个断点，无需重新编译。
三、启动调试会话并执行单步控制
Qoder的调试器基于LLDB/GDB封装，支持全速运行、暂停、单步进入、跳过、退出等标准控制流操作。所有动作都会实时同步到调试视图和变量监视窗口中。
1、确保至少有一个断点处于启用状态，然后点击工具栏的虫子图标（Debug），或按快捷键F5，启动调试会话。
2、程序运行到第一个断点时自动暂停。此时【Locals】窗口会显示当前作用域内的所有变量及其值，并支持双击修改数值，用于验证逻辑分支。
3、按F11执行单步进入（Step Into），进入当前行所调用的函数内部；按F10执行单步跳过（Step Over），跳过函数体直接执行下一行。
4、当光标停在函数内部时，按Shift+F11执行单步退出（Step Out），快速返回上层调用位置，避免逐行跳出。
四、利用Qoder结构化日志辅助断点定位
纯断点调试存在局限性，例如在异步回调、多线程竞争或远程服务响应等场景中，仅靠断点可能力不从心。Qoder提供了一种与调试器联动的日志注入机制，可在断点触发时自动打印结构化的上下文字段，实现代码行与日志段之间的双向锚定。
1、在断点所在的函数开头，插入qCDebug(log_category) << "ENTER" << "trace_id:" << currentTraceId();，其中的log_category需要提前注册。
2、在Qoder IDE底部的【Application Output】面板中，右键点击某条日志行，选择【Jump to Source】，即可自动定位到对应的qCDebug调用位置。
3、启用【Log + Breakpoint Sync】选项后，每次断点命中，系统会自动高亮同一个trace_id的最近三条日志，相当于形成执行路径的快照。
4、对于疑似异常的代码分支，可添加qCDebug(log_category).noquote() << "STATE:" << QString::fromUtf8(QJsonDocument(stateObj).toJson());，输出JSON序列化后的状态对象，便于离线时仔细比对。
五、排查常见断点失效与调试器挂起问题
断点未触发、调试器无响应，或者变量显示
1、在终端执行qoder debug --check-symbols path/to/binary，确认输出中包含DWARF version: 4，且没有missing symbols警告。
2、检查Qoder IDE的设置，【Debugger】→【GDB/LLDB】路径是否指向本地安装的匹配版本。例如macOS需要lldb-1500.0.40.6，Linux需要gdb 12.1+。
3、如果调试器长时间无响应，打开【Processes】视图，找到名为qoder-debugger-agent的进程，对其执行kill -SIGUSR2，这将触发内部状态转储，输出到/tmp/qoder-debug-dump.log。
4、关闭所有Qoder CLI实例和devcontainer沙箱，清除~/.qoder/debug-cache目录，然后重启IDE，排除调试元数据缓存被污染的可能性。