1. 为什么我要在嵌入式项目里手搓 UTF-8 处理
做单片机或者裸机开发的朋友大概率都遇到过这个场景：设备要显示中文，屏幕驱动只给你一个像素一个像素写点的接口，字库文件是现成的，但字库的索引方式是按 Unicode 码点来的。这时候你从串口或者 Flash 里读出来的一串字节，是 UTF-8 编码的，你得先把它解码成 Unicode 码点，才能去字库里查字形。问题来了，很多轻量级嵌入式工程根本不想引入第三方库，像什么 utf8proc、iconv 这类东西，要么体积大，要么依赖操作系统接口，在资源受限的环境里根本跑不起来。
我这个项目就是在这样的背景下动手的。目标很明确：不引入任何第三方库，纯 C 语言实现一套 UTF-8 编解码和配套的工具函数，代码量控制在几百行以内，能直接在单片机上跑，也能在 PC 端做单元测试。涉及的核心关键词就是 C语言、UTF-8、工具函数这三个。说白了，我要解决的就是“给我一串 UTF-8 字节，我还你一个 Unicode 码点数组；给我一个码点，我还你 UTF-8 字节序列”这件事，顺带把字符串长度统计、子串截取、合法性校验这些周边工具函数一并做了。
这篇文章适合谁看？如果你正在做嵌入式显示、串口协议解析、文件系统路径处理，或者单纯想搞清楚 UTF-8 的位运算到底怎么玩，那这篇内容应该对你有用。我不打算讲太多 Unicode 的历史，直接从字节层面拆开讲，把每一个位是怎么拼出来的说清楚，代码可以直接抄。
2. UTF-8 编码原理拆解与设计思路
2.1 UTF-8 的变长编码规则到底怎么理解
UTF-8 的本质是一种变长编码，它用 1 到 4 个字节来表示一个 Unicode 码点。为什么是变长？因为 Unicode 码点的范围是从 0x0000 到 0x10FFFF，一共 110 多万个码点，如果全部用 4 字节定长表示，那 ASCII 字符也要占 4 个字节，浪费太严重。UTF-8 的设计巧妙之处在于，它让 ASCII 字符（0x00 到 0x7F）保持单字节，和传统的 ASCII 编码完全兼容，同时用多字节序列表示更大的码点。
具体规则是这样的：单字节的最高位是 0，剩下 7 位就是码点值。多字节序列里，第一个字节的高位有 n 个 1 后面跟一个 0，n 表示这个序列总共占几个字节，剩下的位用来存码点的高位；后续字节统一以 10 开头，剩下 6 位存码点的低位。这个设计的好处是，你从任意一个字节的位置开始读，只要看它的高位模式，就能判断它是首字节还是后续字节，不会出现歧义。
我用一个具体的例子来说明。汉字“中”的 Unicode 码点是 U+4E2D，二进制是 0100 1110 0010 1101，一共 15 位。15 位需要 3 个字节来装，因为 2 字节最多装 11 位（5+6），3 字节可以装 16 位（4+6+6）。所以“中”的 UTF-8 编码是 3 字节：第一个字节格式是 1110xxxx，填入码点高 4 位 0100，得到 11100100，也就是 0xE4；第二个字节格式是 10xxxxxx，填入中间 6 位 111000，得到 10111000，也就是 0xB8；第三个字节填入低 6 位 101101，得到 10101101，也就是 0xAD。合起来就是 E4 B8 AD，这就是“中”字的 UTF-8 字节序列。
2.2 为什么选择手写而不是用现成库
在嵌入式环境里，第三方库的引入成本比 PC 端高得多。首先是体积问题，很多 UTF-8 库为了兼容各种边界情况，代码量动辄几千行，编译出来的二进制体积可能比我的整个应用还大。其次是依赖问题，有些库依赖 malloc、locale、宽字符接口，这些在裸机环境里要么没有，要么行为不一致。再就是可控性问题，手写的代码我能精确控制每一个分支的行为，出了 bug 也好定位，不用去翻别人的源码。
还有一个很现实的原因：UTF-8 的编解码逻辑本身并不复杂，核心就是位运算和查表，一个熟练的 C 程序员半天就能写出来并测通。与其花时间去移植和裁剪第三方库，不如直接手写一套，代码量小、可读性高、维护成本低。当然，前提是你得把边界情况处理干净，比如非法序列、超长编码、代理对区间这些坑，后面我会详细讲。
2.3 整体模块划分与接口设计
我把整个模块分成三个部分：编解码核心、工具函数、测试用例。编解码核心提供两个基础函数，一个负责把 UTF-8 字节序列解码成码点，一个负责把码点编码成 UTF-8 字节序列。工具函数建立在编解码核心之上，提供字符串长度统计、子串截取、合法性校验、码点遍历这些常用操作。测试用例覆盖各种边界情况，包括 ASCII、2 字节、3 字节、4 字节、非法序列、截断序列等。
接口设计上我遵循几个原则：第一，不依赖任何标准库之外的设施，只用 stdint.h 里的定长类型；第二，所有函数都是可重入的，不维护全局状态；第三，返回值明确区分成功和失败，失败时给出具体的错误码；第四，输入输出缓冲区由调用者提供，函数内部不分配内存。这样做的好处是，这套代码可以直接放进中断服务程序里跑，也可以在多线程环境里安全使用。
3. 核心编解码函数的实现细节
3.1 解码函数：从字节流到码点
解码函数的签名我设计成这样：
int utf8_decode(const uint8_t *src, size_t src_len, uint32_t *codepoint, size_t *consumed);src 是输入字节流，src_len 是可用字节数，codepoint 是输出码点，consumed 是实际消耗的字节数。返回值 0 表示成功，负数表示错误码。为什么要传 src_len？因为在网络协议或者文件读取场景里，你拿到的缓冲区可能不完整，必须防止越界读取。
解码的第一步是看首字节的高位模式。如果首字节小于 0x80，那就是单字节 ASCII，直接返回。如果首字节在 0xC0 到 0xDF 之间，说明是 2 字节序列，需要再读 1 个后续字节。0xE0 到 0xEF 是 3 字节，0xF0 到 0xF7 是 4 字节。这里有个细节要注意：0xC0 和 0xC1 是非法首字节，因为它们会导致超长编码（overlong encoding），也就是用 2 个字节表示一个本可以用 1 个字节表示的码点，这是安全漏洞的常见来源，必须拒绝。
后续字节的校验也很关键。每个后续字节必须满足 (byte & 0xC0) == 0x80，也就是高两位是 10。如果不符合，说明序列被截断或者损坏了。我在实现里会把所有后续字节先校验一遍，全部通过后再做位拼接，这样避免部分写入输出参数。
位拼接的过程是这样的：以 3 字节为例，首字节的低 4 位是码点的 bit 15 到 bit 12，第二个字节的低 6 位是 bit 11 到 bit 6，第三个字节的低 6 位是 bit 5 到 bit 0。拼接的时候用移位和或运算：
uint32_t cp = (uint32_t)(src[0] & 0x0F) << 12; cp |= (uint32_t)(src[1] & 0x3F) << 6; cp |= (uint32_t)(src[2] & 0x3F);拼接完之后还要做范围校验。2 字节序列的码点必须大于等于 0x80，否则就是超长编码。3 字节序列的码点必须大于等于 0x800。4 字节序列的码点必须大于等于 0x10000，且不能超过 0x10FFFF。另外，0xD800 到 0xDFFF 是代理对区间，UTF-8 里不允许出现，遇到也要拒绝。
3.2 编码函数：从码点到字节流
编码函数的签名是：
int utf8_encode(uint32_t codepoint, uint8_t *dst, size_t dst_len, size_t *written);dst 是输出缓冲区，dst_len 是缓冲区大小，written 是实际写入的字节数。返回值同样是 0 成功、负数失败。
编码的第一步是判断码点范围。小于 0x80 的走单字节分支，小于 0x800 的走 2 字节分支，小于 0x10000 的走 3 字节分支，小于等于 0x10FFFF 的走 4 字节分支。超出这个范围的直接返回错误。代理对区间 0xD800 到 0xDFFF 也要拒绝。
每个分支的位拆分逻辑是解码的逆运算。以 3 字节为例：
dst[0] = (uint8_t)(0xE0 | (codepoint >> 12)); dst[1] = (uint8_t)(0x80 | ((codepoint >> 6) & 0x3F)); dst[2] = (uint8_t)(0x80 | (codepoint & 0x3F));这里有个容易踩的坑：移位之前一定要把 codepoint 转成 uint32_t，如果 codepoint 是 int 类型且为负数，右移的行为是实现定义的。我在函数入口就做了参数类型约束，用 uint32_t 接收，从源头上避免这个问题。
写入之前要先检查 dst_len 是否足够。我见过不少代码是先写再检查，结果缓冲区溢出。正确的做法是先根据码点范围算出需要的字节数，和 dst_len 比较，不够就直接返回错误，一个字节都不写。
3.3 边界情况处理与错误码设计
错误码我定义了几个：
| 错误码 | 值 | 含义 |
|---|---|---|
| UTF8_OK | 0 | 成功 |
| UTF8_ERR_TRUNCATED | -1 | 序列被截断，字节数不够 |
| UTF8_ERR_INVALID_LEAD | -2 | 非法首字节 |
| UTF8_ERR_INVALID_CONT | -3 | 非法后续字节 |
| UTF8_ERR_OVERLONG | -4 | 超长编码 |
| UTF8_ERR_SURROGATE | -5 | 代理对区间 |
| UTF8_ERR_RANGE | -6 | 码点超出范围 |
| UTF8_ERR_BUFFER | -7 | 输出缓冲区不足 |
这些错误码在调试的时候非常有用。比如你在串口收到一串乱码，通过错误码就能快速判断是数据被截断了，还是对端发来的根本不是 UTF-8。我在实际项目里就遇到过对端用 GBK 编码发数据，解码函数返回 UTF8_ERR_INVALID_CONT，一看就知道编码格式对不上。
还有一个细节：解码函数在遇到错误时，consumed 应该怎么设置？我的做法是，如果首字节就非法，consumed 设为 1，让调用者可以跳过这个字节继续尝试；如果是后续字节非法，consumed 设为已经消耗的字节数，调用者可以选择跳过整个序列或者逐字节重试。这样设计是为了让上层能做错误恢复，而不是一遇到错误就整个字符串放弃。
4. 工具函数的实现与实战应用
4.1 字符串长度统计：字符数不是字节数
很多人写 C 语言字符串处理的时候，习惯用 strlen 来统计长度，但在 UTF-8 场景下这是错的。strlen 返回的是字节数，一个汉字占 3 个字节，用 strlen 统计出来是 3，但用户期望的是 1 个字符。所以需要一个 utf8_strlen 函数，遍历字节流，统计合法的 UTF-8 序列个数。
实现思路很简单：从头开始，每次调用 utf8_decode，成功就把计数加一，consumed 往前推进；失败就根据错误码决定是跳过一个字节还是跳过整个序列。这里有个策略选择：遇到非法序列时，是把它当作一个字符计数，还是跳过不计？我的做法是当作一个字符计数，因为用户看到的就是一个乱码符号，统计进去更符合直觉。
size_t utf8_strlen(const uint8_t *s, size_t len) { size_t count = 0; size_t i = 0; while (i < len) { uint32_t cp; size_t consumed; int ret = utf8_decode(s + i, len - i, &cp, &consumed); if (ret == UTF8_OK) { i += consumed; } else { i += 1; } count++; } return count; }这个函数的时间复杂度是 O(n)，对于嵌入式场景来说完全够用。如果你需要频繁统计同一个字符串的长度，可以在第一次统计后把结果缓存起来，避免重复计算。
4.2 子串截取：按字符截取而不是按字节
按字符截取子串是显示场景里的高频需求。比如屏幕一行只能显示 10 个汉字，你需要从一段文本里截取前 10 个字符。如果按字节截取，很可能把一个 3 字节的汉字截断，显示出来就是乱码。
utf8_substr 函数的思路是：先遍历找到第 start 个字符的字节偏移，再遍历找到第 start+count 个字符的字节偏移，然后返回这两个偏移之间的字节区间。实现的时候要注意边界，start 超出字符串长度就返回空串，count 超出剩余字符数就截到末尾。
int utf8_substr(const uint8_t *src, size_t src_len, size_t start, size_t count, const uint8_t **out, size_t *out_len) { size_t i = 0, char_idx = 0; size_t begin = 0, end = 0; int found_begin = 0; while (i < src_len) { if (char_idx == start) { begin = i; found_begin = 1; } if (char_idx == start + count) { end = i; *out = src + begin; *out_len = end - begin; return UTF8_OK; } uint32_t cp; size_t consumed; int ret = utf8_decode(src + i, src_len - i, &cp, &consumed); i += (ret == UTF8_OK) ? consumed : 1; char_idx++; } if (found_begin) { *out = src + begin; *out_len = src_len - begin; return UTF8_OK; } *out = src + src_len; *out_len = 0; return UTF8_OK; }这个函数返回的是指向原缓冲区的指针，不涉及内存分配，调用者用完即弃，非常适合嵌入式环境。
4.3 合法性校验与码点遍历
合法性校验函数 utf8_validate 就是遍历整个字节流，每一步都调用 utf8_decode，只要有一个序列非法就返回失败。这个函数在接收网络数据或者读取配置文件的时候特别有用，可以在解析之前先确认数据是合法的 UTF-8，避免后续处理出现意外。
码点遍历函数 utf8_iterate 提供一个迭代器接口，每次调用返回下一个码点和消耗的字节数，调用者用一个偏移量变量维护当前位置。这个接口比一次性解码整个字符串更灵活，适合流式处理场景，比如从串口缓冲区里逐字符解析。
typedef struct { const uint8_t *data; size_t len; size_t pos; } utf8_iter; int utf8_iter_next(utf8_iter *it, uint32_t *cp) { if (it->pos >= it->len) return UTF8_ERR_TRUNCATED; size_t consumed; int ret = utf8_decode(it->data + it->pos, it->len - it->pos, cp, &consumed); it->pos += (ret == UTF8_OK) ? consumed : 1; return ret; }这个迭代器结构体很小，可以放在栈上，不占堆空间。在中断服务程序里用也很安全，因为不涉及动态内存。
5. 实操验证与常见问题排查
5.1 测试用例设计与验证方法
写完代码不测试等于没写。我设计了一组覆盖各种情况的测试用例，用 PC 端的 GCC 编译运行，验证通过后再移植到目标平台。
| 测试用例 | 输入字节 | 期望结果 |
|---|---|---|
| ASCII 单字节 | 41 | 码点 0x41，消耗 1 字节 |
| 2 字节序列 | C2 A9 | 码点 0xA9，消耗 2 字节 |
| 3 字节汉字 | E4 B8 AD | 码点 0x4E2D，消耗 3 字节 |
| 4 字节 emoji | F0 9F 98 80 | 码点 0x1F600，消耗 4 字节 |
| 截断序列 | E4 B8 | 返回 TRUNCATED |
| 非法首字节 | FF | 返回 INVALID_LEAD |
| 非法后续字节 | E4 41 AD | 返回 INVALID_CONT |
| 超长编码 | C0 80 | 返回 OVERLONG |
| 代理对 | ED A0 80 | 返回 SURROGATE |
| 超出范围 | F4 90 80 80 | 返回 RANGE |
测试的时候我用了一个小技巧：把期望的码点和实际解码结果都打印成十六进制，一眼就能看出差异。另外，对于多字节序列，我会额外验证 consumed 的值是否正确，因为 consumed 错了会导致后续解析全部错位。
5.2 实际项目中踩过的坑
第一个坑是符号扩展。早期版本里我用 char 类型接收字节，结果 0xE4 被解释成负数，右移的时候高位补 1，拼出来的码点完全不对。后来全部改成 uint8_t，问题消失。这个坑在 x86 上可能不明显，但在某些编译器上 char 默认是有符号的，移植到 ARM 平台就暴露了。
第二个坑是超长编码的校验顺序。我一开始是先拼接再校验范围，结果 C0 80 拼出来是 0x00，范围校验通过了，但这是非法的超长编码。正确的做法是在拼接之前就根据首字节判断最小合法码点，拼接之后再和这个最小值比较。
第三个坑是缓冲区边界。解码函数在读取后续字节之前，必须先确认 src_len 足够，否则会越界读取。我见过有代码先读再判断，在 PC 上可能没事，因为内存页对齐，但在单片机上直接触发硬件异常。这个问题的修复很简单，就是在每个读取操作之前加长度检查，但一定要养成习惯。
第四个坑是性能。最初的实现里我每个字节都调用一次函数，函数调用开销在嵌入式环境里不可忽略。后来我把短序列的解码逻辑内联到主循环里，只在遇到多字节序列时才调用辅助函数，实测解码速度提升了将近一倍。当然，这是在对性能有极致要求的情况下才需要做的优化，一般场景下可读性优先。
5.3 常见问题速查表
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 中文显示为乱码 | 解码时字节序错误 | 检查是否把多字节序列的字节顺序搞反 |
| 部分字符显示为问号 | 字库缺少对应码点 | 打印码点值，确认字库是否覆盖 |
| 字符串长度统计偏大 | 把非法字节也计入了 | 检查 utf8_strlen 的错误处理分支 |
| 截取后末尾乱码 | 按字节截取而非按字符 | 改用 utf8_substr |
| 解码返回 TRUNCATED | 缓冲区不完整 | 确认数据源是否一次性给全 |
| 解码返回 OVERLONG | 对端编码不规范 | 检查对端是否用了非标准编码器 |
| 4 字节 emoji 解码失败 | 码点范围判断有误 | 确认上限是 0x10FFFF 而非 0xFFFF |
这张表是我在实际调试中总结出来的，基本上覆盖了 90% 以上的问题场景。遇到问题的时候先查表，能省不少时间。
6. 代码组织与移植建议
6.1 文件结构与编译配置
整个模块我放在两个文件里：utf8.h 放函数声明和错误码定义，utf8.c 放实现。测试代码单独放在 test_utf8.c 里，用条件编译控制是否参与构建。这样在嵌入式项目里只需要把 utf8.c 加入编译列表，头文件包含路径配好就行，不需要改任何构建脚本。
编译选项上，我建议开启 -Wall -Wextra -Wconversion，把所有的类型转换警告都打开。UTF-8 处理涉及大量位运算和类型转换，这些警告能帮你提前发现潜在的符号扩展和截断问题。如果目标平台支持 C99，用 stdint.h 里的 uint8_t、uint32_t 这些定长类型，不要用 unsigned char 和 unsigned int，因为后者的宽度在不同平台上可能不一样。
6.2 移植到不同平台的注意事项
移植到 8 位单片机的时候要注意，32 位整数的移位操作可能比较慢，如果性能敏感，可以把 4 字节序列的处理单独优化，或者干脆不支持 4 字节（很多嵌入式字库也不包含 emoji）。移植到 16 位平台的时候要注意，int 是 16 位的，移位超过 15 位会出问题，所有涉及码点运算的变量都必须显式声明为 uint32_t。
还有一个移植相关的点是字节序。UTF-8 是字节流编码，本身没有字节序问题，但如果你把码点存成 uint32_t 数组再序列化，就要注意大小端。我的建议是码点在内存里保持主机字节序，只在编码成 UTF-8 字节流的时候才做位拆分，这样就不会有字节序的困扰。
6.3 后续扩展方向
这套代码目前只做了基础的编解码和工具函数，后续可以按需扩展。比如加上 UTF-8 和 UTF-16 之间的转换，方便和某些只支持 UTF-16 的图形库对接。再比如加上大小写转换，不过这个需要查表，因为 Unicode 的大小写映射不是简单的加减 32。还可以加上码点分类，判断一个码点是字母、数字还是标点，这在做文本分析的时候有用。
扩展的时候要记住一个原则：核心编解码层保持稳定，所有扩展功能都建立在核心层之上。这样即使扩展功能出问题，也不会影响基础的编解码正确性。我在项目里就是这么做的，utf8.c 从第一版到现在几乎没改过，所有的功能增加都在上层模块里完成。
我个人在实际操作中的体会是，UTF-8 处理看起来简单，但边界情况特别多，一定要把测试用例写全，尤其是非法序列的测试。很多 bug 在正常数据下不会暴露，一旦遇到脏数据就出问题。另外，错误码的设计要足够细，不要用一个笼统的“失败”打发所有情况，细分的错误码在调试时能帮你省下大量时间。最后再分享一个小技巧：如果你不确定某个字节序列的 UTF-8 编码是什么，可以用 Python 的'字符'.encode('utf-8')快速验证，比手动算位运算靠谱得多。
