1. 从一次真实的调试经历说起

那天下午，我正在调试一块新画的STM32F103板子，核心任务是通过串口把几个传感器的中文名称和读数发到上位机显示。用STM32CubeMX配置好USART，在Keil里写好printf重定向，编译下载一气呵成。满心期待地打开串口助手，结果屏幕上蹦出来的不是“温度传感器”，而是一堆像“娓╁害浼犳劅鍣?”这样的乱码。相信这个场景，很多从单片机转向32位开发的朋友都遇到过，尤其是第一次尝试输出中文的时候。你可能会怀疑是串口助手的设置问题，换了好几个软件；或者觉得是printf函数重写得不对，反复检查代码；甚至开始质疑芯片是不是坏了。折腾半天，最后发现，问题往往出在一个最基础、但又最容易被忽略的环节——编码。

串口通信本身只是传输原始的字节流，它并不关心你传的是字母“A”还是汉字“中”。乱码的本质，是通信链条上各个环节对同一串字节流的“解读”方式不一致。你的单片机程序、编译器、串口助手，甚至操作系统，都可能使用不同的字符编码。当发送方的“书写规则”和接收方的“阅读规则”对不上时，乱码就产生了。而中文，由于一个字符通常由多个字节表示，在这种编码错位中尤其脆弱。

所以，这篇文章我们就来彻底厘清STM32串口通信中中文乱码的来龙去脉。这不仅仅是解决一个printf的问题，更是理解嵌入式系统中数据表示与传输的基础。我们将从CubeMX的配置开始，深入到编译器设置、代码编写、上位机调试的全链路，手把手带你搭建一个能稳定、正确显示中文的串口通信框架。

2. 乱码的根源：编码标准的三国演义

要解决问题，必须先理解问题。中文乱码的核心矛盾，是发送端、传输过程、接收端三方所使用的字符编码标准不统一。在嵌入式领域，我们主要会碰到以下三位“主角”：

2.1 主角一：ASCII码与扩展ASCII码

这是计算机世界的“元老”。标准ASCII码用7位（后来扩展为8位）表示128个字符，包括英文字母、数字、标点和一些控制字符。它很简单，一个字节对应一个字符，但最大的问题是无法表示中文。早期的单片机调试信息全是英文，就是因为大家默认使用ASCII码。如果你尝试直接把一个汉字的GB2312编码（两个字节）当作两个独立的ASCII字符发送，接收端用ASCII解码，自然会得到两个毫无意义的符号，这就是乱码的起点。

2.2 主角二：GB2312/GBK/GB18030

这是中文Windows系统的“本地霸主”。为了在计算机中表示中文，我国制定了GB2312标准，用两个字节表示一个汉字。后来的GBK、GB18030在其基础上扩展，兼容了更多字符。当你用Windows的记事本默认保存一个.txt文件时，它使用的就是ANSI编码，在中文环境下就是GBK。许多国产的串口助手软件，其默认解码方式也是GBK。如果你的单片机程序发送的是GBK编码的中文字节，而串口助手也设置为GBK解码，那么就能正确显示。

2.3 主角三：UTF-8

这是当今互联网和跨平台开发的“世界语”。UTF-8是Unicode字符集的一种可变长度编码方式。它的一个巨大优点是兼容ASCII码，对于ASCII字符（0-127），它用单个字节表示，和ASCII码完全一样。对于中文等非ASCII字符，则用2到4个字节表示。Linux系统、现代代码编辑器（如VSCode）、以及许多跨平台软件，都默认使用UTF-8。Keil MDK和STM32CubeIDE的默认编码设置，也与操作系统或工程设置有关，不一定就是GBK。

乱码产生的典型场景分析：

1. 源代码文件编码是UTF-8，编译器按GBK解析：你在UTF-8编码的.c文件中写了字符串"你好"，其UTF-8编码是0xE4 0xBD 0xA0 0xE5 0xA5 0xBD（6个字节）。如果编译器错误地将其当作GBK编码来解析，它会尝试将每两个字节组合成一个汉字，比如把0xE4 0xBD组合，这个组合在GBK字库里可能对应一个生僻字，最终编译进单片机的就是错误的字节序列。
2. 程序发送UTF-8，串口助手用GBK解码：即使编译器正确地将UTF-8编码的字符串编译进了程序，单片机也原样发送了这6个字节。但如果你的串口助手（如运行在Windows上的某助手）默认解码方式是GBK，它就会试图用GBK规则去解读这6个字节，从而显示为乱码。
3. 程序发送GBK，串口助手用UTF-8解码：反之亦然。

所以，解决乱码的关键，就是让整个链条统一编码。对于STM32嵌入式开发，我们通常有两种策略：让单片机程序发送GBK编码，以兼容大多数中文Windows环境下的串口助手；或者让整个开发环境统一到UTF-8，并使用支持UTF-8解码的串口工具。

3. STM32CubeMX配置：打好通信的物理基础

在纠结编码之前，首先要确保硬件通信是正常的。STM32CubeMX的配置是这一切的起点。

3.1 USART外设的基本配置

打开CubeMX，为你的USART（比如USART1）进行如下配置，这些是保证字节能正确传输的基石：

• Mode: 选择Asynchronous（异步通信）。这是最常用的模式。
• Baud Rate: 波特率。常用115200。发送端和接收端必须严格一致，这是乱码的第一个排查点。波特率偏差太大会导致数据错位，所有字符都会乱。
• Word Length: 字长。选择8 Bits。一个字节就是8位，这是字符数据传输的标准。
• Parity: 奇偶校验。选择None。在稳定性要求不高的调试场景可以不用，简化配置。
• Stop Bits: 停止位。选择1。
• Over Sampling: 过采样。保持默认16即可。

注意：波特率115200意味着每秒传输115200个比特（bit）。由于我们通常传输的是8个数据位+1个起始位+1个停止位=10位，所以实际每秒传输的字符数约为11520个。这个速度对于调试信息输出绰绰有余。

3.2 关键一步：开启串口中断和重定向printf

为了让printf函数能通过串口输出，我们需要做两件事：

1. 在CubeMX中使能中断：在NVIC Settings标签页，找到对应的USART全局中断，勾选使能。这是为了使用HAL库的HAL_UART_Transmit函数（它可能依赖中断），更重要的是为后续使用printf重定向到_write系统调用做准备。
2. 生成代码后重定向printf：这是核心操作。CubeMX生成代码后，在IDE（如Keil）中，我们需要覆盖一个底层函数，将标准库的输出指向串口。
   • 找到Src文件夹下的syscalls.c文件（如果没有，可以在工程选项中勾选“Use MicroLIB”微库，或者自己创建这个文件）。
   • 在其中重写_write函数。这个函数是底层IO的系统调用，printf最终会调用它。

// 示例：重定向printf到USART1 #include <stdio.h> #include “stm32f1xx_hal.h” // 根据你的芯片系列修改头文件 extern UART_HandleTypeDef huart1; // 声明在main.c中定义的串口句柄 // 重写_write函数 int _write(int file, char *ptr, int len) { // 参数file是文件描述符，这里我们忽略它，将所有输出指向串口 // ptr是指向要发送数据的指针，len是数据长度 HAL_UART_Transmit(&huart1, (uint8_t*)ptr, len, HAL_MAX_DELAY); return len; // 返回成功发送的字节数 }

为什么是_write而不是fputc？很多教程会教你重写fputc。对于Keil的ARM编译器，重写fputc确实可以工作，因为它链接的C库可能简化了IO。但更通用、更底层的方法是重写_write。printf系列函数在底层会调用write系统调用来执行实际的输出操作。重写_write确保了无论使用标准库的完整版还是微库（MicroLIB），都能正确捕获输出流，兼容性更好。特别是在使用CubeMX生成的代码框架和HAL库时，这种方法更可靠。

配置好这些，你应该已经能用printf(“Hello World\r\n”);在串口助手上看到英文了。如果英文都显示乱码，请立即检查波特率设置、硬件连线（TX/RX是否接反）、以及串口助手的参数是否与CubeMX配置完全一致。

4. 征服中文乱码：两种实战策略与代码实现

当英文输出正常后，我们就可以集中火力解决中文问题了。下面提供两种最常用、最彻底的解决方案。

4.1 策略一：源代码使用GBK编码，让单片机发送GBK字节流

这是最直接的方法，目标是让单片机发送的字节流，与中文Windows环境下的串口助手默认解码方式匹配。

操作步骤：

1. 转换IDE工程编码为GBK（以Keil MDK为例）：

   • 在Keil中，点击Edit -> Configuration。
   • 切换到Editor标签页。
   • 在Encoding区域，选择Chinese GB2312(Simplified)或GBK。注意：这一步是改变Keil编辑器打开和保存文件时使用的编码，并不改变已有文件的编码。
   • 更关键的一步：你需要将已有的源文件（尤其是包含中文字符串的.c和.h文件）另存为GBK编码。可以用记事本打开文件，点击“文件->另存为”，在保存对话框底部选择“编码”为“ANSI”（在中文Windows即GBK），然后覆盖原文件，或在Keil中删除旧文件后重新添加。

2. 在代码中直接使用GBK编码的字符串： 确保你的源代码文件是GBK编码后，你就可以直接写中文了。

   printf(“当前温度：25℃\r\n”); printf(“系统启动完成…\r\n”);

   编译器会将这些中文字符按照文件保存的编码（GBK）转换成对应的双字节机器码，并存入程序的常量字符串区。单片机执行printf时，就会将这些GBK字节原样发送出去。

3. 设置串口助手为GBK解码： 打开你常用的串口助手（如SSCOM、XCOM等），在显示区域通常有一个“编码”或“字符编码”设置选项，将其设置为“GBK”或“GB2312”。

这种方法的优缺点：

• 优点：简单直接，无需额外代码转换，与多数国产串口助手兼容性好。
• 缺点：
  • 跨平台性差：如果你的团队有人在Linux或macOS下开发，或者使用VSCode等默认UTF-8的编辑器，打开GBK编码的文件会显示乱码。
  • 工程管理混乱：工程中部分文件是GBK，部分文件是UTF-8（比如从GitHub下载的库文件），容易引发难以察觉的编码错误。
  • 微库（MicroLIB）的潜在问题：在某些情况下，Keil的MicroLIB对宽字符（多字节字符）支持不完善，可能导致GBK字符串处理异常。如果遇到问题，可以尝试切换回标准C库。

4.2 策略二：统一使用UTF-8编码，并在代码中灵活处理

这是更现代、更推荐的做法，尤其适合团队协作和跨平台开发。思路是：源代码、编译器、串口助手全部统一使用UTF-8。

操作步骤：

1. 确保源代码为UTF-8编码：

   • 在Keil的Edit -> Configuration -> Editor中，将编码设置为UTF-8。
   • 同样，将你的源文件另存为“UTF-8”编码（注意：不要带BOM的UTF-8。BOM是文件头部的几个特殊字节，某些嵌入式编译器可能无法识别，导致编译错误）。Windows记事本保存时选择“UTF-8”即可，它默认保存为带BOM的UTF-8，这可能有问题。建议使用Notepad++、VSCode等专业编辑器，明确选择“UTF-8无BOM”格式保存。

2. 代码中字符串即为UTF-8： 此时，代码中的中文字符串在内存中就是以UTF-8格式存储的。直接printf发送的就是UTF-8字节流。

3. 使用支持UTF-8的串口助手： 这是关键。许多老牌串口助手默认不支持UTF-8。你需要选择一款明确支持UTF-8解码的。例如：

   • Putty：经典选择，在连接设置中可将“接收到的数据假定为”设置为“UTF-8”。
   • MobaXterm：功能强大的终端，完美支持UTF-8。
   • SecureCRT：商业软件，支持良好。
   • 一些新版国产串口助手也加入了UTF-8支持选项，请仔细查看设置。

但是，这里有一个巨大的“坑”：你无法控制所有使用你设备的人都会用UTF-8解码的终端。为了最大程度的兼容性，一个更高级的做法是：让单片机程序具备编码转换能力，即内部处理使用UTF-8，但输出时可以按需选择发送GBK或UTF-8。

这就需要我们实现一个轻量级的UTF-8转GBK函数。由于STM32资源有限，我们不可能携带完整的码表。一个实用的方法是，只为程序中实际用到的中文字符提供转换。

实战：实现一个迷你UTF-8转GBK查表函数

1. 提取所需字符的编码对： 首先，统计你程序中所有需要用到的中文字符。然后，通过在线工具或编程方式，获取每个字符的UTF-8编码和GBK编码。 例如：“温”字。

   • UTF-8编码：E6 B8 A9(3字节)
   • GBK编码：CE C2(2字节)

2. 创建转换对照表： 在代码中创建一个结构体数组，作为查找表。

   typedef struct { const char *utf8; // UTF-8编码序列，以‘\0‘结尾 const char *gbk; // 对应的GBK编码序列 } CharMap_t; // 示例：为“温度传感器”五个字创建映射表 static const CharMap_t g_chinese_map[] = { {“\xE6\xB8\xA9”, “\xCE\xC2”}, // 温 {“\xE5\xBA\xA6”, “\xB6\xC8”}, // 度 {“\xE4\xBC\xA0”, “\xB4\xAB”}, // 传 {“\xE6\x84\x9F”, “\xB8\xD0”}, // 感 {“\xE5\x99\xA8”, “\xC6\xF7”}, // 器 // … 添加更多字符 {NULL, NULL} // 结束标志 };

   注意：这里用\x后跟十六进制数表示字节，是为了避免编辑器编码影响。这些字节值就是该字符在对应编码下的二进制表示。

3. 实现转换函数： 编写一个函数，遍历输入字符串，对于每个字符，在查找表中查找其UTF-8序列，如果找到，则输出对应的GBK序列；如果没找到（可能是英文字符或未收录的中文字符），则原样输出。

   void print_gbk(const char *utf8_str) { const char *p = utf8_str; while (*p) { int matched = 0; // 遍历查找表，这里实现一个简单的查找 // 注意：实际实现需要能处理变长的UTF-8序列，本例简化了查找逻辑 for (int i = 0; g_chinese_map[i].utf8 != NULL; i++) { const char *u = g_chinese_map[i].utf8; const char *g = g_chinese_map[i].gbk; // 假设我们的表里都是3字节UTF-8对应2字节GBK if (p[0] == u[0] && p[1] == u[1] && p[2] == u[2]) { HAL_UART_Transmit(&huart1, (uint8_t*)g, 2, HAL_MAX_DELAY); // 发送GBK编码 p += 3; // UTF-8前进3字节 matched = 1; break; } } if (!matched) { // 没找到，可能是ASCII或其它字符，原样发送一个字节 HAL_UART_Transmit(&huart1, (uint8_t*)p, 1, HAL_MAX_DELAY); p += 1; } } }

   然后，你可以这样调用：print_gbk(“温度: 25\r\n”);。这个函数会识别“温”、“度”两个字并转换为GBK发送，冒号、空格、数字和回车换行符是ASCII字符，原样发送。

4. 封装一个printf_gbk函数： 更进一步，你可以利用vsprintf将格式化的字符串先输出到一个UTF-8缓冲区，然后调用上面的转换函数发送，实现类似printf的格式化GBK输出功能。

策略二的优缺点：

• 优点：
  • 源代码统一为UTF-8，利于团队协作和版本管理（如Git）。
  • 通过查表法，可以动态选择输出编码，兼容性最强。
  • 符合现代软件开发规范。
• 缺点：
  • 需要额外实现转换代码，增加复杂度和少量ROM开销（用于存储码表）。
  • 转换表需要手动维护，如果中文内容经常变动，会比较麻烦。

5. 进阶排查与深度避坑指南

即使按照上述策略操作，你可能还是会遇到一些古怪的问题。下面是一些更深层次的排查点和经验之谈。

5.1 编译器与链接器的“隐藏”设置

编码问题不仅发生在编辑器和运行时，编译阶段也可能引入干扰。

• Keil的“–locale”和“–multibyte_chars”选项：在Keil的Target Options -> C/C++选项卡下，有一个“Misc Controls”输入框。这里可以添加编译器指令。对于ARMCC编译器，可以尝试添加--locale=english和--multibyte_chars。前者指定区域设置为英语（避免一些本地化转换），后者告知编译器源文件中可能包含多字节字符（如中文），让编译器以更保守的方式处理字符串常量。但这并非万能，核心还是文件编码本身。
• STM32CubeIDE的编码设置：如果你使用STM32CubeIDE（基于Eclipse），需要检查工作空间和项目的文本文件编码。右键项目 -> Properties -> Resource -> Text file encoding，确保设置为UTF-8。同时，在Window -> Preferences -> General -> Workspace 中，也设置“Text file encoding”为UTF-8。

5.2 串口助手本身的“坑”

不要完全信任串口助手，它可能是乱码链条的最后一环。

• 显示缓冲区与设置重置：有些串口助手在更改编码设置后，需要清空当前显示缓冲区，新的设置才能对后续接收的数据生效。否则，之前接收的、用错误编码显示的乱码字符可能还残留在界面上，影响判断。
• 自动换行与字符截断：确保串口助手没有开启“按十六进制显示”或“按ASCII显示”之外的奇怪模式。有些助手有“自动换行”或“最大行数”限制，如果一行数据被意外截断，也可能导致解码错误。
• 多软件交叉验证：当怀疑是串口助手问题时，最有效的方法是用另一个已知支持UTF-8/GBK的软件（如Putty）连接同一串口，对比显示结果。

5.3 调试技巧：十六进制视图是终极裁判

当字符显示扑朔迷离时，切换到十六进制（Hex）视图，直接查看原始字节流，这是最可靠的调试手段。

1. 在串口助手中，勾选“十六进制显示”或类似选项。
2. 单片机发送一个明确的中文字符串，例如“中”（它的UTF-8编码是E4 B8 AD，GBK编码是D6 D0）。
3. 观察接收区显示的十六进制数。
   • 如果收到E4 B8 AD，说明单片机发送的是UTF-8。
   • 如果收到D6 D0，说明单片机发送的是GBK。
   • 如果收到其他完全不同的字节，说明编译环节就出错了，源代码中的字符串编码可能已经被编译器误解。
4. 根据看到的十六进制码，去核对你的预期编码。这能帮你迅速定位问题出在发送端（单片机程序）还是接收端（串口助手设置）。

5.4 关于“微库（MicroLIB）”的特别说明

在Keil中，为了减小代码体积，我们常会勾选“Use MicroLIB”。这个微库对标准C库进行了精简，在大多数情况下工作良好。但在处理国际化（多字节字符）和某些IO操作时，其行为可能与完整库有细微差别。如果你在使用了上述所有方法后问题依旧，可以尝试：

1. 取消勾选“Use MicroLIB”，使用标准C库重新编译测试。标准库对本地化和字符集的支持更完整。
2. 如果问题解决，说明是MicroLIB的兼容性问题。你可以选择继续使用标准库（代价是代码体积增大），或者更严格地检查你的重定向函数（_write）和编码处理逻辑，确保其与MicroLIB配合无误。

6. 构建健壮的串口调试输出框架

解决了中文乱码，我们可以更进一步，设计一个更稳定、功能更丰富的调试信息输出框架，这将极大提升日常开发效率。

6.1 分级别日志输出

不是所有信息都需要时刻打印。我们可以定义不同的日志级别。

typedef enum { LOG_LEVEL_ERROR = 0, LOG_LEVEL_WARN, LOG_LEVEL_INFO, LOG_LEVEL_DEBUG, } log_level_t; // 设置当前日志级别，只有级别高于或等于此级别的信息才会被打印 static log_level_t g_current_log_level = LOG_LEVEL_INFO; void log_output(log_level_t level, const char *format, ...) { if (level > g_current_log_level) { return; // 级别不够，不输出 } // 添加级别前缀 const char *level_str[] = {“[E] “, “[W] “, “[I] “, “[D] “}; char prefix_buffer[64]; snprintf(prefix_buffer, sizeof(prefix_buffer), “%s”, level_str[level]); // 格式化可变参数 char log_buffer[256]; va_list args; va_start(args, format); vsnprintf(log_buffer, sizeof(log_buffer), format, args); va_end(args); // 发送前缀和日志内容，这里可以集成之前的编码转换函数 // 例如：print_gbk(prefix_buffer); print_gbk(log_buffer); printf(“%s%s\r\n”, prefix_buffer, log_buffer); // 简单示例，先假设英文 }

使用方式：log_output(LOG_LEVEL_INFO, “系统初始化完成，版本：%s”, “V1.2”);。通过修改g_current_log_level，可以在发布时关闭调试信息，减少输出干扰和代码体积。

6.2 添加时间戳和线程信息（如果使用RTOS）

对于复杂的系统，知道日志发生的时间点和任务上下文非常有用。

#include “cmsis_os.h” // 如果使用FreeRTOS void log_output_with_ctx(log_level_t level, const char *format, ...) { // … 级别判断同上 … char header[128]; uint32_t tick = osKernelGetTickCount(); // 获取系统滴答计数 const char *task_name = “Sys”; // 默认系统任务 #ifdef USE_FREERTOS task_name = pcTaskGetName(NULL); // 获取当前任务名 #endif // 格式化头部信息：[时间戳][任务名][级别] snprintf(header, sizeof(header), “[%lu][%s]%s”, (unsigned long)tick, task_name, level_str[level]); // … 后续格式化可变参数并输出，注意header和log_buffer的拼接 … }

这样的日志输出类似于[123456][TaskSensor][I] 采样值: 1024，信息量大大增加。

6.3 输出重定向到多个目的地

除了串口，你可能还想将日志保存到SD卡、或者通过网络发送。我们可以抽象一个输出接口。

typedef void (*log_output_func_t)(const char *str, int len); static log_output_func_t g_output_funcs[MAX_OUTPUT] = {NULL}; static int g_output_count = 0; void log_register_output(log_output_func_t func) { if (g_output_count < MAX_OUTPUT) { g_output_funcs[g_output_count++] = func; } } // 在log_output函数内部，最终不再直接调用printf或HAL_UART_Transmit // 而是遍历所有注册的输出函数进行发送 for (int i = 0; i < g_output_count; i++) { if (g_output_funcs[i] != NULL) { g_output_funcs[i](final_buffer, strlen(final_buffer)); } } // 注册串口输出函数 void uart_output(const char *str, int len) { HAL_UART_Transmit(&huart1, (uint8_t*)str, len, HAL_MAX_DELAY); } // 在系统初始化时调用 log_register_output(uart_output);

这样，未来增加新的输出方式（如SPI Flash、Wi-Fi）就非常灵活，无需修改核心的日志打印代码。

7. 总结与个人实践心得

回顾整个中文乱码的解决过程，本质上是一场关于“数据一致性”的战役。从源代码的文本编辑器，到编译器的解析，再到单片机内存中的存储，最后通过串口发出，以及上位机软件的接收解码，这整条链路上的任何一个环节使用了错误的“密码本”，都会导致最终显示失败。

我个人在项目中的习惯是：将整个开发环境的编码统一为UTF-8无BOM格式。这包括代码编辑器（VSCode）、编译器（GCC/ARMCC，通过编译选项或工程设置）、版本控制工具（Git）。对于调试，我首选Putty或MobaXterm这类对UTF-8支持良好的终端。对于需要兼容老旧上位机或与其他GBK系统对接的情况，我会采用策略二中的查表转换法，在代码层面做一个轻量级的编码转换层，这样既能保持源码的“纯洁性”，又能实现输出的“兼容性”。

最后一个小技巧：在项目初期，可以专门写一个测试函数，依次发送一段包含中文、英文、数字、符号的已知字符串，并同时打印其十六进制值。用这个函数来快速验证你的整个输出链路是否畅通、编码是否正确。把它当作串口调试的“冒烟测试”，能帮你节省大量后期排查的时间。