如果你在 CLion 里调 STM32 串口大概率也踩过这个坑printf 输出死活不出现网上搜到的答案全是让重写 fputc你照着写了结果一点用都没有。后来换成重写 _write整个世界安静了。这篇文章就把为什么是 _write 而不是 fputc 这件事讲清楚顺便把 CLion 里串口重定向的完整配置、常见坑和排查思路一起梳理出来适合用 arm-none-eabi-gcc 工具链做嵌入式开发、又习惯在 CLion 里写代码的朋友。1. 问题背景CLion 串口调试时 printf 失效的典型场景1.1 复现路径从新建工程到串口助手这个问题的标准复现场景大概是这样的你从 STM32CubeMX 生成了一个基础工程或者手写了一个 CMake 工程工具链选的是 arm-none-eabi-gccIDE 是 CLion。你满心欢喜地在 main 函数里写了一句printf(Hello CLion\r\n);然后打开串口助手波特率也对串口也选对了结果屏幕上什么都没有。于是你开始排查直接调用HAL_UART_Transmit发一包固定数据串口助手能收到说明串口本身没问题但只要换成 printf就是一片空白。这种问题在 Keil 和 IAR 里也会遇到但网上能找到的解决方案尤其是中文社区的方案大部分是 Keil 系的让你重写一个fputc函数大概是这样的int fputc(int ch, FILE *f) { HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, HAL_MAX_DELAY); return ch; }在 Keil 工程里这一段代码通常真的能让 printf 输出到串口。但在 CLion GCC 的环境里这段代码加进去以后编译能过printf 依旧无声无息。这时候很多人就开始怀疑人生怀疑是 HAL 库版本问题怀疑是 CLion 的配置问题甚至怀疑是串口线接触不良。其实问题不在硬件也不在 CLion而在 C 库实现上。1.2 网传 fputc 方案为什么在 CLion 里失灵要理解这个差异得先搞清楚一件事你用的 C 库是什么。Keil 的 AC5/AC6 编译器默认可以选 microlib这个库体积很小很多标准函数的实现做了精简。在 microlib 里printf 处理完格式化以后确实会逐字符调到 fputc所以你在 Keil 里重写 fputcprintf 的输出就被“劫持”到了串口。这也是为什么网上大量教程都是这个写法因为 Keil 在嵌入式开发中的存量太大了老工程师的经验就这样一代传一代。但 CLion 里的 arm-none-eabi-gcc 工具链不一样。它默认链接的是 Newlib或者 Newlib-nano。这个 C 库的 printf 实现路径和 microlib 差别很大格式化完成后的字符并不是直接调用 fputc 这个函数而是走一套基于 FILE 缓冲区的机制最后落到一个底层系统调用_write上。你重写 fputc相当于改了一个 printf 根本不会经过的入口自然一点效果都没有。1.3 先别急着改代码确认工具链如果你在 CLion 里也遇到了这个问题开始改代码之前先花两分钟确认一下自己的工具链和链接配置。打开 CLion 的 Settings - Build, Execution, Deployment - Toolchains看看编译器路径是不是某个arm-none-eabi-gcc比如arm-none-eabi-gcc --version如果输出类似arm-none-eabi-gcc (GNU Arm Embedded Toolchain 10.3-2021.10)这样的信息那你的 C 库就是 Newlib 系列。再看 CMakeLists.txt 里的链接选项常见的是target_link_options(${PROJECT_NAME} PRIVATE --specsnano.specs --specsnosys.specs )--specsnano.specs会切换到 Newlib-nano体积更小但默认不包含浮点打印支持--specsnosys.specs会链接一套最小的 syscall stub避免程序跑到半主机semihosting相关的代码里去。这两个参数在后面都非常关键尤其是第二个和_write的实现直接相关。2. 底层原因printf、fputc、_write 之间到底是什么关系2.1 newlib 中 printf 的调用链要彻底搞懂为什么重写 _write先看 newlib 里 printf 到底是怎么工作的。表面上你调用的是 printf但它在内部会经过_vfprintf_r这样的重入版本函数把格式化结果写到 stdout 这个 FILE 结构体相关的缓冲区里。缓冲区满了或者遇到换行符且当前是行缓冲模式再或者程序主动 fflush就会把缓冲区的数据通过底层函数真正发出去。这个底层函数在 newlib 的 syscall 层就是_write。它的原型是int _write(int file, char *ptr, int len);其中file是文件描述符ptr是要发送的数据缓冲区指针len是数据长度。也就是说stdout、stderr 的内容最终都会集中到这里来。你只要重写这个函数把数据从串口发出去整个 printf 的输出链路就通了。可以打个比方printf 像一个写文件的文员它把内容填进一张张表格里fputc 是往某一张表格里填一个字而 _write 是把整沓填好的表格送出去的人。你只换掉填字的人送信的人还是原来那个信件当然到不了该到的地方。2.2 fputc 和 _write 的分工差异fputc 在标准 C 库里负责“往一个流里写一个字符”。但在 newlib 的实现里printf 并不是靠调用 fputc 这个符号来输出格式化结果的。fputc 本身也只是一个上层接口它把单个字符放进 FILE 的缓冲区缓冲区的情况由 FILE 结构体管理最终刷新缓冲区时依然会走进 _write。换句话说fputc 和 _write 不是一个层面的东西。fputc 操作的是抽象流_write 操作的是底层设备。在 CLion GCC 的链路里printf 默认走的是底层 _write 这条高速路而不是 fputc 这条县道。你重写了 fputc等于把县道修得再漂亮printf 的车却没有开上去。另外要留意一点newlib 里 fputc 的符号通常是_fputc_r或者带__sputc宏实现直接覆盖一个名为fputc的函数有时可能连链接器都不会认为你有问题因为标准库里本来就有这个符号你定义了一个强符号覆盖它链接能通过但得不到你想要的效果。这也是很多人在 CLion 里加了 fputc 却毫无反应的原因。2.3 为什么有些平台重写 fputc 有效既然 fputc 不是必经之路为什么 Keil 里重写它就有效因为 Keil 默认用的 microlib 实现走了另一条路。microlib 为了控制体积省掉了很多 FILE 缓冲区的复杂管理printf 在输出字符时直接回调fputc所以用户只要重定义 fputc就能让 printf 流向串口。IAR 的嵌入式 C 库也有类似的实现逻辑很多老教材基于 IAR 或 Keil 在写导致“重写 fputc”成了教科书式的做法。但到了 CLion 配 arm-none-eabi-gcc 这个新组合C 库换成了 newlib这条路就断了。很多从 Keil 迁到 CLion 的人第一次遇到这个问题都会卡住因为经验在新的工具链下不适用了。这里还要提一个容易混淆的地方STM32CubeIDE 默认用的也是 arm-none-eabi-gcc但它会在生成的代码里塞一个 syscalls.c里面已经提供了_write的默认实现很多人在 CubeIDE 里改 fputc 有时候也能用是因为 CubeIDE 的 syscall 实现被改过或者他们使用了不同的半主机模式。而 CLion 的 CMake 工程不会自动生成 syscalls.c所以你必须自己补上 _write。这也是为什么同一个工程从 CubeIDE 导入 CLion 后printf 突然就不工作了。3. CLion 下的正确写法重写 _write3.1 基础模板HAL 库版本我这里的习惯是在一个单独的文件里实现 _write比如retarget.c不要把它放在 main.c 里避免以后维护工程时被 CubeMX 重新生成覆盖。最简单的 HAL 库版本是这样#include errno.h #include sys/unistd.h #include usart.h int _write(int file, char *ptr, int len) { if (file STDOUT_FILENO || file STDERR_FILENO) { HAL_UART_Transmit(huart1, (uint8_t *)ptr, len, HAL_MAX_DELAY); return len; } errno ENOTSUP; return -1; }几个关键点说明一下。第一STDOUT_FILENO和STDERR_FILENO来自sys/unistd.h分别对应文件描述符 1 和 2。printf 的输出走 stdout所以判断这两个描述符基本够用。第二返回值一定返回len表示这次数据全部发送成功。如果返回 0 或者 -1printf 可能认为写入失败轻则丢数据重则内部状态异常。第三HAL_UART_Transmit最后一个参数HAL_MAX_DELAY是无限等待阻塞直到发送完成。这种写法简单可靠调试日志场景完全够用但如果你在高频率中断里调用 printf可能会因为长时间阻塞引发问题后面我单独说。第四别忘了包含对应的串口头文件比如usart.h否则huart1没有声明编译会报错。huart1这个句柄名以 CubeMX 生成的为准很多人改成huart2或huart6别照抄。3.2 不依赖 HAL 的寄存器版本如果你不想依赖 HAL 库或者单片机型号比较特殊也可以用寄存器直写的方式。比如 STM32 的 USART1在标准库或 LL 库的底子上可以直接操作int _write(int file, char *ptr, int len) { if (file ! STDOUT_FILENO file ! STDERR_FILENO) { errno ENOTSUP; return -1; } for (int i 0; i len; i) { while (!(USART1-ISR USART_FLAG_TXE)); USART1-TDR (uint8_t)ptr[i]; } return len; }这里USART_FLAG_TXE是发送数据寄存器空的标志USART1 要提前初始化好时钟和引脚否则写寄存器会直接触发硬件错误。寄存器版本的好处是代码跟 HAL 解耦缺点是移植到其他型号时要手改寄存器名。3.3 链接参数与半主机处理光写了 _write 还不够链接参数也得对。在 CMakeLists.txt 里我建议加上target_link_options(${PROJECT_NAME} PRIVATE --specsnano.specs --specsnosys.specs -u _printf_float )--specsnano.specs使用 newlib-nano可以显著降低代码体积。--specsnosys.specs会把缺失的系统调用 stub 帮我们补上这里最关键如果没有 nosys.specs程序链接时遇到_write未定义有可能链接失败或者更隐蔽的是参考了默认的半主机实现导致一旦 printf 触发调试通道semihosting目标板就会卡死或者跳到 HardFault。-u _printf_float是为了让 printf 支持%f浮点格式化newlib-nano 默认把这个功能裁掉了不加上去打印浮点数会直接得不到正确结果。这里有个常见误解很多人以为实现了 _write 就不需要 nosys.specs 了。其实 nosys.specs 还提供了_sbrk、_close、_lseek、_read等一堆 syscall 的弱定义。你只实现 _write但 malloc 或其它库函数可能还会引用_sbrk如果不链接 nosys.specs某些工程会在链接时报undefined reference to _sbrk。加上它整个 syscall 层就齐全了。3.4 怎样确认 _write 真的被调用了写完代码以后怎么确认 _write 真的接管了 printf最直接的办法是在 _write 函数里打一个断点然后把 printf 放在 main 里执行调试模式下如果断点命中说明链路已通。如果不方便打断点也可以在 _write 第一句加一个临时变量或者写一个死循环int _write(int file, char *ptr, int len) { for (volatile int i 0; i 1000; i); ... }如果串口或调试器显示程序进入了这个函数就说明 printf 已经调用了 _write剩下的问题就是串口配置和波特率了。还有一个验证技巧直接在_write里不管ptr内容先发一个固定数据const char test[] write called\r\n; HAL_UART_Transmit(huart1, (uint8_t *)test, sizeof(test) - 1, HAL_MAX_DELAY);如果上电后串口能收到这行字但 printf 的内容收不到说明_write被调用了问题可能在格式化、缓冲区刷新时机或者len的返回值上这时候继续往下排查就轻松多了。4. 排查实录从“没输出”到“乱码”4.1 输出完全没有如果重写 _write 之后串口依然什么都没有先检查两件事第一_write所在的源文件是否真的参与编译。CMake 里如果新加的retarget.c没有被add_executable包含编译器根本不会链接它。可以在 CMakeLists.txt 里加上一句target_sources(${PROJECT_NAME} PRIVATE retarget.c)然后在 CLion 里重新加载 CMake 工程。第二链接选项--specsnosys.specs是否生效。我见过有人在 CMake 里写了target_link_libraries(${PROJECT_NAME} --specsnano.specs)这种写法有时不会生效因为--specs是编译器/链接器选项不是库名。应该用target_link_options或set(CMAKE_EXE_LINKER_FLAGS --specsnano.specs --specsnosys.specs)。在 CMake 里这两种写法的差异很坑如果没写对链接时用的还是默认库。4.2 输出乱码如果 printf 有输出但全是乱码先别怀疑 _write 写错了乱码的最常见原因是串口参数不匹配。检查串口助手的波特率、数据位、停止位、校验位是否和初始化代码一致。STM32 的 UART 初始化里波特率寄存器是硬件预分频计算的如果你系统时钟配置变了但串口时钟没跟着变实际波特率会偏差很大这时候收出来的数据就是乱码。另一个容易忽视的点是电平转换。如果你的开发板串口是 TTL 电平但用了 USB 转 RS232 的线收到的东西也会乱。这类问题跟 _write 没有直接关系但很多人在排查 printf 重定向时会被带偏。先用HAL_UART_Transmit发送一个固定字符串如果固定字符串也乱码那就是串口硬件或者时钟初始化的问题不是 _write 的问题。4.3 浮点格式化失效printf(%f, 3.14)在嵌入式中经常莫名其妙地有问题。如果你已经重写了 _write浮点输出变成空白、或者输出?大概率是 newlib-nano 默认没有启用浮点格式化支持。解决方法就是在链接选项里加-u _printf_float这个选项会把浮点格式化函数强制拉进链接。如果加了以后代码体积增大很多这是预期内的因为浮点格式化实现本身就不小。顺便提一句很多人为了省空间会放弃%f改用整数运算把浮点拆开打印比如float value 3.14; printf(%d.%02d, (int)value, (int)((value - (int)value) * 100));这也是一种实用方案但调试阶段还是建议加上-u _printf_float省时间。4.4 Debug 时的 0x20 访问违例串口调用链里还有个经典故障CLion 的 GDB 调试窗口报write to location 0000000000000020 caused an access violation程序直接跑飞。这个0x20地址一看就不是有效 RAM 地址通常是空指针或者外设未初始化导致的。在重定向场景下最常见的触发原因有两个。一个是huart1句柄还没有初始化就在_write里通过HAL_UART_Transmit去访问huart1.Instance这个时候huart1.Instance可能是 0于是访问了地址 0 附近的区域报出来的值就类似 0x20。解决办法是确保printf在MX_USART1_UART_Init()之后调用不要在系统时钟和外设初始化之前就打印日志。另一个原因是串口外设时钟没开。HAL 初始化函数里其实会打开时钟但如果你在_write里用了寄存器版本又没有调用__HAL_RCC_USART1_CLK_ENABLE()外设地址空间根本不可访问也可能触发总线错误。这个报错的地址不一定全是 0x20具体值取决于外设基地址和偏移量。4.5 中文输出乱码CLion 里跑 printf 输出中文串口助手显示乱码十有八九是编码不一致。CLion 默认源文件是 UTF-8 编码中文字符串在内存里是 UTF-8 字节流但很多串口助手默认按 GBK 或 ASCII 解析自然就乱码。这不是 printf 重定向的问题而是编码标准不统一。我自己的习惯是嵌入式日志里尽量用英文和 ASCII 字符协议数据更要用十六进制。实在要输出中文可以把源文件编码改成 GBK或者选择支持 UTF-8 的串口助手但这两样都会给协作和后续维护添麻烦。调试日志最重要的是可读性和稳定性不是显示中文。下面这个表可以当速查手册用现象可能原因优先排查printf 完全无输出_write 未实现/未参与链接确认 retarget.c 在编译列表_write 断点是否命中无输出且链接正常半主机 stub 生效导致卡死链接参数加 --specsnosys.specs有输出但乱码波特率/电平不匹配用 HAL_UART_Transmit 发固定串验证有输出但 %f 错误newlib-nano 缺浮点格式支持链接选项加 -u _printf_float运行到 printf 就跑飞半主机/外设未初始化关闭半主机检查 UART 初始化顺序0x20 访问违例UART 句柄为空或时钟未开确认 printf 在 MX_USART1_UART_Init 之后中文乱码编码不一致统一 UTF-8 或改用 ASCII 日志5. 跨工具链兼容一套代码同时搞定 Keil 和 CLion5.1 条件编译的兼容写法如果你需要在 CLion 和 Keil 之间共用一套代码可以在重定向文件里用条件编译同时实现_write和fputc这样两个工具链都能用。我一般这样写#include errno.h #include stdio.h #include sys/unistd.h #include usart.h #if defined(__ARMCC_VERSION) || defined(__CC_ARM) /* Keil MDK: microlib printf calls fputc */ int fputc(int ch, FILE *f) { HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, HAL_MAX_DELAY); return ch; } #else /* CLion arm-none-eabi-gcc: newlib printf calls _write */ int _write(int file, char *ptr, int len) { if (file STDOUT_FILENO || file STDERR_FILENO) { HAL_UART_Transmit(huart1, (uint8_t *)ptr, len, HAL_MAX_DELAY); return len; } errno ENOTSUP; return -1; } #endif__ARMCC_VERSION和__CC_ARM是 Keil 编译器定义的宏arm-none-eabi-gcc 不会定义它们所以两边各走各的路。当然如果你还想在 IAR 上跑也可以补一个__ICCARM__分支一般 IAR 里也是改 fputc 或者__write具体要看库的版本。5.2 额外建议重定向 stdin 和 stderr如果你需要从串口读取数据比如实现 scanf 或者用 getchar 接收数据那除了_write还得实现_read。newlib 的_read原型是int _read(int file, char *ptr, int len) { if (file STDIN_FILENO) { HAL_UART_Receive(huart1, (uint8_t *)ptr, len, HAL_MAX_DELAY); return len; } errno ENOTSUP; return -1; }stderr 一般直接和 stdout 指向同一个串口输出就行在_write里同时判断STDERR_FILENO和STDOUT_FILENO可以保证 error 日志也走串口。_read里要注意接收超时和堵塞问题HAL_MAX_DELAY 会让程序等串口收到数据才继续执行如果协议处理不当可能卡死在 scanf 上。5.3 一些实际操作心得最后说几个我自己在实际项目中踩出来的小经验。第一个是关于缓冲区的newlib 的 stdout 默认是带缓冲的printf 的内容不一定会立刻从串口发出去。如果你希望每条日志马上输出可以在初始化时加一句setvbuf(stdout, NULL, _IONBF, 0);_IONBF表示无缓冲每次 printf 都会直接触发_write调试时非常直观。代价是执行效率低因为每个字符都可能触发一次底层调用。但调试本身就是慢点无所谓的等产品稳定后可以再改成行缓冲_IOLBF甚至全缓冲_IOFBF。第二个是关于中断里调用 printf 的问题。如果串口发送用的是阻塞模式_write里一个HAL_UART_Transmit会把整个 CPU 卡在等待发送完成的循环里在中断回调或者 RTOS 任务里这么做可能会引发并发问题。我一般在正式工程里会套一层互斥锁或者用一个环形缓冲区让_write只负责把数据塞进缓冲区再由中断或者 DMA 慢慢发送。调试阶段不必在意但产品化之前一定要处理。第三个是“不要过度设计”。很多人刚搞懂 _write 和 fputc 的区别以后喜欢写一个非常复杂的重定向框架支持多串口、支持日志分级、支持颜色。结果呢代码一复杂问题就多了。我的做法是调试工程里只放一个最简单的_write够用就行等真正需要日志系统的时候再单独设计模块不在重定向这个环节上做文章。回到最初的问题CLion 里为什么要重写_write而不是fputc答案一句话就能说清因为 CLion 配的 arm-none-eabi-gcc 工具链用的是 newlibprintf 的底层出口是_write而 Keil 的 microlib 才把出口放在fputc。下次你再看到网上铺天盖地的 fputc 教程先别急着抄看看自己的编译器是哪个再决定改哪个函数。串口不输出这种事多半不是玄学而是工具链的底层机制变了。