C程序ANSI彩色日志实践

终端里清一色的printf日志，协议一多就眼花。用ANSI 转义序列（SGR）给前景色、粗体、背景色套一层，Linux/macOS 终端、Windows Terminal、WSL、多数 IDE 集成终端都能直接生效——零依赖、不改日志框架，适合驱动调试、串口协议 dump、嵌入式 bring-up。

速览

• 格式：\033[<显示>;<前景>;<背景>m开头，\033[0m结尾复位。
• 常用前景：31红、32绿、33黄、36青；加1;为粗体高亮。
• 重定向到文件会写入裸 ESC，产生乱码 → 用isatty()或环境变量开关颜色。
• 推荐宏封装，按 ERROR/WARN/INFO/DEBUG 分级配色。

核心结论（30 秒版）

1. 语法：printf("\033[1;31m错误\033[0m\n");
2. 务必以\033[0m结束，否则后续输出继承颜色。
3. 仅TTY上色；管道/文件应关闭 ANSI。
4. 旧版cmd.exe默认不支持，需 Windows Terminal 或SetConsoleMode开 VT。
5. 协议 dump：按字节偏移分段配色，比整行单色更易扫字段。

目录

• 1. ANSI SGR 是什么
• 2. 语法与码表
• 3. 基础示例
• 4. 宏封装（强烈推荐）
• 5. 日志分级配色
• 6. 实战：让协议帧「一眼可读」
• 7. 如何优雅地决定是否输出颜色
• 8. 踩坑实录：ANSI 颜色的经典翻车点
• 9. 延伸阅读

1. ANSI SGR 是什么

SGR（Select Graphic Rendition）是 ECMA-48 / ISO 6429 里用 ESC 序列控制终端显示属性的机制。C 里常见写法：

2. 语法与码表

2.1 完整格式

printf("\033[显示方式;前景色;背景色m 内容 \033[0m");

分号分隔的多段可省略中间段，例如\033[1;31m表示粗体+红字。

2.2 显示方式（常用）

2.3 前景色（字体）

2.4 背景色

2.5 256 色与真彩色（可选）

现代终端支持\033[38;5;<n>m（256 色前景）、\033[38;2;<r>;<g>;<b>m（24 位 RGB）。日常日志用30–37足够；需要品牌色再扩展。

3. 基础示例

#include<stdio.h>intmain(void){printf("\033[1;31mThis text is red and bold.\033[0m\n");printf("\033[0;36mCyan text\033[0m\n");printf("\033[1;33mYellow bold\033[0m on default background\n");printf("\033[41;37mWhite on red background\033[0m\n");return0;}

实际项目里不推荐在业务代码中裸写\033[...m——容易漏\033[0m、难以统一开关颜色。见下一节宏封装。

4. 宏封装（强烈推荐）

避免每次手写\033[0m，并便于一键关闭颜色：

#include<stdio.h>#defineHL_RED"\033[1;31m"#defineHL_GRN"\033[1;32m"#defineHL_YEL"\033[1;33m"#defineHL_CYN"\033[1;36m"#definePF_CLR"\033[0m"#definemyprintf(color,fmt,...)\do{\printf("%s",color);\printf(fmt,##__VA_ARGS__);\printf("%s",PF_CLR);\}while(0)/* 用法 */voiddemo(void){myprintf(HL_YEL,"%s\n","warning line");myprintf(HL_GRN,"ok: %d\n",42);}

##__VA_ARGS__在 GCC/Clang 下允许无额外参数；MSVC 需,_VA_ARGS__或 C23__VA_OPT__。

4.1 可直接拷贝的log_color.h

零依赖头文件，集成 TTY 判断与四级日志宏：

#ifndefLOG_COLOR_H#defineLOG_COLOR_H#include<stdio.h>#include<stdlib.h>#include<unistd.h>#defineCLR_RST"\033[0m"#defineCLR_ERR"\033[1;31m"#defineCLR_WRN"\033[1;33m"#defineCLR_INF"\033[1;32m"#defineCLR_DBG"\033[0;36m"staticinlineintlog_use_color(void){constchar*no_color=getenv("NO_COLOR");if(no_color&&no_color[0]!='\0')return0;if(getenv("FORCE_COLOR"))return1;returnisatty(fileno(stdout));}#defineLOG_PRINT(clr,lvl,fmt,...)\do{\if(log_use_color())printf("%s",clr);\printf("[%s] "fmt"\n",lvl,##__VA_ARGS__);\if(log_use_color())printf("%s",CLR_RST);\}while(0)#defineLOG_E(fmt,...)LOG_PRINT(CLR_ERR,"ERR",fmt,##__VA_ARGS__)#defineLOG_W(fmt,...)LOG_PRINT(CLR_WRN,"WRN",fmt,##__VA_ARGS__)#defineLOG_I(fmt,...)LOG_PRINT(CLR_INF,"INF",fmt,##__VA_ARGS__)#defineLOG_D(fmt,...)LOG_PRINT(CLR_DBG,"DBG",fmt,##__VA_ARGS__)#endif/* LOG_COLOR_H */

用法：#include "log_color.h"后LOG_W("retry %d", n);。Windows 工程在main开头调用enable_vt_mode()（见 §7.2）即可。

5. 日志分级配色

#defineLOG_E(fmt,...)myprintf(HL_RED,"[E] "fmt"\n",##__VA_ARGS__)#defineLOG_W(fmt,...)myprintf(HL_YEL,"[W] "fmt"\n",##__VA_ARGS__)#defineLOG_I(fmt,...)myprintf(HL_GRN,"[I] "fmt"\n",##__VA_ARGS__)#defineLOG_D(fmt,...)myprintf(HL_CYN,"[D] "fmt"\n",##__VA_ARGS__)

6. 实战：让协议帧「一眼可读」

6.1 按字段偏移上色（单行）

协议调试时按字节偏移上色，关键字段一眼可辨：

#include<stdio.h>#defineHL_RED"\033[1;31m"#defineHL_GRN"\033[1;32m"#defineHL_YEL"\033[1;33m"#defineHL_CYN"\033[1;36m"#definePF_CLR"\033[0m"#definemyprintf(color,fmt,...)\do{printf(color);printf(fmt,##__VA_ARGS__);printf(PF_CLR);}while(0)voiddump_frm(constchar*title,constunsignedchar*data,intlen){myprintf(HL_YEL,"%s\n",title);for(inti=0;i<len;i++){if(i==0)myprintf(HL_RED,"%02x ",data[i]);/* 例如 msgType */elseif(i==3||i==4)myprintf(HL_CYN,"%02x ",data[i]);/* 例如 length */elsemyprintf(HL_GRN,"%02x ",data[i]);}putchar('\n');}

可按协议文档把i==0、i==3||i==4换成宏常量偏移，避免魔数散落。

6.2 对齐版：offset + 十六进制 + ASCII 侧栏

长度变化时单行%02x列不对齐；经典hexdump每行 16 字节，带偏移与可打印字符侧栏：

0000: aa bb cc dd ee ff 00 11 12 34 56 78 9a bc de f0 ........ .4Vx.... 0010: 01 02 03 04

#include<stdio.h>#include<ctype.h>staticconstchar*byte_color(inti){if(i==0)return"\033[1;31m";/* msgType */if(i==3||i==4)return"\033[1;36m";/* length */return"\033[1;32m";}staticintg_dump_color=1;voiddump_hex_aligned(constunsignedchar*data,intlen){for(intbase=0;base<len;base+=16){printf("%04x: ",base);charascii[17];for(inti=0;i<16;i++){intidx=base+i;if(idx<len){if(g_dump_color)printf("%s",byte_color(idx));printf("%02x ",data[idx]);if(g_dump_color)printf("\033[0m");ascii[i]=isprint(data[idx])?(char)data[idx]:'.';}else{printf(" ");ascii[i]=' ';}if(i==7)putchar(' ');}ascii[16]='\0';printf(" %s\n",ascii);}}

g_dump_color可与log_use_color()联动；侧栏便于快速辨认 ASCII 字段（如魔数ABCD）。

7. 如何优雅地决定是否输出颜色

7.1 何时应关闭颜色

用isatty(fileno(stdout))判断标准输出是否为 TTY：

#include<unistd.h>#include<stdio.h>staticintcolor_enabled=-1;staticintuse_color(void){if(color_enabled<0)color_enabled=isatty(fileno(stdout));returncolor_enabled;}#definemyprintf(color,fmt,...)\do{\if(use_color())printf("%s",color);\printf(fmt,##__VA_ARGS__);\if(use_color())printf("%s",PF_CLR);\}while(0)

也可读环境变量：NO_COLOR（no-color.org 约定）、FORCE_COLOR=1强制开启。

isatty()是够用但不完美的默认策略：

严格场景建议：命令行--color=auto|always|never覆盖isatty()，并与NO_COLOR一并判断（见log_color.h）。

7.2 平台支持

Windows 旧控制台可在启动时启用虚拟终端（Windows 10+）：

#ifdef_WIN32#include<windows.h>staticvoidenable_vt_mode(void){HANDLE h=GetStdHandle(STD_OUTPUT_HANDLE);DWORD mode=0;if(GetConsoleMode(h,&mode))SetConsoleMode(h,mode|ENABLE_VIRTUAL_TERMINAL_PROCESSING);}#endif

跨平台项目常见写法：

#ifdefined(_WIN32)&&!defined(USE_ANSI_COLOR)#defineHL_RED""#definePF_CLR""#else#defineHL_RED"\033[1;31m"#definePF_CLR"\033[0m"#endif

7.3 与 C++ 日志

C++ 可向std::ostream插入 ANSI 字符串，或用fmt/spdlog等库的ANSI 配色 sink；原理相同，生产环境更推荐成熟日志库 + 结构化字段，ANSI 留给本地调试。

8. 踩坑实录：ANSI 颜色的经典翻车点

9. 延伸阅读

编译示例：gcc -Wall -o color_demo color_demo.c，在终端直接运行可见彩色；./color_demo > out.txt可验证文件中为裸转义符。

适用边界：什么时候不该用

ANSI 彩色日志的本质是人眼调试辅助，不是日志系统的核心能力。

本地 bring-up、协议联调、单次复现排查——ANSI 性价比高；进入采集与告警体系后，改用结构化日志（级别、时间、trace_id 字段），颜色留给交互式终端即可。

收束：ANSI 彩色日志是低成本的可读性增强——log_color.h+ 分级色 + TTY/NO_COLOR判断，就能在 C 调试里少花一半眼力；上线采集链路记得关色或写无 ESC 的纯文本副本。

验证环境：GCC 13 · Linux TTY · Windows Terminal 1.18 · macOS Terminal