1. 先从一个让人抓狂的日志 Bug 说起
几个月前帮人看一段代码，现象很怪：设备日志里温度字段偶尔会变成一个巨大的负数，或者干脆把后面几条日志的内容"吞"掉。代码逻辑看着没问题，就是一行sprintf(buf, "T=%d,H=%d", temp, humi);，buf声明成char buf[32]，怎么看都够用。最后定位到根因：temp是一个int16_t变量，但格式串里写的是%d，而传入的可变参数经过默认实参提升后是int，这在多数平台上恰好能对上；真正出问题的是另一个字段——一个long变量用了%d去接，在 64 位平台上long是 8 字节，sprintf按 4 字节去读栈上的参数，后面所有参数的偏移全部错位，于是humi读到了temp的高位垃圾，格式化出来的字符串长度不可控，最终越界写穿了buf。
这个案例几乎把sprintf的所有经典坑踩了个遍：类型不匹配导致参数错位、返回值没检查、输出长度不可控导致缓冲区溢出。所以我不打算把这篇写成一份"函数手册摘抄"，而是按一个真实使用者的思路，把sprintf这个 C 语言里最常用也最容易被误用的格式化函数，从原型语义、格式串语法、实战写法、安全边界到排错方法，一层层拆开讲清楚。不管你是刚学 C 语言、还在纠结%d和%ld区别的新手，还是已经在写嵌入式固件、后台服务、命令行工具的老手，下面这些内容应该都能直接拿去用，或者至少能帮你躲开几个我踩过的坑。
printf家族里，sprintf的定位很明确：不往屏幕上打，而是往一块你自己负责管理的内存里打。它把格式化的结果当成一段字符串写进调用者提供的缓冲区，由调用者负责这块内存的大小、生命周期和后续使用。这个"责任转移"是整个函数复杂度的来源——printf写错了顶多屏幕花掉，sprintf写错了就是内存越界，轻则数据错乱，重则程序崩溃或者被利用。理解了这一点，后面所有的规则和技巧才站得住脚。
1.1 原型、返回值和一个被普遍忽视的细节
标准原型是这样的：
#include <stdio.h> int sprintf(char *str, const char *format, ...);第一个参数str是目标缓冲区，第二个format是格式串，后面的...是可变参数。返回值类型是int，成功时返回写入的字符数，不包含结尾的'\0'；失败（比如编码错误）返回一个负数。
这里有个细节值得单独强调：返回值是"字符数"而不是"字节数"这种说法在 C 里其实是一回事，因为char就是 1 字节。但真正被忽视的是——返回值的类型是int。如果你的格式化结果理论上可能超过INT_MAX（在某些 32 位平台上就是 2GB 左右），返回值会溢出，这时候拿它去做长度计算就是错的。实际工程里极少有人拼 2GB 字符串，但如果你在做流式拼接或者大报文组装，这个上限值得记在心里。
另一个细节：sprintf不会在任何情况下帮你检查目标缓冲区够不够大。它连缓冲区有多大都不知道——没有任何参数告诉它。这就是它和snprintf的根本区别，也是所有溢出事故的来源。很多人第一次知道snprintf存在时会有一种"那我以后是不是不该用sprintf了"的疑问，这个问题的答案不是简单的"是"或"否"，后面第 4 节会展开算给你看。
至于%n这个说明符——把已写入的字符数回写到参数指向的int里——在所有格式化函数里都存在，但在业务代码里应该完全禁用，因为它要求你传入一个指针，而一旦格式串可控，这就是一个现成的任意地址写原语。这条是硬规矩，不接受讨论。
1.2 它和 printf、fprintf、snprintf 到底差在哪
把族里几个常用成员摆在一起对比，选型时不容易糊：
| 函数 | 输出去向 | 长度控制 | 返回值语义 | 典型场景 |
|---|---|---|---|---|
printf | 标准输出 | 不涉及 | 输出字符数 | 调试打印、命令行工具 |
fprintf | 指定文件流 | 不涉及 | 输出字符数 | 写日志文件 |
sprintf | 调用者缓冲区 | 无 | 写入字符数 | 已知长度足够短的拼接 |
snprintf | 调用者缓冲区 | 有，size 参数 | 本应写入的长度 | 绝大多数需要落盘到内存的场合 |
asprintf | 内部申请堆内存 | 自动 | 分配长度 | 长度完全不确定时（非标准扩展） |
asprintf是 GNU 扩展，不在 C 标准里，跨平台代码不要依赖它，但知道它存在有好处——在需要动态长度时，你可以用snprintf(NULL, 0, ...)手动实现等价逻辑，第 4 节给完整代码。
顺带说一个常见误解：有人以为sprintf比snprintf快很多，所以为了性能坚持用sprintf。实测下来（后面第 6 节有具体数据），在输出长度较短、格式串简单的情况下两者差距很小，snprintf多出来的开销主要是一次长度比较和截断处理逻辑。为了这点性能去承担越界风险，账不划算。真正需要抠性能的场合，答案通常不是"用sprintf而不是snprintf"，而是"两个都别用，手写转换"。
2. 格式串拆解：一个占位符到底由几段构成
格式串里以%开头的部分叫转换说明（conversion specification），完整语法是：
%[flags][width][.precision][length]specifier方括号表示可选，只有%和最后的specifier是必须的。这个结构值得背下来，因为九成的格式化 Bug 都出在中间这几段被省略或者写错。下面逐段拆。
2.1 五段结构与默认行为的对应关系
specifier是转换类型，决定了参数怎么被解释：d/i有符号十进制整数、u无符号十进制、o八进制、x/X十六进制、f/F定点浮点、e/E科学计数、g/G自动选择、c字符、s字符串、p指针、%字面百分号。
flags控制填充和对齐，常用的有这么几个：
-：左对齐，右侧补空格。默认是右对齐。0：用零填充而不是空格。注意零填充对左对齐无效，写了%-05d里那个0会被忽略。+：正数也强制带+号。- 空格：正数前面留一个空格，和
+互斥，+优先级更高。 #：八进制加前缀0，十六进制加0x/0X。对浮点则强制输出小数点。0和-同时出现时，-赢，零填充失效。这个组合很多人写过，看着没报错，结果就是不对齐。
width是最小字段宽度，不是截断长度。这是新手最容易搞反的一点：%5d打印123得到的是" 123"（前面补两个空格），而不是把123砍成两位。宽度不够时宽度参数完全不生效，该多长还是多长。宽度可以写成*，表示从参数列表里取一个int作为宽度，比如printf("%*d", 8, 42)等价于printf("%8d", 42)。这个技巧在写表格对齐时非常好用，因为列宽可以运行时算出来。
precision前面带点，含义随specifier变化，这一块是歧义最多的：
- 对
d/i/u/o/x/X：最小数字位数，不够就左侧补零。%.5d打42得到"00042"。 - 对
f/e：小数点后的位数，默认 6 位。%.2f打3.14159得到"3.14"（四舍五入）。 - 对
g/G：有效数字位数，默认 6 位。 - 对
s：最大输出字符数，超出的部分被截掉。%.3s打"abcdef"得到"abc"。 - 对
c：无意义，忽略。
精度写成.*时同样从参数取，printf("%.*s", 3, "abcdef")输出"abc"。这个写法我在解析协议字段时用得非常频繁——长度是运行时变量，天然适合用.*。
length修饰符是决定"参数在栈上占几个字节"的关键，写错了就是第 1 节那个 Bug：
| 修饰符 | 配合的说明符 | 实际期望的参数类型 |
|---|---|---|
hh | diux等 | int（内部按signed char/unsigned char解释） |
h | diux等 | int（内部按short解释） |
| 无 | di | int |
l | di | long |
ll | di | long long |
z | udx | size_t对应类型 |
j | du | intmax_t/uintmax_t |
t | d | ptrdiff_t |
L | feg | long double |
这里有个反直觉的点必须讲清楚：%hhd对应的参数类型仍然是int，不是char。原因是可变参数函数在传参时会做默认实参提升，char和short一律提升成int，float一律提升成double。所以printf家族里根本不存在%hf这种写法，浮点只用%f（内部接double）和%Lf（接long double）。hh和h的作用不是告诉函数"参数是 char"，而是告诉函数"请你把这个int截断成 char/short 再格式化"。理解这一点，%hhd和%d的区别就不会再混。
2.2 宽度、精度、标志位组合的实测结果
纯看规则容易晕，直接上代码跑一遍最清楚。下面这段我放在手边当速查：
#include <stdio.h> int main(void) { char buf[64]; sprintf(buf, "[%d]", 42); /* [42] */ sprintf(buf, "[%5d]", 42); /* [ 42] */ sprintf(buf, "[%-5d]", 42); /* [42 ] */ sprintf(buf, "[%05d]", 42); /* [00042] */ sprintf(buf, "[%+d]", 42); /* [+42] */ sprintf(buf, "[% d]", 42); /* [ 42] */ sprintf(buf, "[%.5d]", 42); /* [00042] */ sprintf(buf, "[%8.5d]", 42); /* [ 00042] */ sprintf(buf, "[%x]", 255); /* [ff] */ sprintf(buf, "[%#x]", 255); /* [0xff] */ sprintf(buf, "[%#08x]", 255); /* [0x0000ff] */ sprintf(buf, "[%o]", 8); /* [10] */ sprintf(buf, "[%#o]", 8); /* [010] */ sprintf(buf, "[%f]", 3.14159); /* [3.141590] */ sprintf(buf, "[%.2f]", 3.14159); /* [3.14] */ sprintf(buf, "[%08.3f]", -3.14159);/* [-003.142] */ sprintf(buf, "[%e]", 1234.5678); /* [1.234568e+03] */ sprintf(buf, "[%g]", 0.000012345); /* [1.2345e-05] */ sprintf(buf, "[%5.2s]", "abcdef"); /* [ ab] */ sprintf(buf, "[%-5c]", 'X'); /* [X ] */ return 0; }几个结果值得盯一下。[%08.3f]打-3.14159得到-003.142——零填充发生在符号之后，宽度算的是总长度（8 个字符），不是"小数点前几位"。这一点在做对齐的数字表格时特别重要，否则正负数混排会歪。
[%#08x]得到0x0000ff，前缀也算在宽度里。如果写%#8x（不带0），得到的是" 0xff"，空格在前缀前面。
[%5.2s]得到" ab"，先按精度截到 2 个字符，再按宽度右对齐补 3 个空格。这个"先截断再补齐"的顺序是固定的，不会反过来。
如果你想要"恰好 N 位、不足补零、超长截断"的效果（很多协议字段是这种要求），那sprintf的精度只管数字类，对字符串只有截断没有补齐，需要组合使用或者单独判断。这是后面第 3 节的一个实战点。
2.3 那些"看起来能用其实不能用"的写法
列几个我见过真实出事、或者自己年轻时写过的错误写法：
int16_t t = -5; sprintf(buf, "%d", t); /* 能跑，t 提升为 int，恰好对上 */ sprintf(buf, "%hd", t); /* 也行，按 short 解释 */ sprintf(buf, "%hhd", t); /* 错！会被截成 char，-5 还好，但 200 就变 -56 了 */ long v = 123456789L; sprintf(buf, "%d", v); /* 错！64 位平台上 long 是 8 字节，参数错位 */ size_t n = sizeof(buf); sprintf(buf, "%u", n); /* 错！64 位平台上 size_t 是 8 字节，必须 %zu */ float f = 1.5f; sprintf(buf, "%f", f); /* 形式上错，实际对：f 提升为 double */ sprintf(buf, "%Lf", f); /* 错！%Lf 要 long double，传 double 会读到垃圾 */ char *s = NULL; sprintf(buf, "%s", s); /* 未定义行为，某些实现打 "(null)"，别依赖 */最后那条NULL的情况值得单说。很多平台上的标准库实现确实会贴心地输出(null)，这让一批人以为这是标准保证的行为，于是大胆地把可能为空的指针直接丢给%s。它在另一种编译器或者另一种 C 库上就是段错误。稳妥写法是自己判空：
sprintf(buf, "%s", s ? s : "(null)");或者把默认值提到业务层，别让格式化函数去兜底。这一点在日志系统里尤其重要——你永远不知道某个字段什么时候会是空指针，而日志代码通常被包在断言之外，一崩就是整条链路。
再说%p。它的输出格式是实现定义的，可能带0x也可能不带，可能是 12 位也可能 16 位。所以拿%p的输出做字符串比较或者跨平台传参都是错的。要生成稳定的十六进制地址表示，用%#x配合强制转换到uintptr_t：
sprintf(buf, "0x%08lx", (unsigned long)(uintptr_t)ptr);uintptr_t在<stdint.h>里，是"能装下指针的整型"，用来做这种转换最稳。
3. 六种高频实战用法，代码可以直接抄
光讲语法没意思，下面这几种是我在实际项目里反复用的组合，每个都附上用途说明和踩过的坑。
3.1 数字转字符串：补零、定长、编号生成
最常见的场景：生成定长编号，比如000123。正确写法是%06d：
char id[16]; int seq = 123; sprintf(id, "%06d", seq); /* "000123" */如果序号可能超过 6 位怎么办？%06d是"至少 6 位"，超过就原样输出，得到"1234567"（7 位），不会截断也不会报错。如果你的下游系统要求必须正好 6 位，那就得自己判：
char id[16]; int seq = 1234567; if (seq >= 0 && seq <= 999999) { sprintf(id, "%06d", seq); } else { /* 超界处理：报错、归零、或者用别的编号策略 */ }这个判断很多人省，结果在跑了几百万条数据之后才炸，而且炸得很隐蔽——下游按定长去解析，多出来的字符全部错位一位。这类"边界值在很久之后才出现"的 Bug，最省事的做法是在写入处就设防。
负数补零会出问题：sprintf(id, "%06d", -123)得到"-00123"，长度确实是 6，但符号占了位。如果你的编号系统只允许正数，明确约束；如果允许负数，确认下游能正确解析前导负号。
3.2 十六进制、二进制与内存转储
十六进制是sprintf最实用的场景之一，因为手写转换又长又容易错：
unsigned char data[] = {0x01, 0xAB, 0xFF, 0x00}; char hex[32]; int off = 0; for (size_t i = 0; i < sizeof(data); i++) { off += sprintf(hex + off, "%02X", data[i]); } /* hex == "01ABFF00" */这里有个技巧值得说：用sprintf的返回值推进偏移。每次调用返回写了多少字符，累加即可。这个写法在拼接循环里非常自然，比手动算下标清晰。但要注意——它也是溢出风险最高的写法，因为sprintf从不告诉你"还剩多少"。加上限判断是必须的：
char hex[32]; int off = 0; const int cap = (int)sizeof(hex) - 1; for (size_t i = 0; i < sizeof(data) && off + 2 <= cap; i++) { off += sprintf(hex + off, "%02X", data[i]); } hex[off] = '\0';cap预留一个字节给结尾的'\0'，循环条件里检查off + 2 <= cap（每个字节输出 2 个字符）。这种"手动水位线"的写法在嵌入式里很常见，因为不想引入snprintf的开销，那就得自己把刀拿稳。
二进制没有标准说明符，只能手写。一个紧凑的写法是按位拼字符：
void to_bin(unsigned int v, int bits, char *out) { for (int i = bits - 1; i >= 0; i--) { *out++ = (v >> i) & 1u ? '1' : '0'; } *out = '\0'; }别用sprintf循环拼二进制，效率低得离谱（每个位一次格式串解析）。
3.3 浮点数的可控格式化：精度、舍入与那个经典陷阱
浮点格式化最容易被%.2f的"看起来对"骗过去。sprintf(buf, "%.2f", 0.125)得到"0.12"还是"0.13"？答案是看实现。因为0.125在二进制浮点里是精确可表示的，正好落在两个可舍入值中间，这时候采用哪种舍入规则（银行家舍入还是四舍五入）取决于 C 库。想要确定性结果，要么改用整数运算，要么明确规定用哪种舍入并在测试里覆盖。
金额类场景我一律建议用整数分做内部表示，只在展示时格式化：
long long cents = 12345; sprintf(buf, "%lld.%02lld", cents / 100, llabs(cents % 100)); /* "123.45" */这样避开浮点误差，也避开了舍入规则的不确定性。llabs在<stdlib.h>里，处理负数金额必须用，否则-12345分会被格式化成"-123.45"（cents/100 = -123，cents%100 = -45），前面的-123已经带符号了，后面再带一个就成了-123.-45。这是个非常隐蔽的坑，我第一次写金额格式化就栽在这上面，测试用例只测了正数，上线被财务发现负数全错。
科学计数法%e的默认精度也是 6 位，做协议编码时记得显式写%.6e，别依赖默认值——默认值你记得住，接手的人记不住，某天有人改了一下编译选项就变了。
3.4 字符串拼接与路径/日志构造
sprintf天然适合拼固定结构的字符串。比如构造一条日志：
sprintf(line, "[%s][%d][%s] %s", level_str, pid, module, msg);这类写法可读性极好，一眼能看出输出长什么样。但有两个必须注意的点。
第一，%s的长度完全由输入决定。如果module或msg是外部传入的，长度可能远超预期。防御性写法是用精度限制最大长度：
sprintf(line, "[%s][%d][%.64s] %.256s", level_str, pid, module, msg);%.64s会截断到 64 字符，超长部分丢弃。代价是丢信息，但比缓冲区溢出好一万倍。更好的做法是在更上层就限制字段长度，让格式化函数成为最后一道不带脑子的防线。
第二，路径拼接不要用sprintf强行拼分隔符。"/a/b" + "/" + "c"拼出"/a/b//c"在多数系统上能用，但在做字符串比较、去重、缓存 key 时就是两个不同的东西。要么用一个小的规范化函数处理连续斜杠，要么用专门的路径拼接库。
还有一个场景是"拼接可变数量的片段"，比如把多个参数拼成一条命令。这时候千万不要用一个固定大小的缓冲区无限sprintf追加，我见过的最惨的一次是日志系统在异常风暴下把自己写崩了，因为它对每条日志都做sprintf(buf + strlen(buf), ...)，缓冲区 4KB，异常一来瞬间写穿。第 4 节给正确写法。
3.5 表格化输出：用*动态算列宽
做命令行工具时，对齐输出是个刚需。写死宽度在数据变长之后会歪，正确做法是先扫一遍算最大宽度，再用*传进去：
const char *names[] = {"alpha", "b", "gamma_long_name"}; int w = 0; for (int i = 0; i < 3; i++) { int len = (int)strlen(names[i]); if (len > w) w = len; } char row[64]; for (int i = 0; i < 3; i++) { sprintf(row, "%-*s | %d", w, names[i], i); puts(row); }输出会是三行，名字部分左对齐、宽度统一。%-*s这个组合里-管左对齐，*取宽度，s是说明符，三个部分各司其职。这类用法在写小工具、调试面板时特别顺手，比手动printf一堆空格靠谱。
3.6 状态机、协议报文里的定长字段
自定义协议里常规定某字段固定 N 字节，比如版本号 4 位、状态 2 位。用sprintf生成时有几个注意点：
char ver[8]; sprintf(ver, "%04d", version); /* "0007" */如果version是int且可能为负，%04d会给-007（4 个字符，含负号）。协议里通常要求无符号，那就先用unsigned接收，或者写入前判负。另外，定长字段的接收端解析时，通常按"跳过前导零再转数字"，这要求发送端保证不能有空格——%4d是补空格，%04d才是补零，这两个写混了协议直接对不上，而且抓包看字符串很相似，容易排查很久。
4. 安全边界：sprintf的致命缺陷和snprintf的正确姿势
这一节是全文最重要的部分。如果你只记一件事，就记这个：sprintf没有任何方式知道目标缓冲区有多大，所以只要输出长度可能超过缓冲区，它就是内存越界写入。这不是"可能有问题"，是确定性的未定义行为。
4.1 溢出是怎么发生的：一次手算
char buf[8]; sprintf(buf, "%s", "hello world");这条语句会写 12 个字节（11 个字符加结尾'\0'）到一块 8 字节的空间里，多出来的 4 个字节会覆盖buf后面的栈内容。如果后面正好是返回地址或者另一个局部变量，程序行为就完全不可预测了。
更隐蔽的是这种：
char buf[16]; sprintf(buf, "ID:%d", user_id); /* user_id 是 int */int最大2147483647，11 位数字加"ID:"3 个字符加结尾 1 个，共 15 字节，刚好塞进 16 字节。看起来"设计得很紧凑"。但换成负数-2147483648就是 12 位数字，总共 16 字节，加结尾正好 17，溢出 1 字节。只溢出 1 个字节的 Bug 是最难查的——它可能刚好覆盖了一个对齐填充字节，什么都不影响；也可能覆盖了某个变量的最低位，导致偶发的、跟数据相关的诡异现象，测试环境复现不了，生产上偶发。
所以任何"我算过了够用"的自信，都建立在"所有输入都在我的预期范围内"这个假设上。而实际系统的输入永远会给你惊喜。
4.2snprintf的三个关键语义
int snprintf(char *str, size_t size, const char *format, ...);三个关键点，每个都有人误解：
第一，它最多写size个字节，其中包含结尾的'\0'。也就是说实际能容纳的字符数是size - 1。如果你写char buf[64]; snprintf(buf, sizeof(buf), ...)，最多写 63 个字符加结尾，安全。这是最常见的正确写法：第二个参数直接给sizeof(buf)，不要给sizeof(buf) - 1，不要给一个手动算出来的数字。
第二，返回值是"如果缓冲区无限大，本该写入多少字符"，而不是"实际写入了多少"。这一点几乎每个新手都会理解错。当发生截断时，返回值会大于等于size。所以判断是否被截断的正确写法是：
int n = snprintf(buf, sizeof(buf), "%s-%s", a, b); if (n < 0) { /* 编码错误 */ } else if ((size_t)n >= sizeof(buf)) { /* 发生了截断，内容不完整 */ }很多人写成n == sizeof(buf)，这只能捕获"正好截掉 0 个字符"的情况，漏掉绝大多数截断。还有人写成n > sizeof(buf)，漏掉边界。记法：n >= size即截断。
第三，size为 0 时什么都不写，但返回值仍然是被需要的长度。这意味着你可以传NULL和0来"探测长度"。这是sprintf无论如何都做不到的事情。
4.3 两段式动态长度：彻底解决缓冲区大小问题
当输出长度不确定且可能很大时，标准做法是先用snprintf(NULL, 0, ...)算出需要的长度，再动态分配：
#include <stdio.h> #include <stdlib.h> #include <stdarg.h> #include <string.h> char *fmt_alloc(const char *fmt, ...) { va_list ap; int need; char *out; va_start(ap, fmt); need = vsnprintf(NULL, 0, fmt, ap); va_end(ap); if (need < 0) return NULL; out = (char *)malloc((size_t)need + 1); if (!out) return NULL; va_start(ap, fmt); vsnprintf(out, (size_t)need + 1, fmt, ap); va_end(ap); return out; }这里用的是vsnprintf——snprintf的va_list版本，写可变参数的包装函数时必须用它。注意va_start要调用两次，因为va_list在第一次遍历之后状态就报废了，不能重复使用。
这个模式有几个细节：
malloc的大小是need + 1，多出来那个给'\0'。need本身不含结尾。- 第一段传
NULL, 0，在 C99 之后是标准保证的合法行为。C89 下不保证，如果你的工具链很老，得换成一个足够大的栈缓冲区去试。 - 两次格式化意味着一次额外开销。对于长度基本可预测的场景（比如拼接 3 个短字符串），直接用栈上 256 或 512 字节的缓冲区加一次
snprintf更快。 - 调用方必须
free。这是这类函数的通病，容易忘。
如果输出有上限（比如协议规定最长 4KB），更好的做法是一次snprintf到固定缓冲区，然后检查返回值判断是否截断，截断了就走错误处理而不是动态扩容。这样可以避免堆分配、避免内存碎片、避免忘记释放。我做嵌入式时基本都走这条路：宁可报错，不做动态分配。
4.4 一个完整的"安全拼接"小工具
把上面的规则揉成一个可以直接放进项目里的小函数：
/* 追加到 buf 的 off 位置，返回新的 off； * 若空间不足，返回 -1 表示失败，buf 内容保持为合法的以 '\0' 结尾的字符串 */ int safe_append(char *buf, size_t cap, int off, const char *fmt, ...) { va_list ap; int need; if (off < 0 || (size_t)off >= cap) return -1; va_start(ap, fmt); need = vsnprintf(buf + off, cap - (size_t)off, fmt, ap); va_end(ap); if (need < 0) return -1; if ((size_t)need >= cap - (size_t)off) { /* 截断了：把 off 位置恢复成 '\0'，保证字符串合法 */ buf[off] = '\0'; return -1; } return off + need; }用法：
char line[128]; int off = 0; off = safe_append(line, sizeof(line), off, "%s:", level); if (off >= 0) off = safe_append(line, sizeof(line), off, "%d:", pid); if (off >= 0) off = safe_append(line, sizeof(line), off, "%s", msg); if (off < 0) { /* 日志被截断或者字段太多，走降级路径 */ }这个模式的核心思想是：每次追加前都知道还剩多少空间，每次追加后都知道用掉了多少，任何一次失败就立即停止并保证缓冲区仍是合法字符串。这一套下来，越界和未终止字符串两个问题同时消失。
我个人的经验是，只要你在项目里立下"所有字符串拼接走snprintf或者这个safe_append"的规矩，并配一条代码扫描规则禁掉裸sprintf，字符串相关的崩溃能少掉一大半。这不是夸张，因为字符串越界在 C 项目的崩溃里占比确实高得惊人。
5. 常见问题与排查实录
这一节按症状查。遇到现象先对照，能省很多时间。
5.1 症状速查表
| 症状 | 最可能的原因 | 排查动作 |
|---|---|---|
| 程序崩溃、栈破坏提示 | 目标缓冲区太小，越界写入 | 用snprintf打印返回值，对比sizeof(buf) |
| 数值变成巨大负数或无关值 | 参数类型与修饰符不匹配，参数错位 | 逐项核对%ld/%zu/%lld与实际类型 |
| 字符串后半段是乱码 | 缓冲区没有正确'\0'结尾 | 检查是否手动算了下标并写越界 |
| 浮点打出来是 0.000000 或垃圾 | 传了float配%Lf，或精简库未启用浮点格式化 | 改%f；检查工具链是否裁剪了浮点支持 |
| 数字前面少了几位 | 用了%d接long long | 改%lld |
输出的十六进制没有0x | 忘了#标志 | 加#，注意它占用宽度 |
| 负数格式化后位置不对 | 零填充与符号的交互 | 用%08.3f观察实际输出 |
| 日志内容串到下一行 | 输入里含\n，或缓冲区未终止 | 对输入做转义/长度限制 |
| 某平台上完全正常，换平台就错 | long/size_t的宽度差异 | 改用int32_t/%zu/PRId64 |
表里最后一行值得展开。long在 32 位平台上是 4 字节，在 64 位 Linux/macOS 上是 8 字节，在 64 位 Windows 上又是 4 字节。这意味着同一份代码，%ld在三种平台上有两种不同的行为。跨平台代码里不要用long配%ld做跨平台数据，用<inttypes.h>里的宏：
#include <inttypes.h> int64_t v = 1234567890123LL; sprintf(buf, "%" PRId64, v); /* 展开成 %lld 或 %ld，看平台 */PRIu64、PRId32、PRIx16这些宏同理。第一次看到"%" PRId64这种字符串拼接的写法会觉得很怪，但它是标准做法，也是唯一稳妥的跨平台方案。
5.2 三个我真实踩过的坑
坑一：sizeof用在指针上。函数里写void f(char *buf) { snprintf(buf, sizeof(buf), ...); }，这里的sizeof(buf)是指针大小（4 或 8），不是缓冲区大小。这个错误编译器不会报，代码看着完全正常，只有在缓冲区大于 8 字节且实际输出超长时才炸。解决办法是把容量作为参数一起传进来，或者用带长度信息的结构体。这条规则要刻进肌肉记忆：凡是看到sizeof(指针变量)，一律当成 Bug 嫌疑。
坑二：snprintf返回值的误用。有一段代码这样写：
char buf[16]; int n = snprintf(buf, sizeof(buf), "%s", long_str); buf[n] = '\0'; /* 崩了 */作者以为n是"实际写入了多少"，所以手动补终止符。实际上n是"本该写入多少"，发生截断时n大于缓冲区大小，buf[n]直接越界。而且snprintf本来就会自己写'\0'，这行代码双重错误。这个坑的杀伤力在于：不截断时它能正常工作，只有长输入才崩，测试如果只用短字符串就永远发现不了。
坑三：多线程共享同一个格式化缓冲区。早期写的一个日志模块，为了省事用了一个static char logbuf[512]，多线程下两条日志同时格式化，内容互相覆盖，输出里出现半条 A 半条 B。sprintf本身没有全局状态，是可重入的，问题出在共享的缓冲区上。解决办法是把缓冲区放到栈上（每次调用独立），或者用线程局部存储。栈上分配 512 字节在多数场景下完全没问题，除非你在很深的递归里或者在中断栈很小的地方调用。
5.3 嵌入式环境的两个额外注意点
如果你在做单片机开发，还有两条几乎必踩：
浮点格式化被裁掉了。很多嵌入式工具链默认用的是精简版 C 库，为了省 Flash 空间，%f的支持根本没编进去。表现是%f打出来一个空、一个?、或者干脆链接报错。解决办法通常是加链接选项显式引入浮点格式化，或者干脆在代码里改成整数运算——把12.34转成1234再手动插小数点。第二种做法代码量大一点，但 Flash 占用和确定性都更好。
格式化函数在中断里要格外小心。如果主循环和中断都在用sprintf，而中断里用的缓冲区又恰好是全局的，那就是典型的重入问题。更隐蔽的是某些 C 库的浮点格式化内部会用到锁或者堆，在有中断抢占的环境下行为不可预测。我的做法是中断里只记录原始数据，格式化统一放到主循环做。
6. 性能边界与替代方案的选择
最后聊聊"要不要用"的问题。sprintf的开销主要来自两处：解析格式串（每调用一次就要扫一遍），以及各种边界判断和填充逻辑。对短格式串（10 个字符以内）来说，解析开销很小；格式串长、参数多的时候，开销会线性增长。
我做过一组粗略对比（同一台机器，循环一百万次，输出都是"id=123,val=456"这种量级）：
| 写法 | 相对耗时 | 说明 |
|---|---|---|
sprintf固定短格式串 | 1.0x | 基准 |
snprintf同格式串 | 1.2x ~ 1.5x | 多出的开销在长度检查 |
手写整数转字符串 +memcpy | 0.3x ~ 0.5x | 无格式串解析 |
| 手写 + 预计算长度 | 0.25x | 最省，但代码量大 |
结论很明确：只有在高频路径（比如每毫秒几百次的报文组装）上，手写转换才有意义。普通业务逻辑、日志输出、配置文件生成，用snprintf完全不构成瓶颈，反而省下大量维护成本。
真正需要警惕的不是"性能不够"，而是"用错场景"。有几种情况我会主动避开格式化函数：
一是只做纯数字转字符串且格式固定，手写几行更快也更可控，尤其是在没有完整 C 库的环境里。
二是输出内容是二进制数据，格式化函数处理'\0'会提前终止，%s在这里根本没意义，必须用memcpy。
三是格式化串来自外部输入。如果格式串本身可能是用户提供的，那除了%n的问题外，还可能触发非预期的类型读取，直接导致信息泄露或者崩溃。这种情况必须用白名单限定格式，或者干脆不用格式化函数，改成键值对替换。
还有一个容易被忽视的替代方案：能不用字符串就不用。很多拼接字符串的场合，其实是为了打日志或者拼报文，而这两件事都可以改成结构化处理——日志用结构化字段（key=value 列表，每个值单独格式化），报文用序列化库。结构化之后，每个字段的格式化都是独立可控的，长度上限可以逐字段约束，出了问题也好定位。这是架构层面的解法，比在函数层面反复纠结sprintf还是snprintf要有效得多。
6.1 一份可以直接落地的使用准则
压到最后，我在项目里推行的规则就这么几条，简单好记：
- 业务代码里禁止裸
sprintf，一律snprintf(buf, sizeof(buf), ...)。如果目标是堆上申请的，容量必须来自同一个变量，不能用魔数。 - 所有格式化返回值都要处理，至少判断
>= size的截断情况。日志代码可以降级（截断就截断），协议代码必须报错。 - 格式串里的
%s必须配精度限制，除非你百分之百确定输入长度。%.*s加运行时长度是最灵活的做法。 - 跨平台数据用
<inttypes.h>的宏，不用long硬扛。 %n全项目禁用，加进代码扫描规则。- 浮点只在展示层用，内部金额、时间、坐标一律整数。
6.2 最后一个小技巧
如果你需要在调试时快速确认某个格式化串会不会溢出，有个非常土但非常好用的办法：把snprintf的容量临时改成 1，然后把返回值打出来。返回值就是这条语句需要的完整长度（不含'\0'），拿它和你的实际缓冲区比一下，立刻知道有没有风险。
int need = snprintf(NULL, 0, "[%s][%d] %s", level, pid, msg); fprintf(stderr, "need=%d, cap=%zu\n", need, sizeof(buf));我在 code review 时经常让人加这么一行，跑一遍压测，把need的最大值抓出来，然后按最大值加安全余量定缓冲区大小。比拍脑袋定 256 还是 1024 靠谱得多，也比等线上出事再回来改便宜得多。缓冲区大小这种事，与其争论"应该够了吧"，不如让数据说话。
