一个很常见的场景你在 CLion 里配好了一个 STM32 裸机工程想用 printf 把调试信息从串口打出来结果串口助手上一片空白网上教程翻了一堆有人说改 fputc有人说改__io_putchar还有人让你去折腾链接脚本。你先把最常见的 fputc 版本抄了一遍编译不报错烧进去依旧没有任何输出。再加一个__io_putchar还是静悄悄。这篇文章就把这个“CLion 下 printf 到底该重写谁”的问题彻底讲透。核心结论先说在你用arm-none-eabi-gcc newlib 的标准路径下printf 最终会汇入底层函数_write而不是 fputc。所以你在 CLion 里照着 Keil 那套经验改 fputc等于改了一个 printf 根本不调用的函数。下面我会从输出链路、实操代码、CMake 配置到坑位排查一条条拆开说。1. 为什么这个问题会冒出来1.1 从一句“printf 打不出来”说起先还原一下我见过很多次的排查现场。大家在 CLion 里新建嵌入式工程通常都是拿 STM32CubeMX 生成初始化代码再通过 CMake 导入 CLion。工具链一般就是 arm-none-eabi-gccC 库默认是 newlib 或者 newlib-nano。这个组合本身没问题但问题出在“网络上的重定向教程来源太杂”。很多老帖子、旧博客的示例来自 Keil MDK 或者 IAR它们把 printf 的输出重定向描述成“重写 fputc 就行”。新手照着一抄函数是写了可 printf 的输出流程从头到尾就没走到 fputc 那一步。更隐蔽的情况是程序在串口上偶尔会蹦出一个字节或者第一次调用 printf 之后整个程序直接卡死。这通常是_write默认指向了 semihosting 相关实现串口没接调试器或者调试器没有处理 semihosting 请求程序就在一条断点指令上等死。从这个现象也能看出来真正影响 printf 的底层函数是_write你改上层 fputc 当然治标都治不到。1.2 fputc 方案在哪些场合能 work不是说 fputc 重定向方案是错的只是它有严格的前提。Keil MDK 的 MicroLIB 就是一个典型例子。MicroLIB 为了裁剪体积把 stdio 的输出实现做成按字符回调printf 内部每输出一个字符就调用一次 fputc。所以在 Keil MicroLIB 环境下重写 fputc 确实能改变 printf 的走向。很多老教程就是从这个环境里总结出来的。但换到 GCC 工具链情况完全不同。arm-none-eabi-gcc 配套的 newlib 实现里printf 是先把格式化结果写进 stdout 的缓冲区等到缓冲区满、遇到换行、或者显式调用 fflush 时再整批交给底层系统调用。这个底层系统调用就是_write。它并不是围绕 fputc 设计的。因此同样是“重定向 printf 到串口”不同工具链要改的函数可能完全不同。把这几个环境放在一起看就不容易踩坑了。工具链 / 运行库重定向目标原因Keil MDK MicroLIBfputcMicroLIB 的 stdio 按字符回调arm-none-eabi-gcc newlib_writestdio 缓冲刷新最终走底层 syscallIAR EWARM__write / __write_bufferedIAR 专用 retarget 层桌面包环境不一定需要stdout 已被操作系统接管1.3 先搞清你的工具链层级newlib 与 _writenewlib 是面向嵌入式系统的一套 C 运行库。它和桌面 Linux 的 glibc 不一样很多底层能力需要使用者自己提供比如从硬件读一个字节、向硬件写一段字节、调整堆指针等。这些底层函数在 newlib 里有统一的名字_write就是“向某个文件描述符写入”的那一个。在裸机环境里fd1 的 stdout 本质上就是个逻辑概念你想让它走 UART 还是走别的外设就自己去实现_write。很多人在这一步会犯迷糊write和_write有什么关系简单说POSIX 标准里叫write而 newlib 为了在嵌入式这么小的空间里做适配把这类底层函数用下划线开头的名字暴露出来。你的业务代码不需要直接调用它但 printf 的缓冲机制在背后会经过它。所以“重定向 printf”这个需求准确点说就是“接管底层_write的走向”而不是去上层 fputc 上缝缝补补。2. 链路拆解printf 到串口到底走的是哪条路2.1 newlib 的底层 I/O 设计想真正理解为什么是_write得把这一条调用链看清楚。在 newlib 里printf 本质上是一个格式化函数它负责把“要输出的内容”按格式转成字节但这些字节并不是立刻、逐个送到硬件去。它们会先被塞进 stdout 对应的一个缓存区。等到缓存区被填满或者碰到换行符触发行缓冲刷新或者程序主动调用 fflush 时缓存里的整块内容才会走一次真正的“输出动作”。这个“输出动作”在 newlib 内部最终会落到_write这个函数上。你可以把流程理解为printf → 格式化 → stdout 缓冲区 → 缓冲刷新 → _write → 硬件外设注意这里面的关键点是_write拿到的是一整块待输出的字节而不是单个字符。它一次能拿到几十个甚至上百个字节能不能把这些字节都交给串口由你的实现决定。fputc 则不同它天然就是单字符接口把它放在这条链路里效率和组织方式都对不上。顺带提一个非常容易踩的问题因为 stdout 是带缓冲的很多新手以为 printf 执行完串口就应该立刻有数据。但在嵌入式环境里如果没有把 stdout 设置成无缓冲或者_isatty没有告诉运行库“这是一个终端设备”printf 可能攒了一大片才往外吐看起来就像“偶尔有输出、偶尔没输出”。这种时候不一定是_write没写好而是缓冲策略在捣乱。2.2 fputc 和 _write 的本质区别fputc 是 C 标准里的流式输出函数它面向的是 FILE 结构。你可以用 fputc 往 stdout 或者任意一个文件里写一个字符它本身并不关心底层硬件长什么样。它是“流”这个抽象层的成员。_write 则更底层它把自己定位成“文件描述符”的写操作一次写一段字节返回实际写入的字节数。这两者的差异在实际工程里非常明显。用 fputc 做重定向时printf 每次输出几个字符可能要频繁进出串口发送函数性能很差而且很难利用 DMA。用_write做重定向时一次调用就能拿到一整包待输出数据你可以选择阻塞发送、中断发送甚至直接把缓冲区地址丢给 DMA。这对嵌入式调试体验的提升是肉眼可见的。还有一点值得说_write的返回值有明确语义。如果串口发送超时或者缓冲区还没准备好你的实现要返回实际成功发送的字节数甚至返回 -1 并设置 errno。这种和底层硬件打交道的设计就是为了让上层库能感知到异常。而 fputc 的返回只是单个字符或者 EOF信息量完全不同。2.3 一张表看懂“哪个函数该被谁重写”我用一张表把不同情况下该改谁列清楚你可以直接对号入座。你的环境正确的重定向函数常见误导CLion arm-none-eabi-gcc newlib_write网上教程说改 fputcKeil MicroLIBfputc有人让你改底层半主机函数IAR__write有人让你改 fputcCubeIDE GCC同样是 _writeCubeIDE 本质也是 GCC 工具链纯 C 工程注意 extern C 包住 _write忘了 C name mangling表格背后其实就一个原则先搞清楚你这条工具链里 printf 最终汇入哪个底层函数再决定重定向谁。不要拿着 A 环境经验硬套 B 环境。很多人在 CLion 下折腾半天没结果就是被环境错位给带偏了。3. CLion 里重写 _write 的完整实操3.1 最小可用版本UART1 输出在 CLion 里最朴素也最常用的方案是这样。新建一个retarget.c放在工程源码目录里然后写这段代码。我这里假设你已经用 CubeMX 初始化好了 UART1句柄叫huart1。#include errno.h #include sys/unistd.h #include main.h extern UART_HandleTypeDef huart1; int _write(int fd, char *pBuffer, int size) { if (fd STDOUT_FILENO || fd STDERR_FILENO) { HAL_UART_Transmit(huart1, (uint8_t *)pBuffer, size, HAL_MAX_DELAY); return size; } errno EBADF; return -1; }这段代码干了三件事判断 fd 是不是标准输出或标准错误把整段字节交给 UART 发送返回实际发送的字节数。注意_write函数把pBuffer直接当成一块连续内存传给 HAL 库所以它和“逐字符发送”是两种思路。如果你还想支持scanf可以顺便实现_read。逻辑差不多只是串口接收往往一次只能收一个字节所以实现里通常按单字节处理。int _read(int fd, char *pBuffer, int size) { if (fd STDIN_FILENO) { HAL_UART_Receive(huart1, (uint8_t *)pBuffer, 1, HAL_MAX_DELAY); return 1; } errno EBADF; return -1; }在 main 函数最开始我建议再加一句setvbuf(stdout, NULL, _IONBF, 0);。它的意思是把 stdout 设置成无缓冲模式让每一次 printf 都即时触发_write。调试阶段这样最直观否则你可能碰见“printf 之后没反应程序跑了好半天才突然冒出一串数据”的怪现象。3.2 进阶多路输出、超时与 DMA有的工程不只有一个串口可能调试串口用 USART1某个外设日志走 USART2。_write的签名里只有 fd、缓冲区指针和长度没有“我是谁”这种参数。所以你不能简单说“printf 同时往两个串口打”。更常见的做法是把硬件句柄定义成一个可切换的宏或者干脆在_write里做一个全局输出通道。#define DEBUG_UART_HANDLE huart1 int _write(int fd, char *pBuffer, int size) { if (fd STDOUT_FILENO) { while (HAL_UART_Transmit(DEBUG_UART_HANDLE, (uint8_t *)pBuffer, size, 1000) ! HAL_OK) { /* 超时或 USART 忙简单重试 */ } return size; } errno EBADF; return -1; }这里我把 HAL_UART_Transmit 的返回值单独拿出来检查是因为实际中真有可能遇到串口忙或者发送超时。如果 HAL 返回 HAL_BUSY而你直接忽略HAL 库并不会帮你重发最后串口上就会丢数据。调试时看不出来一旦系统里中断变多、任务切换频繁这个问题就会暴露。用 DMA 发送是另一个进阶方向。_write一次能拿到一整块缓冲天然适合 DMA。但要注意缓冲区生命周期问题如果 DMA 还没发送完_write就返回了而上层 printf 紧接着又修改了这块缓冲就会出现“发出去的数据是乱码、缺字、错位”。稳妥做法是用 DMA 发送完成中断或者信号量等发完再返回。3.3 CMake 链接配置nano.specs 与浮点 printf很多人重写了_write编译正常但链接时一片红色报错尤其容易出现undefined reference to _sbrk、undefined reference to _lseek这类符号。这是因为 GCC 的 newlib 库里除了_write还预留着其他系统调用。如果你想偷懒就让链接器使用nosys.specs它会把一组空的系统调用实现塞进来保证链接通过。在 CLion 的 CMakeLists.txt 里比较典型的写法是这样target_link_options(${PROJECT_NAME} PRIVATE --specsnano.specs --specsnosys.specs -u _printf_float )如果你用的 CMake 版本比较老不支持target_link_options也可以用传统方式set(CMAKE_EXE_LINKER_FLAGS ${CMAKE_EXE_LINKER_FLAGS} --specsnano.specs --specsnosys.specs -u _printf_float)nano.specs选用精简版 C 库体积小很多适合 Flash 资源紧张的 MCU。但精简版默认不带 printf 的浮点输出如果你要printf(%.2f, 3.14)这种格式链接器会给出一个明确提示。加上-u _printf_float就是强制把浮点格式化函数拉进来。代价是代码体积会明显增加这一点要在意别等到 Flash 溢出了才一头雾水。4. 高频翻车现场与排查实录4.1 中文乱码编码、波特率与时钟三项检查CLion 下中文输出乱码是一个热度极高的问题而且很多时候它和_write无关是环境没对齐。先说最核心的一点_write收到的是一串字节它不认“中文”这个概念。如果源码文件是 UTF-8 编码那么你好这两个字在内存里就是 6 个 UTF-8 字节如果你的串口助手用 GBK 解析自然显示成一堆乱码。所以排查要分三层。第一层是源码和 IDE 编码。CLion 里建议把 File Encodings 统一设置为 UTF-8并且可以让 CMake 编译时明确字符集。第二层是串口助手的显示编码换成 UTF-8 再看。第三层是波特率和时钟。这个最隐蔽如果 MCU 的串口波特率实际值是 9600而串口助手开的是 115200那所有内容都会是花屏一样的乱码和编码设置一点关系都没有。我给一个很笨但很有效的定位方法先别打中文只打printf(ABCD);然后把串口助手切到十六进制显示。如果能看到41 42 43 44说明_write链路已经通了乱码纯属编码或波特率问题。如果连这 4 个字节都不对才需要回头查_write本身。4.2 “write access to const memory”与指针乱写CLion 配 OpenOCD 调试时偶尔会弹出一句类似 “write access to const memory has been detected” 的提示意思是代码正在往只读区域写数据。遇到这个第一反应不是去怪调试器而是查自己哪里越界或者指针类型搞错了。最常见的情况就是把一个 const 限定符强转去掉然后往里面写值这种操作在 C 语言里属于未定义行为MCU 的 MPU 或调试器一旦发现就会报警。还有一种常见原因和_sbrk缺失有关。newlib 的 malloc 依赖_sbrk来扩展堆空间。如果_sbrk被 nosys.specs 里的空实现覆盖或者实现里返回的堆顶地址不对malloc 出来的指针可能指向内存映射外的区域一写就触发硬件异常。调试器会把它描述成“write to location 0000000000000020 caused an access violation”之类的地址错误。这时要检查链接脚本里堆栈区域的符号是不是被正确使用尤其不要自己随便魔改.ld文件。排查顺序我建议是先看有没有明显的指针类型转换再看数组有没有越界最后才考虑堆分配问题。这三个里面前两个占了绝大多数。4.3 链接阶段找不到 syscall 符号除了前面讲的_sbrk我这几年还常收到这样的报错undefined reference to _write undefined reference to _lseek undefined reference to _close undefined reference to _fstat undefined reference to _isatty undefined reference to _getpid undefined reference to _kill看到这一串符号第一反应不是去一个个实现而是检查链接 flags 里有没有--specsnosys.specs。这个 options 会把你没实现的那批系统调用空实现自动链接进来属于“够用但很简陋”的类型。如果你想要真正的串口输入输出就自己实现_write和_read它们是强符号优先级高于 nosys 提供的弱符号。如果工程里文件扩展名是 .cpp或者你把_write实现在了 C 文件里记得用extern C包一层。否则 C 编译器会对函数名做 name mangling链接器找的_write和实际产出的符号对不上报错还特别难查。防御性写法是专门建一个retarget.c用纯 C 实现省得纠结。4.4 多个 main 与 CMake 文件收集CLion 里“工程里放了多个 main.c”也是个常见事故。不少人的项目目录长这样根目录下有一个main.c作为正式入口后来又建了个test_main.c想临时测点东西。结果 CMake 里用了aux_source_directory(. SRC)之类的方式把当前目录所有 .c 文件全收进来两个源文件都定义了 main 函数链接器直接报重复定义。这个问题和_write无关但它会卡住整个开发流程。标准做法是把不同入口做成不同的可执行目标或者手动维护源文件列表。比如add_executable(project_app Core/Src/main.c Core/Src/usart.c Drivers/... )如果只是临时调试也可以先注释掉某一个 main或者用set(SOURCE_FILES main.c ...)显式指定。CLion 里最忌讳的就是靠搜索 *.c 自动收集因为它会把所有历史残留源文件都拖进来。5. 实测经验与后续扩展5.1 为什么同一段代码在别的 IDE 里改 fputc 又能跑很多人在 CLion 里踩完坑回头会想明明我在别的 IDE 里改 fputc 就能跑怎么到这就失灵了这不是玄学是运行库实现差异。Keil MicroLIB 选择把 printf 的单字符输出渠道固定在 fputc方便用户在小工程里快速重定向。而 arm-none-eabi-gcc 配套的 newlib 更偏向于类 POSIX 的底层 syscall 设计它天然认为“输出一坨数据”比“输出一个字符”更合理。理解了这一点你就能写出跨环境代码。比如用宏区分编译器#if defined(__GNUC__) int _write(int fd, char *pBuffer, int size) { /* GCC 工具链实现 _write */ } #elif defined(__CC_ARM) int fputc(int ch, FILE *f) { /* Keil 工具链实现 fputc */ } #endif这种写法在代码移植时很实用也是很多商用 SDK 内部处理 retarget 的套路。5.2 向 RTOS 与 C 工程扩展如果你的工程里用了 FreeRTOS_write里直接调用阻塞式的HAL_UART_Transmit要特别小心。任务上下文里调用没问题但如果某个中断服务函数里间接调用了 printf你又在_write里做长时间的阻塞等待就可能把整个中断阻塞住轻则任务卡顿重则系统跑飞。更合理的方式是加一个互斥量把串口发送保护起来。int _write(int fd, char *pBuffer, int size) { if (fd STDOUT_FILENO) { osMutexAcquire(uart_mutex, osWaitForever); HAL_UART_Transmit(huart1, (uint8_t *)pBuffer, size, HAL_MAX_DELAY); osMutexRelease(uart_mutex); return size; } errno EBADF; return -1; }这个例子里用 CMSIS-RTOS 的接口换成其他 RTOS 也同理。加了互斥量之后多个任务同时 printf 就不容易把数据打断成乱码。C 工程我也提一句只要你保持_write是 C 链接方式std::cout最终也会走到 stdout所以_write对 C 的流式输出同样有效。重点还是那个extern C不要被 C 的名字修饰坑到。最后再分享一个我自己常用的验证习惯拿到一块新板子别急着调中文输出先用printf(M);这种单字符同时把串口助手切到 hex 显示。看到4D说明_write链路和波特率都是通的这时候再逐步加长输出、加中文、加编解码切换。这招帮我省了不知道多少排查时间尤其适合在 CLion 这种“IDE 环境、编译器、调试器、串口工具”多重变量叠加的场景里快速锁定真正的问题出在哪一层。