在Windows平台，使用`MultiByteToWideChar`与`WideCharToMultiByte`组合实现UTF-8与GBK互转，需经UTF-16中转并指定代码页936。务必先调用一次获取所需缓冲区大小，再分配内存；检查返回错误码（如`ERROR_INSUFFICIENT_BUFFER`）；避免使用已弃用的`std::codecvt_utf8`
在Windows平台上处理UTF-8和GBK的转换，最直接也最靠谱的方式，还得是这对经典的API组合：`MultiByteToWideChar`和`WideCharToMultiByte`。不需要第三方库，也避免了ICU或iconv在Windows上带来的链接和运行时依赖问题。
### 为什么不能直接用 std::codecvt_utf8
从Visual Studio 2015开始，`std::codecvt_utf8`就被标记为弃用，2017之后更是彻底移除。即便是GCC和Clang，在Windows环境下对GBK的支持也谈不上稳定。更关键的问题在于，`std::codecvt`对多字节编码（比如GBK）的边界处理相当不可靠，很容易在双字节字符的中间位置截断，导致乱码甚至程序崩溃。
具体来说，问题出在几个方面：
- 不感知Windows代码页，遇到“镕”、“珮”这类扩展汉字，映射就乱套了
- 输入缓冲区长度计算容易出错，`out`缓冲区没预留足够空间时，会静默截断，连个提示都没有
- 没有错误码反馈，失败时只返回0，很难定位是参数错了还是编码本身非法
### UTF-8 → GBK：用 WideCharToMultiByte + CP_UTF8 → CP_ACP
这条路必须经过UTF-16中转——这是Windows API的强制路径，绕不开。有个细节容易踩坑：不要直接用`CP_ACP`去转GBK字符串，而是应该显式指定`CP_GB2312`（兼容GBK）或直接用代码页号`936`。否则在非中文系统上，很可能误用其他ANSI代码页，结果就全错了。
具体操作分两步走：
- 第一步：调用`MultiByteToWideChar(CP_UTF8, ...)`把UTF-8转成`wchar_t`字符串。这里特别要注意，`len`参数是字节数，不是字符数，别搞混了。
- 第二步：调用`WideCharToMultiByte(936, ...)`把`wchar_t`转成GBK字节流。
- 两次调用都要先传`nullptr`获取目标缓冲区长度，再分配内存，这样可以避免栈溢出或堆越界。
- 务必检查返回值：为0表示失败，通过`GetLastError()`查具体原因。常见的有`ERROR_INSUFFICIENT_BUFFER`（缓冲区不够）和`ERROR_NO_UNICODE_TRANSLATION`（编码无法转换）。
```csharp
int len = MultiByteToWideChar(CP_UTF8, 0, utf8_str, -1, nullptr, 0);
if (len == 0) return false;
std::vector
wbuf(len);
MultiByteToWideChar(CP_UTF8, 0, utf8_str, -1, wbuf.data(), len);
int gbk_len = WideCharToMultiByte(936, 0, wbuf.data(), -1, nullptr, 0, nullptr, nullptr);
if (gbk_len == 0) return false;
std::vector gbk_buf(gbk_len);
WideCharToMultiByte(936, 0, wbuf.data(), -1, gbk_buf.data(), gbk_len, nullptr, nullptr);
```
### GBK → UTF-8：反向调用 MultiByteToWideChar + WideCharToMultiByte
顺序刚好颠倒，但核心思路不变：仍然需要经过UTF-16中转，而且必须用`936`而不是`CP_ACP`。有一个容易忽略的坑：当GBK输入中包含`\0`字节时，`MultiByteToWideChar`默认按C字符串处理，遇到`\0`就截断。如果待转换的是二进制的GBK数据，必须传入明确的长度，第四个参数不能是`-1`。
几个关键点值得记住：
- GBK输入长度必须显式传入（比如`gbk_len`），否则中文路径末尾带`\0`就会被提前终止，导致转换不完整。
- `WideCharToMultiByte(CP_UTF8, ...)`输出缓冲区的大小是按字符数算的，但UTF-8每个字符占1到4个字节。所以目标缓冲区至少预留`wlen * 4`字节，这是比较保守但安全的做法。
- 如果源GBK数据中含有非法字节序列（比如单个0xA1），API默认会静默替换成`?`。如果需要严格校验，可以开启`MB_ERR_INVALID_CHARS`标志，这样非法输入会让函数返回0，并设置`ERROR_NO_UNICODE_TRANSLATION`错误。
### 性能与线程安全注意事项
这两个API是Windows内核导出函数，线程安全方面不用担心。但频繁调用确实有开销——每次都要查表、做状态机解析。如果需要在高频场景下转换（比如批量写入日志），建议预分配好`wchar_t`缓冲池，复用内存，避免反复分配释放。
具体来说，有几点实践经验可以参考：
- 不要在循环里反复new/delete `std::vector`，改用成员变量缓存或对象池，能省不少开销。
- 避免对同一字符串反复调用两次API（一次测长、一次转换），除非长度真的动态变化。
- Release版本下，`WideCharToMultiByte`对纯ASCII输入做了优化，但如果GBK中中文占比高，这个优化基本派不上用场。
- MinGW用户要注意：`CP_UTF8`定义在`windows.h`中，确保`#define WIN32_LEAN_AND_MEAN`没有屏蔽掉`winnls.h`，否则编译会报错。
真正麻烦的从来不是调用哪个函数，而是忘记检查返回值、忽略非法字符策略、以及在跨模块传递时混淆了“字节长度”和“字符长度”。Windows编码转换没什么魔法，只有老老实实查文档、打日志、看GetLastError。
