嵌入式调试技巧

January 19, 2026 · 6 min read

Eureka X

Mr.Nobody

本文记录我在嵌入式开发中逐步完善的调试日志实践，核心是通过条件编译与宏封装，在保留诊断能力的同时实现零运行时开销。

条件编译与调试

在嵌入式开发中，调试信息是排查问题的重要眼睛。但当项目进入稳定阶段或准备发布时，这些 printf 或 UsartPrintf 日志又成了负担：它们占用串口带宽、消耗 CPU、甚至泄露内部逻辑。

于是很多初学者（包括曾经的我）会做两件事：

直接删除所有调试语句；
或者逐行注释掉，留着“以后可能用”。

但随着项目变大、问题变复杂，这两种做法都暴露出严重缺陷。本文将分享一种更专业的做法——基于条件编译的模块化日志宏封装，并解释它为何是嵌入式工程的最佳实践。

删除 or 注释？

❌ 删除调试代码的问题：

不可逆：下次遇到类似问题，要重写相同的诊断逻辑；
浪费时间：本人曾为一个 JSON 逗号错误调试半天，如果删掉日志，下次可能还会踩同样的坑；
降低系统可观测性：嵌入式系统往往难以复现问题，没有日志等于“盲人摸象”。

❌ 注释掉调试代码的问题：

污染源码：满屏的 // printf(...) 让代码难以阅读；
版本混乱：Git diff 中充斥着日志开关的变动，干扰真正逻辑修改；
无法批量控制：想临时开启某模块日志？得手动取消几十行注释。

本质上，这两种做法都把“调试能力”当作垃圾处理了。

用条件编译包裹日志

真正的工程思维是：调试代码不是累赘，而是可开关的资产。

#ifdef ONENET_DEBUG
    UsartPrintf(USART_DEBUG, "Payload: %s\r\n", payload);
#endif

定义宏 ONENET_DEBUG

debug_config.h
// ==== 模块调试开关（调试时去掉对应注释） ====
// #define ONENET_DEBUG
// #define WIFI_DEBUG
// #define SENSOR_DEBUG

开启时：日志输出，能够快速定位问题；
关闭时：预处理器直接移除整段代码，零 Flash 占用、零 RAM 消耗、零 CPU 开销。这已经比删除/注释好太多。但还不够优雅。

当某行被注释（如 // #define ONENET_DEBUG），ONENET_DEBUG 未定义，相关日志代码会被预处理器移除；

当取消注释（#define ONENET_DEBUG），宏即被定义（无论是否有值），#ifdef ONENET_DEBUG 条件成立，日志生效。

宏封装

我们进一步封装成模块专属的日志宏：

debug_config.h
#ifdef ONENET_DEBUG
  #define ONENET_LOG(fmt, ...) \
      UsartPrintf(USART_DEBUG, "[ONENET] " fmt "\r\n", ##__VA_ARGS__)
#else
  #define ONENET_LOG(fmt, ...)
#endif

封装解释

🌰 举个例子

假设代码中写了：

ONENET_LOG("Payload len: %d", body_len);

情况 1️⃣：#define ONENET_DEBUG 已启用

预处理器会把它替换成：

UsartPrintf(USART_DEBUG, "[ONENET] " "Payload len: %d" "\r\n", body_len);

→ C 语言会自动拼接相邻字符串字面量，实际等价于：

UsartPrintf(USART_DEBUG, "[ONENET] Payload len: %d\r\n", body_len);

✅ 结果：正常打印日志

情况 2️⃣：#define ONENET_DEBUG 被注释（未定义）

此时使用 #else 分支：

#define ONENET_LOG(fmt, ...)

这表示：任何 ONENET_LOG(...) 调用都会被替换为空。 所以：

ONENET_LOG("Payload len: %d", body_len);

在编译前就完全消失（连空语句都没有）。

✅ 结果：零 Flash 占用、零 RAM、零 CPU 开销！

💡 为什么要用 `...` 和 `##__VA_ARGS__`？

...：表示这个宏可以接收任意数量的额外参数（类似 printf）；
__VA_ARGS__：代表那些额外参数；
##__VA_ARGS__：是 GCC 的扩展语法，当没有额外参数时，自动删除前面的逗号，避免语法错误。例如：

ONENET_LOG("Hello");  // 没有额外参数

若用 __VA_ARGS__ → 展开为 UsartPrintf(..., "Hello", ) → ❌ 多出逗号，编译失败；
用 ##__VA_ARGS__ → 展开为 UsartPrintf(..., "Hello") → ✅ 正确。

虽然通常会传参数，但保留 ## 是更健壮的做法。

使用时只需一行：

ONENET_LOG("Sent %d bytes, payload: %s", len, json);

✨ 这种封装的五大优势：

1. 接口统一，调用简洁

无需写 #ifdef，也无需重复写前缀和换行符。代码专注业务，日志只是“一句话”。

2. 自动带模块标识 [ONENET] 前缀让你一眼知道日志来源，尤其在多模块混合输出时至关重要。

3. 完全零开销

当 ONENET_DEBUG 未定义时，ONENET_LOG(...) 被替换为空，编译后不存在任何痕迹。

4. 支持可变参数

借助 ... 和 ##__VA_ARGS__，像 printf 一样灵活，且兼容空参调用。

5. 集中管理，按需开启

所有调试开关集中在 debug_config.h：

// #define WIFI_DEBUG
#define ONENET_DEBUG   // 只开 OneNET 日志
// #define SENSOR_DEBUG

调试 Wi-Fi 时关掉传感器日志，避免刷屏；查通信问题时只看 [ONENET]，效率翻倍。

工业级标准

AUTOSAR、MISRA 等规范明确推荐使用宏控制调试输出；
Linux 内核、Zephyr、FreeRTOS 等开源项目广泛采用类似机制；
汽车、IoT、工业控制等量产项目依赖这种“可关闭但可恢复”的诊断能力。

专业团队不追求“没有日志的干净代码”，而是追求“需要时能立刻看到关键信息”的系统韧性。

建议

如果你还在：

调试完就删日志，
或用 // 注释掉几百行 printf，

请尝试以下三步：

创建 debug_config.h，定义模块开关；
为每个模块写一个 XXX_LOG 宏；
用 XXX_LOG(...) 替换所有调试打印。

你会发现：

调试更快了，
代码更干净了，
发布更安心了。

结语

调试日志不是代码的“临时补丁”，而是系统的“诊断接口”。
用条件编译和宏封装，我们既能享受调试的便利，又不影响产品的性能与安全。

好的嵌入式工程师，不是不写日志，而是让日志“召之即来，挥之即去”。

本文源于一次真实的调试困境：一个 JSON 逗号引发的通信失败。
正是那次经历，让我意识到——保留调试能力，就是保留解决问题的能力。

后记
本文源于一次真实的通信故障排查，后续通过与 AI 工具多轮探讨，逐步厘清了调试日志的设计原则。
虽然部分内容由对话启发，但所有代码、逻辑和结论均经过我在实际项目中的验证与调整。
写下它，不仅是为了分享，更是为了记住：解决问题的能力，值得被保留下来。

加载评论中...

条件编译与调试​

删除 or 注释？​

❌ 删除调试代码的问题：​

❌ 注释掉调试代码的问题：​

用条件编译包裹日志​

宏封装​

🌰 举个例子​

✅ 结果：正常打印日志​

✅ 结果：零 Flash 占用、零 RAM、零 CPU 开销！​

💡 为什么要用 ... 和 ##__VA_ARGS__？​

✨ 这种封装的五大优势：​

工业级标准​

建议​

结语​