项目标题里那个尖括号其实是个信号——<wchar.h>是 C 标准库里少数几个"看名字很温和、用起来很刺手"的头文件之一。我第一次真正被它咬到，是给一个用户昵称做展示截断：需求写着"超过 20 个字符就截断加省略号"，我顺手用了wcsncpy，本地测试全是英文，一切正常；上线后中文昵称开始出现一坨问号和半个汉字。那次排查从编码一路查到mbstate_t，最后发现问题根本不在库函数,而在我对"字符"这个概念的理解。这篇就把<wchar.h>从类型定义到转换函数、从流方向到实战封装，完整拆一遍。如果你写过带多语言文本的 C 程序，或者正准备接一个"要支持中文"的遗留项目，下面这些内容大概率能帮你省掉几个通宵。

1. wchar_t 不是"宽一点的 char"：尺寸、编码与可移植性

1.1 一个字节撑不住时的三种历史方案

char的问题不在于它小，而在于它同时承担了两个互相冲突的身份：既是"一个字节的内存单元"，又是"一个字符"。ASCII 时代这两个身份恰好重合，一个字符就是一个字节，皆大欢喜。一旦字符集扩展到成千上万个码位，这个重合就崩了，业界分出了三条路。

第一条是变长多字节编码，用多个char拼出一个字符，这就是 UTF-8 和各类传统双字节编码的做法；第二条是定长宽字符，让每个字符占固定字节数，用空间换"按下标直接访问第 n 个字符"的能力，wchar_t走的就是这条；第三条是彻底不碰字符，只当字节流处理，把编码问题推给上层。C 标准库选择在第一条和第二条之间架桥，<wchar.h>就是那座桥本身。

理解这个背景很关键：wchar_t从诞生起就不是为了"存储文本"设计的，它是为了"在内存里做字符级运算"设计的。所以你会看到它在文件 I/O、网络传输这些场景里几乎没人用，而在字符串比较、大小写转换、格式化的内部实现里出现得比较多。搞清楚这个定位，后面很多设计上的别扭感就都能解释了。

1.2 sizeof(wchar_t) 的分裂：2 字节与 4 字节

wchar_t在标准里的定义极其宽松：它是一个整数类型，能表示实现所支持的最大扩展字符集里的所有码位。注意，标准没说它多宽，也没说它用什么编码。现实里就分裂成了两派。

这个分裂带来的直接后果是：在 4 字节平台上wcslen(s)等于字符数，在 2 字节平台上它等于"码元数"，遇到表情符号、部分生僻汉字这类辅助平面字符时，一个字符会占两个wchar_t。你在一个平台上写的"取前 20 个字符"，换到另一个平台就可能把某个字符劈成两半，产生无法解析的孤立代理项。

我后来养成一个习惯：任何涉及wchar_t下标的代码，先问一句"这里数的是字符还是码元"。如果只是想截断显示，那就干脆别用wchar_t下标运算，走完整的码点解析路径，下面第 6 节会给出具体实现。

1.3 用 WCHAR_MIN/WCHAR_MAX 写"不假设尺寸"的代码

<wchar.h>里定义了WCHAR_MIN和WCHAR_MAX，还有WEOF和WINT_MIN/WINT_MAX。这些宏看起来像装饰品，实际上是你写可移植判断的唯一依据。比如判断一个wchar_t值是不是有效的 Unicode 码位，正确的写法不是硬编码0x10FFFF，而是先把平台宽度考虑进去：

#include <wchar.h> #include <limits.h> /* 判断 wc 是否落在一个"正常字符"范围内， * 排除孤立代理项和明显越界的值 */ static int is_valid_wchar(wchar_t wc) { if (wc < 0) return 0; /* 有符号实现下的负值 */ if (sizeof(wchar_t) == 2) { /* UTF-16 平台：代理项单独出现是非法序列 */ if (wc >= 0xD800 && wc <= 0xDFFF) return 0; return 1; } if (wc > 0x10FFFF) return 0; /* 超出 Unicode 码位上限 */ if (wc >= 0xD800 && wc <= 0xDFFF) return 0; return 1; }

注意if (wc < 0)这一句在wchar_t为无符号类型的实现上会被编译器警告"条件恒为假"。这不是错误，是无符号类型下的正常现象，但你的构建系统要是开了-Werror，就会卡在这里。稳妥的做法是先判断WCHAR_MIN < 0，再决定要不要做负值检查，或者干脆用wint_t来接参数——wint_t是专门为了能装下WEOF和所有wchar_t值而设计的类型，很多宽字符函数的参数和返回值都用它。

WEOF同样值得单独说一句。它不等于EOF，也不保证等于-1。你用wc = fgetwc(f)读文件，判断结束必须写wc == WEOF，写成wc == -1在部分实现上是能跑的，但那是在赌运气。

2. 把<wchar.h>拆开：类型、函数族与<string.h>的镜像关系

2.1 五个类型各自的职责边界

打开头文件看，核心类型其实就五个，但新手最容易在这几个类型之间来回猜。

wchar_t是宽字符本体，已经被说过了。wint_t是"能装下任意wchar_t和WEOF的整数"，fgetwc、towlower、iswalpha这些函数全用它，目的是让返回值可以同时表达"一个字符"和"结束/出错"。size_t是老熟人，各种长度参数和返回值都用它。

真正陌生的是mbstate_t和wctype_t。mbstate_t是一个完整对象类型，用来保存多字节编码转换过程中的状态，是后面第 3 节的主角；wctype_t和wctrans_t是宽字符分类和映射的句柄，由wctype()/wctrans()生成，再喂给iswctype()/towctrans()。后两个用得少，但当你需要自定义分类规则（比如判断某字符是否属于"标点"这个偏门类别）时它们就是入口。

mbstate_t有一个我必须强调的细节：它可以零初始化，也必须零初始化，但你不能用memcmp去比较两个状态是否相等。标准没保证这种比较有意义。判断"是否处于初始状态"要用mbsinit(&st)，这个函数是唯一被标准认可的方式。

#include <wchar.h> #include <string.h> mbstate_t st; memset(&st, 0, sizeof st); /* 唯一的正确初始化方式 */ /* ... 一通转换 ... */ if (mbsinit(&st)) { /* 当前处于初始状态，可以直接丢掉了 */ }

2.2 函数族分组与实际调用的优先级

<wchar.h>里的函数数量接近百个，按用途可以分成四组，这个分组决定了你遇到问题该去哪找答案。

第一组是字符串操作，wcslen、wcscpy、wcscat、wcschr、wcsstr、wmemset这些，行为和str*完全对应，唯一区别是元素宽度。第二组是数值转换，wcstol、wcstod、wcstoull，对应strtol那一套，它们内部会跳过前导空白、处理正负号、设置errno和endptr，行为规范一模一样。第三组是分类映射，iswalpha、iswspace、towupper这些，它们的共同点是依赖当前 locale，这个依赖后面会专门讲。第四组就是 I/O 和转换，fwprintf家族加上mbrtowc、wcrtomb、mbsrtowcs、wcsrtombs四兄弟。

实际用的时候优先级很清楚：能不用宽字符就别用，非要用优先用转换函数而不是宽字符 I/O。原因在后面的流方向一节会揭晓。

2.3 wcs* 与 str* 的映射表及"不完全等价"的地方

大部分wcs*函数和str*是一一对应的，可以直接按名字替换。但有几个地方表面类似、行为不同，我列出来。

wmemcpy和memcpy那个差异值得单独提醒一句。memcpy(dst, src, n)里的n是字节数，wmemcpy(dst, src, n)里的n是wchar_t元素个数。如果习惯性把sizeof(buf)直接丢进去，在 4 字节平台就会拷贝出四倍的数据，缓冲区直接溢出。这类错误在小数据量下可能不崩，等上线后数据变多才炸，排查起来非常痛苦。

3. mbstate_t 与 mbrtowc：多字节与宽字符之间的那道闸门

3.1 mbrtowc 四种返回值分别意味着什么

mbrtowc是整个头文件里最难啃、也最有价值的函数。签名是：

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

它尝试从s指向的最多n个字节里解出一个宽字符，写进*pwc，返回消耗的字节数。返回值有四种可能，每一种都对应一个完全不同的处理分支：

• 正数：成功解出一个字符，返回值是消耗的字节数（1 到n之间）。
• 0：s指向的那一个字节是空字符'\0'，此时*pwc被写成L'\0'，消耗 1 个字节。
• (size_t)-1：遇到非法序列，errno被设为EILSEQ，转换状态变为未定义。这是"数据坏了"。
• (size_t)-2：数据还不够，只读到了某个多字节字符的前半截，已经消耗掉n个字节，状态被更新。这是"数据还没到齐"，不是错误。

绝大多数人第一次写错，都是把-2当成了错误直接返回，结果处理分块读取的文件时,每个块边界都会丢掉一个字符。更隐蔽的是把0和"成功但字符是L'\0'"混为一谈——其实它们是一回事，但如果你在循环里只判断正数，就会漏掉结尾。

还有个小陷阱：ps传NULL是允许的，此时函数用一个内部静态状态。这在单线程小工具里很方便，但在多线程或者需要交错处理多个输入流的场景下会互相干扰。我的习惯是永远显式传一个自己管理的mbstate_t，从不依赖那个内部状态。

3.2 分块解码循环怎么写才不漏字符

搞清楚了四个返回值，循环就好写了。下面这段是我现在项目里实际在用的解码骨架，处理"从网络或者文件里一块一块读字节、转成宽字符"这个典型场景：

#include <wchar.h> #include <errno.h> #include <string.h> /* 从 src[0..len) 解出最多 cap 个宽字符写入 dst。 * st 由调用方持有，用于跨块保留状态。 * 返回实际消耗的字节数，出错返回 (size_t)-1， * *out 为写出的宽字符个数。 */ static size_t decode_block(const char *src, size_t len, wchar_t *dst, size_t cap, size_t *out, mbstate_t *st) { size_t used = 0, n = 0; while (used < len && n < cap) { wchar_t wc; size_t r = mbrtowc(&wc, src + used, len - used, st); if (r == (size_t)-1) { /* 非法序列：报告并放弃这一块 */ return (size_t)-1; } if (r == (size_t)-2) { /* 尾部是残缺序列，把这几个字节留到下一块 */ used = len; break; } if (r == 0) { /* 遇到 L'\0'，正常收尾 */ dst[n++] = L'\0'; used += 1; break; } dst[n++] = wc; used += r; } *out = n; return used; }

调用方要注意：如果返回的used小于传入的len，说明尾部有-2的情况，那么src + used到src + len这几个字节需要拷贝到下一块缓冲区的最前面，再和新读到的数据拼起来继续解。这个"残留字节前移"的逻辑是整段代码的核心，漏了它就会在块边界处随机丢字符，而且因为只在特定块大小下复现，测试极难覆盖。

mbstate_t跨块保持的意义还在于：UTF-8 是无状态编码，mbstate_t其实一直是初始态，怎么做都没事；但如果你处理的是某些有状态的遗留编码，一个转义序列可能跨块，那时mbstate_t就是唯一的救命稻草。所以哪怕眼下用不到，也建议按有状态的方式来写，成本几乎为零。

3.3 反向编码 wcrtomb 与移位状态编码的坑

反方向是wcrtomb：

size_t wcrtomb(char *s, wchar_t wc, mbstate_t *ps);

把一个宽字符编码成多字节序列，返回写入的字节数（最多MB_CUR_MAX），失败返回(size_t)-1。参数里那个wc传L'\0'是特殊用法：它会把状态重置回初始态，并写入一个空字节。所以正确收尾的写法是显式编码一次L'\0'，而不是直接s[n] = '\0'——前者能保证状态被正确复位，在有状态编码下这个区别是致命的。

MB_CUR_MAX定义在<stdlib.h>里，它告诉你当前 locale 下一个字符最多编码成多少字节。缓冲区按它开是安全的：

#include <stdlib.h> #include <wchar.h> #include <string.h> /* 把宽字符串编码成多字节，写入 dst（容量 cap） */ static size_t encode_wstr(const wchar_t *src, char *dst, size_t cap) { mbstate_t st; size_t used = 0; const wchar_t *p = src; memset(&st, 0, sizeof st); for (; *p; p++) { size_t r = wcrtomb(dst + used, *p, &st); if (r == (size_t)-1) return (size_t)-1; if (used + r >= cap) return (size_t)-1; /* 留一格给结尾 */ used += r; } /* 用 wcrtomb 编码 L'\0' 来复位状态并写入结尾 */ if (wcrtomb(dst + used, L'\0', &st) == (size_t)-1) return (size_t)-1; return used; }

注意那个used + r >= cap的判断，用>=而不是>，是为了给结尾的空字节留位置。这种差一错误在编码函数里特别常见，因为编码后的长度是不确定的，很容易在最后一步写越界。

3.4 mbsrtowcs 一次搞定的场景与它省不掉的前提

如果输入是完整的、以空字符结尾的多字节串，用mbsrtowcs比手写循环省事得多：

size_t mbsrtowcs(wchar_t *dst, const char **src, size_t len, mbstate_t *ps); size_t wcsrtombs(char *dst, const wchar_t **src, size_t len, mbstate_t *ps);

它们的特点是会一路转换下去，直到遇到空字符或者写满len。这带来一个好用的副作用：传dst = NULL、len = 0，它就只做长度计算，不写任何东西，相当于一次"试算"。所以"先算长度再分配"这个套路可以这么写：

#include <stdlib.h> #include <wchar.h> #include <string.h> wchar_t *dup_mbs_to_wcs(const char *s) { mbstate_t st; const char *p = s; size_t need; wchar_t *buf; memset(&st, 0, sizeof st); need = mbsrtowcs(NULL, &p, 0, &st); /* 试算，不写内存 */ if (need == (size_t)-1) return NULL; /* 非法序列 */ buf = malloc((need + 1) * sizeof *buf); if (!buf) return NULL; memset(&st, 0, sizeof st); /* 状态必须重新初始化 */ p = s; if (mbsrtowcs(buf, &p, need + 1, &st) == (size_t)-1) { free(buf); return NULL; } return buf; }

两次调用之间必须重置mbstate_t，因为第一次调用已经把状态推进过了。这个细节我见过不止一个人漏掉，在无状态编码下不会出问题，换到有状态编码上就会得到莫名其妙的结果，而且极难定位。另外src参数是"指向指针的指针"，转换过程中会被推进到停下来的位置，这个设计经常让不熟的人写错类型。

4. locale 不是可选项：setlocale 决定的整条转换链行为

4.1 不调 setlocale 时中文为何直接报 EILSEQ

C 程序启动时，locale 默认是"C"，这个 locale 下字符集基本等价于 ASCII，多字节编码只认单字节。后果是：任何超过 0x7F 的字节丢给mbrtowc，直接返回(size_t)-1，errno设成EILSEQ。

我第一次遇到的症状特别有迷惑性：英文正常，中文全都是转换失败，同一份代码在别人机器上又跑得好好的。折腾半天才想起来，那个"别人机器"的启动脚本里有一行setlocale。所以现在我看到"转换函数没报错但中文全是问号"这类描述，第一反应就是去搜代码里有没有setlocale。

正确的初始化方式是在程序入口附近显式设置：

#include <locale.h> int main(void) { /* 使用环境变量里的 locale，这是我们想要的 */ if (setlocale(LC_ALL, "") == NULL) { /* 设置失败，退回到一个保守的默认值 */ setlocale(LC_ALL, "C.UTF-8"); } /* ... 业务代码 ... */ return 0; }

setlocale(LC_ALL, "")里那个空字符串是关键，它的意思是"读取环境变量里配置的 locale"。写成"en_US.UTF-8"之类硬编码值的问题在于：目标机器上不一定装了那个 locale，设置会失败，而且失败是静默的——setlocale返回NULL，如果你不检查，后面所有转换都会在"C"locale 下偷偷跑偏。

4.2 "C"、""、"C.UTF-8" 三者的实测差异

这三个值经常被混用，实际行为差别不小。

我实测过的结论是："C.UTF-8"在多数现代 POSIX 环境里可用，是"我想要 UTF-8 但不想被用户环境影响"时的好选择；但它不是标准要求的，某些精简过的运行环境里设不上。所以稳妥的写法是先试""，再试"C.UTF-8"，最后退回"C"并接受只能处理 ASCII 的现实。

还有一个容易忽略的点：locale 分类是独立的。LC_CTYPE管字符分类和转换，LC_COLLATE管排序，LC_TIME管时间格式。你要是只设LC_CTYPE，那wcscoll和wcsftime依然在"C"环境下工作，中文排序会按码位排，日期会输出英文缩写。用LC_ALL一把梭虽然粗暴，但至少不会漏。

4.3 setlocale 的全局性副作用与多线程下的规避

setlocale改的是进程级全局状态，这一点在多线程程序里是隐患。你在线程 A 里改 locale，线程 B 正在跑的mbrtowc会跟着变，转换结果就可能错乱。标准库对此的态度是"自己管好"。

我的规避策略有三条，按成本从低到高。第一，在main最开始、任何线程创建之前就把 locale 定死，之后全程不再改，这能解决九成问题。第二，把依赖 locale 的字符串操作集中到一个专用的工作线程，其他线程不碰。第三，如果确实需要在不同 locale 间切换（比如多语言排版），那就别用mbstate_t相关的标准接口了，直接用能显式指定编码的第三方转换库，把 locale 这个全局变量彻底绕开。

顺便说一个相关的问题：towupper、iswalpha这些分类函数同样受LC_CTYPE影响。在"C"locale 下，iswalpha(L'中')返回 0，因为它根本不知道"中"是个字母。这类"看起来取反了"的行为，八成都是 locale 没设对。

5. 宽字符 I/O 的流方向：fwide 与 fwprintf 的红线

5.1 一个流只能有一个方向：混用的后果

C 标准对一个FILE *的使用方向有硬性规定：一旦对某个流做了字节 I/O（比如fgetc、fprintf、fread），它就是"字节方向"；一旦做了宽字符 I/O（fgetwc、fwprintf、fread之外的宽版本），它就是"宽字符方向"。方向确定后不能再改，除非中间调用了fflush或者文件定位函数，而且中间没有ungetwc残留。

这个规则听起来很学术，实际踩起来很实在：你在同一个FILE *上先fprintf写了个头部，再fwprintf写正文，标准说这是未定义行为。在某个实现上它可能正好工作，换个实现就可能缓冲区错乱。

fwide就是查询和设置方向的函数：

#include <stdio.h> #include <wchar.h> int fwide(FILE *stream, int mode);

mode > 0表示"请设为宽字符方向"，mode < 0表示"请设为字节方向"，mode == 0表示"我只查询"。返回值大于 0 是宽字符方向，小于 0 是字节方向，等于 0 表示"还没定，现在设也行"。

于是有个常见的写法可以强制某个流走宽字符：

if (fwide(fp, 1) < 0) { /* 这个流已经是字节方向了，改不回来了 */ fprintf(stderr, "stream already byte-oriented\n"); }

我的经验是：能不开宽字符 I/O 就别开。格式化和输出完全可以在宽字符域内用swprintf拼好，再统一编码成 UTF-8 用fputs写出去。这样流方向永远是字节方向，避开了所有方向冲突，同时也避开了宽字符 I/O 在不同平台上实现差异带来的麻烦。

5.2 fwprintf 里 %s 和 %ls 的含义与 printf 相反

这是一个反复出现在代码评审里的问题。printf里%s期望char *，%ls期望wchar_t *。但在fwprintf里，因为目标流是宽字符的，%s的默认含义变成了wchar_t *，而%ls反而才是"普通字符串"。

我在项目里的做法是：只要写fwprintf，就在旁边加注释把参数类型写清楚，或者干脆不用fwprintf，用swprintf拼好再输出。这不是懒，是因为这个反向规则太容易在维护期被改坏——改的人看到%s直觉上会以为是char *，编译能过，运行就崩。

5.3 swprintf 截断返回负值：与 snprintf 最容易被忽略的分歧

snprintf的契约大家都熟：返回"如果有足够空间本该写入的字符数"，截断时返回一个大于缓冲区的值，所以你可以拿返回值来判断够不够。

swprintf完全不是这样。标准规定：如果n是 0，或者写入会超过n（含结尾空字符），返回负值，且缓冲区内容不确定。也就是说，截断时你拿不到"还差多少"这个信息。

#include <stdio.h> #include <wchar.h> wchar_t buf[16]; int r = swprintf(buf, 16, L"%ls", L"一段特别特别长的中文文本"); if (r < 0) { /* 要么是编码错误，要么是空间不够，两者分不出来 */ }

这就是个实实在在的功能缺失。我的应对办法是先估算或者先格式化到一个动态分配的更大缓冲区里，确认长度之后再决定是否截断：

static wchar_t *safe_swprintf(const wchar_t *fmt, ...) { va_list ap; wchar_t *buf = NULL; size_t cap = 128; va_start(ap, fmt); for (;;) { va_list ap2; int r; wchar_t *nb = realloc(buf, cap * sizeof *nb); if (!nb) { free(buf); va_end(ap); return NULL; } buf = nb; va_copy(ap2, ap); r = vswprintf(buf, cap, fmt, ap2); va_end(ap2); if (r >= 0) break; /* 成功 */ if (cap > (1u << 20)) { /* 防御性上限，防止死循环 */ free(buf); va_end(ap); return NULL; } cap *= 2; } va_end(ap); return buf; }

用"失败就翻倍重试"这个策略，是因为swprintf失败时无法区分"空间不够"和"编码错误"。翻倍到一定上限还失败，那就认定是后者。这个上限很重要，我见过有人的代码因为编码错误而无限翻倍，最后malloc失败崩溃的。

5.4 输出到终端时全角字符占两列的对齐处理

这个问题严格说不属于<wchar.h>的范畴，但处理宽字符输出必然撞上。中文、日文这类全角字符在等宽字体终端里占两个字符格，而wcslen只数个数。所以你要对齐一个中英混排的表格，用wcslen算出来的宽度根本不准。

标准 C 没有解决办法。POSIX 提供了wcwidth，给它一个wchar_t返回显示宽度，给人看的字符返回 1，全角返回 2，组合字符返回 0，控制字符返回 -1：

#include <wchar.h> #include <wctype.h> /* 计算一个宽字符串在终端里的显示宽度 */ static int display_width(const wchar_t *s) { int w = 0; for (; *s; s++) { int cw = wcwidth(*s); if (cw > 0) w += cw; /* 负值和 0 都不占位 */ } return w; }

用display_width做填充对齐，中英混排的表格才真的能对齐。wcwidth不是标准 C 的成员，但主流 POSIX 环境都有，配上<wchar.h>一起用很自然。要注意它同样受 locale 影响，"C"locale 下所有非 ASCII 都返回 -1，你的宽度计算会全盘错位——又是一个必须先把 locale 设对的例子。

6. 实战封装：按"字符"而不是"字节"截断与统计

6.1 需求拆解：截断点不能落在半个字符上

回到开头那个昵称截断的需求。真正的约束有三条：第一，截断后不能出现乱码，也就是不能切在多字节序列中间；第二，不能切在 UTF-16 代理对中间，否则会产生孤立代理项；第三，最好能按显示宽度而不是字符数来算，因为中英混排时"20 个字符"的视觉宽度差异巨大。

这三条里前两条是硬性正确性要求，第三条是体验要求。我最后的设计是分两层：底层做一个"安全的宽字符串前缀提取"，保证不切碎任何字符；上层再决定用字符数还是显示宽度来定截断点。

关键是要先把多字节输入完整解码成宽字符，做截断运算，再编码回去。中间那一步"在宽字符域内做运算"正是<wchar.h>的价值所在——如果全程在字节域里操作，你就得自己解析 UTF-8 的续字节标记，那才是真的麻烦。

6.2 完整实现与三组测试

#include <stdio.h> #include <stdlib.h> #include <string.h> #include <wchar.h> #include <wctype.h> /* UTF-16 平台上的代理项判断；UTF-32 平台上永远返回 0 */ static int is_high_surrogate(wchar_t c) { return sizeof(wchar_t) == 2 && c >= 0xD800 && c <= 0xDBFF; } /* 取宽字符串的前 n 个"码点"，不切断代理对。 * 返回值需要 free。 */ static wchar_t *wcs_prefix(const wchar_t *src, size_t n) { size_t i = 0, chars = 0; wchar_t *out; /* 先数出实际要取多少个 wchar_t 元素 */ while (src[i] && chars < n) { if (is_high_surrogate(src[i]) && src[i + 1]) i += 2; /* 整个代理对一起取 */ else i += 1; chars++; } out = malloc((i + 1) * sizeof *out); if (!out) return NULL; wmemcpy(out, src, i); out[i] = L'\0'; return out; } /* 完整流程：多字节 -> 宽字符 -> 截断 -> 多字节 */ char *truncate_mbs(const char *input, size_t max_chars, const char *ellipsis) { mbstate_t st; const char *p = input; size_t need, prefix_len; wchar_t *wide, *prefix, *joined; char *result; memset(&st, 0, sizeof st); need = mbsrtowcs(NULL, &p, 0, &st); if (need == (size_t)-1) return NULL; wide = malloc((need + 1) * sizeof *wide); if (!wide) return NULL; memset(&st, 0, sizeof st); p = input; if (mbsrtowcs(wide, &p, need + 1, &st) == (size_t)-1) { free(wide); return NULL; } if (wcschr(wide, L'\0') - wide <= (ptrdiff_t)max_chars) { /* 不需要截断，原样返回 */ free(wide); result = malloc(strlen(input) + 1); if (result) memcpy(result, input, strlen(input) + 1); return result; } prefix = wcs_prefix(wide, max_chars); if (!prefix) { free(wide); return NULL; } /* 拼上省略号 */ prefix_len = wcslen(prefix); joined = malloc((prefix_len + 8) * sizeof *joined); if (!joined) { free(prefix); free(wide); return NULL; } memset(&st, 0, sizeof st); wmemcpy(joined, prefix, prefix_len); joined[prefix_len] = L'\0'; if (ellipsis) { size_t elen = strlen(ellipsis); wchar_t *ew = malloc((elen + 1) * sizeof *ew); if (ew && mbstowcs(ew, ellipsis, elen + 1) != (size_t)-1) { size_t room = prefix_len + elen; wmemcpy(joined + prefix_len, ew, elen + 1); (void)room; } free(ew); } /* 编码回多字节 */ memset(&st, 0, sizeof st); need = wcsrtombs(NULL, (const wchar_t **)&(const wchar_t *){joined}, 0, &st); /* 上面这一行写法过于取巧，实战中建议用显式变量，见下文 */ free(joined); free(prefix); free(wide); (void)need; return NULL; }

上面最后那段编码部分我故意保留了一个反面示范。实际写的时候，wcsrtombs的第一个参数是char *，第二个是const wchar_t **，需要传入一个可以推进的指针变量的地址，用复合字面量取地址这种做法虽然能编过，可读性极差，而且容易在维护时出错。正确写法是老老实实声明一个中间变量：

const wchar_t *wp = joined; memset(&st, 0, sizeof st); need = wcsrtombs(NULL, &wp, 0, &st); if (need == (size_t)-1) { /* 编码失败 */ } result = malloc(need + 1); if (result) { wp = joined; memset(&st, 0, sizeof st); wcsrtombs(result, &wp, need + 1, &st); }

测试的时候我准备了三个用例，都很有代表性：

第三个用例是最容易出问题的。在 4 字节平台上的表现和在 2 字节平台上的表现不同，所以我一般会在两套环境里各跑一遍，确认代理对判断那段逻辑真的生效。如果只在单一平台上测过，那段is_high_surrogate里的sizeof(wchar_t) == 2条件根本不会被触发到，等于没测。

6.3 实测中暴露的三个问题

第一个问题是mbsrtowcs的试算和实际转换之间状态必须重置。我在初版里忘了第二次memset(&st, 0, sizeof st)，在 UTF-8 环境下完全没问题，因为 UTF-8 是无状态的，mbstate_t是不是初始态都无所谓。但这段代码被复用到另一个处理遗留编码的模块后就出了偏差，查了很久才发现根因。这类"在无状态编码下测不出来"的 bug 是最阴的。

第二个问题是省略号本身的编码。我一开始直接把"..."三个点当成字节拼在末尾，结果中文截断后如果刚好在一个多字节字符的边界，直接拼字节就会拼到半个字符里。后来改成先mbstowcs把省略号转成宽字符，在宽字符域里拼接，最后统一编码回去。这里还有个隐藏前提：省略号的字节表示必须能被当前 locale 正确解码，如果传入的是 UTF-8 的"…"而 locale 是别的编码，mbstowcs会失败。所以我的实现里对mbstowcs失败做了降级处理，退化成不追加省略号。

第三个问题是缓冲区预留量不够。我在拼接的时候按prefix_len + 8开的数组，看起来够用，但如果调用方传进来的省略号很长（比如传了"，以及更多内容"），就会溢出。后来改成先算prefix_len + ellipsis_wchars + 1再分配。这种"按经验值预留"的写法在 demo 里没事，一进生产环境就被各种真实参数打穿，所以我现在写这类函数一律精确计算，不用估算。

7. 还要不要用 wchar.h：与 uchar.h、第三方库的取舍

7.1 wchar_t 身上的三个历史包袱

现在回头看，<wchar.h>有三个绕不过去的结构性问题。

第一是尺寸不统一。2 字节和 4 字节的分裂导致"一个wchar_t等于一个字符"这个最核心的假设只在部分平台成立。任何跨平台的宽字符串操作都必须处理代理对，代码复杂度直接翻倍。

第二是和 locale 强绑定。所有转换函数的行为都取决于进程全局的 locale 状态，这在单进程单线程时代不是问题，在多线程服务端程序里就是雷。你不能同时让两个线程用不同编码做转换，除非绕开标准接口。

第三是宽度语义缺失。终端显示、排版这类真实需求需要考虑"全角占两列""组合字符不占位"，而<wchar.h>里完全没有这个概念，得靠 POSIX 的wcwidth补，而它又依赖 locale。

这些不是实现质量的锅，是 1990 年代设计时的取舍。当时的设计者已经尽力了，只是没想到三十年后的文本处理会这么复杂。

7.2 三种方案横向对比

C11 引入了<uchar.h>，提供char16_t、char32_t和带状态的转换函数mbrtoc16、c16rtomb、mbrtoc32、c32rtomb。它的关键改进是把编码宽度写死在类型名里：char16_t一定是 16 位，char32_t一定是 32 位，不再有"取决于平台"的问题。转换函数也强制要求传mbstate_t，不再提供NULL用内部状态的那个后门。

第三方库的优势在于可以显式指定"从 UTF-8 转到 UTF-32"，不经过 locale，线程间互不干扰，而且通常带完整的代理对、组合字符、非法序列处理。代价是多一个依赖，构建系统要改。

我的实际选型判断是这样的：如果项目本身已经在用某个文本处理库，直接用它，别为了"少一个依赖"去和<wchar.h>较劲；如果是纯 C 的轻量工具、只处理单一种类的输入、运行环境可控，<wchar.h>够用，用不着引入额外依赖；如果是新写的、需要长期维护的、C11 可达的项目，我倾向用<uchar.h>，图的就是那个"类型宽度固定"的确定性。

7.3 我在不同项目的选型判断

有个具体的判断方法我觉得挺实用：看这个程序的文本数据从哪来、到哪去。

如果输入输出都在进程内部，那用wchar_t做中间表示没什么风险，反正不落地。如果输入输出要跨进程、跨网络、跨文件，那编码边界上就必须非常小心，这时候wchar_t反而是个负担——你会不断在"内部宽字符"和"外部 UTF-8"之间来回转，每次转换都是出错机会。

所以我现在的主流做法是"内部统一 UTF-8，只在需要的局部用宽字符"。具体来说：所有字符串存储、传递、持久化都用 UTF-8 的char *；只有在需要做"按字符切分""大小写转换""显示宽度计算"这些必须理解字符语义的操作时，临时转成宽字符处理，处理完立刻转回去；转换点集中在几个封装函数里，不散落在业务代码中。

这个策略的好处是边界清晰：<wchar.h>的复杂度和它的坑都被关在几个函数里，业务代码完全不用知道mbstate_t是什么东西。坏处是多了一次转换的开销，但实测下来对绝大多数应用完全无感，只有在处理超大文本时值得优化。

最后分享一个我用了很多年的小检查：任何涉及宽字符的模块，上线前我会故意在"C"locale 下跑一遍全量测试。如果全过了，说明这段代码根本没用上 locale 提供的能力，要么是有冗余逻辑，要么是有 bug 被掩盖了。因为正常工作的宽字符代码，在"C"locale 下处理非 ASCII 输入时应该出问题。测试能过反而说明测例没覆盖到真正的多语言场景，这种反向验证帮我抓到过好几次"看起来测了其实没测"的假覆盖。