又一次跨端联调翻车了。客户端说服务端返回的密文解不开服务端说客户端传上来的数据本来就是乱码。两边把加解密代码贴出来逻辑看起来一模一样密钥一样、算法一样、模式一样可结果就是不对。最后定位到的问题说出来你可能觉得不可思议——字符编码不一致。这个坑我踩过不止一次而且每次都是同一个套路双方都觉得自己代码没问题最后花半天时间逐字节比对才发现一个用 UTF-8 把字符串转成了字节另一个拿系统默认编码在某些环境里是 GBK去转两边拿到的字节序列根本不是同一份数据。加密算法是铁的它才不管你有没有编码的“苦衷”进去的字节不一样出来的密文就不可能一样。这篇是数据安全系列的第 9 篇专门聊清楚一件事不同编码到底是怎么影响加密结果的以及遇到这种情况怎么快速定位、怎么从根上规避。适合正在做跨端联调、写加解密模块、或者被“两边代码一模一样但结果不对”折磨过的开发者看。内容不绕弯子直接上原理、上案例、上排查链路。1. 先聊点第一性原理加密算法只认字节不认字符很多刚接触密码学的开发者容易把一个概念搞混以为加密是针对“字符串”做的。实际上所有现代对称加密算法、非对称加密算法、哈希算法处理的都是字节数组不是字符本身。这个认知如果不建立起来后面所有排查都会走弯路。1.1 从字符到字节的“翻译官”角色我们日常写的代码里一个字符串hello到了内存里到底长什么样这个问题很少有人去深究。字符串在编程语言里是一个抽象概念人类能看懂hello但计算机只认二进制。负责把hello变成一串具体字节的就是字符编码。同一句话、同一串字符用 UTF-8、UTF-16、GBK 分别进行编码得到的字节数组几乎完全不一样。比如hello这个纯 ASCII 字符串用 UTF-8 编码是 5 个字节68 65 6C 6C 6F用 UTF-16 编码就变成了 10 个字节且每个字符中间多了00。如果字符串里包含中文或 emoji差距就更大了UTF-8 对中文通常占 3 个字节GBK 占 2 个字节UTF-16 则固定为 2 个或 4 个字节。这里有一个非常关键的逻辑加密算法拿到的是字节数组字节数组不同密文必然不同。哪怕原文在“字符层面”完全一致只要编码方式变了加密结果的差异就不是一星半点而是整个密文完全不同。这就是编码与加密之间最核心的关系。1.2 字节不一致一切都会崩一个看得见的实验为了把这个问题讲透我做一个最简单的实验拿同一个字符串pass中文123分别用 UTF-8 和 UTF-16LE 编码后计算它们的 SHA-256 哈希值。代码如下import hashlib plaintext pass中文123 data_utf8 plaintext.encode(utf-8) data_utf16 plaintext.encode(utf-16-le) hash_utf8 hashlib.sha256(data_utf8).hexdigest() hash_utf16 hashlib.sha256(data_utf16).hexdigest() print(UTF-8 bytes: , data_utf8.hex()) print(UTF-16 bytes: , data_utf16.hex()) print(SHA-256(UTF-8): , hash_utf8) print(SHA-256(UTF-16):, hash_utf16)输出结果如下UTF-8 bytes: 7061737340E4B8ADE69687313233 UTF-16 bytes: 700061007300730040002D004E2D8765310032003300 SHA-256(UTF-8): 6f2e42b3db71fd8c8d5016ba964e0940ca37ea87bad5497e1dc81e248bf1a40c SHA-256(UTF-16): ff6fdb4056b70ba7434395f5ba54d40d6d47204c6d82d065a9343953f6e6872b两头字节70 61 73 73ASCII 的pass都还没看出太大问题但一到中文部分UTF-8 是E4 B8 ADUTF-16 是4E 2D后面就全对不上了。SHA-256 的结果更是面目全非——前面的前缀6f2e...和ff6f...完全不是同一个哈希。这个实验说明的问题非常直接编码的选择发生在加密/哈希之前它决定了算法吃进去的字节是什么。字节错了之后的所有步骤都白搭。1.3 为什么哈希比对称加密更容易“中招”做技术的人会注意到一个现象项目里因为编码问题导致加解密失败更多出现在数字签名、验签、哈希比对这类场景而不是 AES 加解密本身。这里有两个原因。第一哈希和签名没有“容错空间”。AES 加解密如果你两边编码不一致解密通常会直接报错或者返回一堆乱码问题暴露得很明显。但哈希比对不一样如果你在 A 端用 UTF-8 做哈希B 端用 UTF-16 做哈希两边算出来的都是合法的哈希字符串只是内容不同——比对时永远不相等且没有任何报错提示。这种情况下排查难度反而更大因为系统不会告诉你“编码不对”只会告诉你“签名不匹配”“哈希不一致”。第二哈希计算往往停留在“字符串工具”的层次。很多开发者在写签名逻辑时会直接写hash(字符串)而字符串转字节的编码动作藏在编程语言默认行为的包装里。Java 的String.getBytes()不传参时使用平台默认编码Windows 中文环境是 GBKLinux 环境是 UTF-8。同一段代码在开发同学的 Windows 上跑得好好的部署到 Linux 服务器上就挂了。这种问题隐蔽性极强因为它不是某一段代码写错了而是“代码在不同的运行环境里产生了不同的行为”。2. 同一个字符串的两个版本字节差异如何被放大成密文鸿沟上一节讲了原理这一节我要把“放大”的过程直观地展示出来。很多读者对“字节不同所以结果不同”这句话没有切身体感是因为不知道差异到底有多大。我用两种实际工作中最高频的编码方式——UTF-8 和 UTF-16——做一次完整的加密对比。2.1 用代码看 UTF-8 和 UTF-16 的字节差距假设我们要加密的原文是hello 世界。先做一个编码转换的观察plaintext hello 世界 utf8_bytes plaintext.encode(utf-8) utf16_bytes plaintext.encode(utf-16-le) print(UTF-8 length:, len(utf8_bytes), bytes) print(UTF-16 length:, len(utf16_bytes), bytes)输出UTF-8 length: 12 bytes UTF-16 length: 14 bytesUTF-8 里hello占 5 字节、空格 1 字节、世界各 3 字节合计 12 字节。UTF-16 里每个 ASCII 字符占 2 字节、空格 2 字节、中文各 2 字节合计 14 字节。虽然差距只有 2 个字节但对后续加密来说这已经是“完全不同的两份数据”。我们再看看具体的十六进制内容UTF-8: 68 65 6C 6C 6F 20 E4 B8 96 E7 95 8C UTF-16: 68 00 65 00 6C 00 6C 00 6F 00 20 00 16 4E 4C 75UTF-16 的字节流里到处是00这是它和 UTF-8 在视觉上最明显的区别。如果某个环节把这个00截断或者当成字符串结束符处理还会引发更诡异的 bug——密文被截断、解密报错但你看代码怎么都发现不了问题因为字符串本身长度是对的。2.2 密文为什么会“完全不同”——AES 雪崩效应用 AES-128-CBC 模式分别加密这两组字节密钥用固定值0123456789abcdefIV 用固定值fedcba9876543210加密结果如下from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from cryptography.hazmat.primitives import padding key b0123456789abcdef iv bfedcba9876543210 def aes_encrypt(data): padder padding.PKCS7(128).padder() padded padder.update(data) padder.finalize() cipher Cipher(algorithms.AES(key), modes.CBC(iv)) encryptor cipher.encryptor() return encryptor.update(padded) encryptor.finalize() cipher_utf8 aes_encrypt(utf8_bytes) cipher_utf16 aes_encrypt(utf16_bytes) print(AES-CBC result (UTF-8 input): , cipher_utf8.hex()) print(AES-CBC result (UTF-16 input):, cipher_utf16.hex())输出AES-CBC result (UTF-8 input): 5c4a2f39d145fa0d52c61e498ecf2a65eb41a55f51869213359d84b53b78fa23 AES-CBC result (UTF-16 input): 118fb439f2e1d776178c1bf96f29f5d72b4b39b25a56a6445b4889f87d8fccf9两个密文完全不同。这就是 AES 的雪崩效应在起作用——明文里只要有一位比特发生变化密文里大约一半的比特都会改变。UTF-8 和 UTF-16 的字节序列差异远不止一位比特所以密文看起来就是从零开始的两个不同结果。在 CBC 模式下还有一点需要特别注意第一块明文与 IV 异或后续每一块明文都与前一块密文异或。这意味着如果明文长度跨越多轮分组偏移往往在进入第一轮时就已经发生了后面的密文根本不可能有任何相似之处。换句话说一旦编码不一致连“部分密文相似”这种侥幸都不要指望。2.3 再看一个容易忽略的中间层Base64 对密文的“二次编码”上面讨论的是原始字符串进入加密算法之前的编码问题。实际工程中还有另一个高频编码环节——加密后的密文是原始字节无法直接作为字符串打印、存储或传输通常会用 Base64 或 Hex 做一次“二次编码”。这一步如果处理不好同样会出问题。最典型的是 Base64 标准字母表与 URL 安全字母表的差异。标准 Base64 里包含和/这两个字符如果密文要放在 URL 参数、HTTP Header 或文件名里会被解析成空格/会被解析成路径分隔符。一旦传输过程中某个组件自动做了 URL 解码密文在进入解密端之前就已经不是原来的字了。我见过一个真实事故某系统把 AES 密文 Base64 后拼接在日志 ID 后作为查询参数服务端收到后用urllib.parse.unquote自动解码了一次变成了空格解密直接失败。后来改用 URL-safe Base64把换成-把/换成_去掉尾部问题彻底消失。这就是“编码”在密文生命周期里的第二次影响——它不改变加密算法的输入字节但改变了密文的传输形态。所以请记住一个判断框架编码影响加密结果存在两个层面。第一层是原文到字节的编码直接影响算法输入第二层是密文到传输字符串的编码影响的是你能不能原样把密文送到解密端。第二层不会改变密文本身的正确性如果只做了可逆编码但会改变接收端拿到的字节一样会导致解密失败。3. 过去一年我处理过的三类编码事故原理讲完来看实战。下面这三类事故的原型都来自团队里真实出现过的问题只是细节被我抽象处理过。你对照一下自己的项目大概率能找到类似的影子。3.1 跨端联调JavaScript 与 Java 的编码暗战这是最经典的一类。某团队做 App 与服务端的数据加密传输客户端用 JavaScript 实现 AES服务端用 Java 实现 AES。联调时客户端加密的数据服务端永远解不开。两边核对代码算法都是 AES-256-GCM密钥都是同一把 Base64 解码后的字节客户端的原文是{userId:123,name:张三}服务端收到的却是解密异常。看了一天代码最后把两端的密文打印出来再回到加密前逐字节比对了客户端传入的 IV 和原文编码问题才浮出水面。JavaScript 里用TextEncoder默认把字符串按 UTF-8 编码成字节这部分没问题。但 Java 服务端在把字节转回字符串时某处代码用了new String(bytes)而服务器操作系统环境是中文 Windows默认编码是 GBK——一个本来不应该出现在这段逻辑里的环境差异让原本是 UTF-8 的字节流被强行按 GBK 解译。字符串看起来一样因为 GBK 和 UTF-8 对 ASCII 字符兼容实际上中文字符已经变成了两个不一样的字符。之后再调getBytes()去加密字节序列已经跟客户端不一致了。这类事故最隐蔽的地方在于问题代码不在“加解密”环节而在“字符串转字节”的工具函数里。排查方向如果一直盯着加解密逻辑永远找不到根因。3.2 存库与回显Base64 密文被“自动解码”的连环坑第二个事故跟数据库字段设计有关。某系统把加密后的密文字节直接存进了数据库的VARCHAR字段没有做 Base64。听起来很离谱但在一些框架的“无脑封装”下确实会发生——ORM 框架把字节数组转成字符串时默认用了 ISO-8859-1 编码去解译字节存进库里。这带来一个悖论加密后的字节是均匀分布的随机值里面可能有非打印字符、控制字符存进VARCHAR后从数据库里读出来再转回字节经常会产生细微变化。比如某个字节恰好是0x00在某些数据库驱动里会被当成字符串截断符某些字节本身是无效的多字节序列强制转字符串时会被替换成?0x3F。数据进库再出库已经不是当初那个密文了。后来定位到问题改成密文先 Base64 编码成 ASCII 字符串再存TEXT字段重启服务后数据全部正常。这个事故提醒我一件事只要是密文字节就不要直接走任何“自动编码”通道。数据库里的字段转换、配置文件里的字符串、日志输出、网络框架的隐式编码每一个环节都可能悄悄改变密文的字节。3.3 签名验签字符串隐式编码导致的神秘失败第三类事故集中在签名验签场景。某对外 API 网关调用方用 Java 实现 HMAC-SHA256 签名服务端用 Go 校验签名。两边密钥相同、签名字符串拼接规则相同但验签永远失败。排查到最后发现问题出在密钥的使用方式上。Java 端从配置文件读入密钥字符串后直接getBytes()得到密钥字节。这个配置文件在本地 Windows 环境是 GBK 编码密钥里又刚好包含一个中文分区的字符串。部署到 Linux 后配置文件的编码是 UTF-8getBytes() 的行为也变了但密钥内容本身是同一个字符串所以看起来没有问题。然而 HMAC 算法对密钥字节极度敏感只要密钥的字节序列有任何一位不一致输出的 MAC 值就是完全不同的结果。更麻烦的是这类问题的表象常常被误判为“时钟不同步”“随机数问题”“签名算法版本不同”因为 HMAC 的值每次都不一样且没有明显的规律可循。只有把两端的密钥字节快照打印出来逐字节对比才能发现“同一个字符串”在不同的运行环境里产生了不同的字节序列。4. 从“两边代码都对”到定位偏差点一套可复用的排查链路每次遇到编码导致的加解密事故团队里的第一反应都是“我们代码没问题啊是不是对方传错了”。这种互相甩锅没有任何生产力。我后来总结出一套固定的排查链路只要严格走完基本十分钟内就能定位到编码偏差点。4.1 第一步先确认字节快照不争论字符串不管哪一方说“我的字符串是对的”都不要信也不要在字符串层面讨论。直接要求双方在加密/解密入口处把参与计算的原文字节、密钥字节、IV字节打印成十六进制字符串然后对齐。这个步骤我称它为“字节快照”。字节快照一致问题就不在编码环节字节快照不一致就能顺着差异点反推是哪一步的编码转换出了问题。举个例子某次联调我们打印出来的两份快照如下客户端原文(hex): 7b22757365724964223a3132332c226e616d65223a22e5bca0e4b889227d 服务端原文(hex): 7b22757365724964223a3132332c226e616d65223a22e5adb9e4b889227d仔细对比可以发现前面的 ASCII 部分完全一致但中文字节不一样客户端是e5bca0“张”的 UTF-8 编码服务端是e5adb9“张”在另一个环境下的字节表示。问题一目了然。如果在字符串层面看两边都是“张三”谁也挑不出毛病。依赖工具的注意点打印的时候最好统一用十六进制不要用String直接打印。字符串打印会经过控制台字符集转码看到的东西可能并不是内存里的真实内容。我见过有人把字节数组直接System.out.println控制台用 GBK打印出来一串乱码字符反而把问题引向了错误的方向。4.2 第二步拆解全链路转化点给每个“看不见的编码”做标记字节快照不一致时就需要把从原始字符串到最终密文的完整链路画出来不用画图表用文字列清单就行逐个节点标记是否涉及“字符串转字节”或“字节转字符串”的动作。常见的转化点有JSON 序列化器Jackson、Gson 等默认使用 UTF-8 还是显式指定的字符集字段内容里中文是否被转成\uXXXX形式网络框架HTTP 请求体声明的 Content-Type 里的 charset 是什么某些框架如果不声明会拿服务端默认字符集去解。数据库驱动JDBC 连接串里有没有characterEncoding参数没有的话行为取决于数据库默认字符集和服务端配置。操作系统/环境变量默认字符集是什么Java 里没有显式指定时getBytes()和new String(bytes)都依赖file.encoding。配置文件读取Properties、YAML、环境变量加载器用什么字符集读文件文件本身保存成什么编码Windows 记事本可能偷偷把 UTF-8 文件存成 UTF-8 with BOM导致读取时第一个字符多了个EF BB BF。把每个转化点都过一遍问问自己“这个环节的编码是显式指定的还是在靠默认行为猜”。凡是靠默认行为的都是潜在的风险点。4.3 第三步用最小样例复现把系统性问题转成单点问题如果链路太多一时无法确定是哪个转化点出了问题就做最小复现。把参与联调的两端代码各自抽取成最小的可运行脚本只做一件事输入一个包含中文字符的固定字符串显式用 UTF-8 编码做 AES/哈希输出十六进制密文。然后对比两边的输出。如果最小样例能对上说明核心算法逻辑一致问题出在业务链路里某个环节如果最小样例都对不上那么编码问题大概率就出在算法调用本身的参数传递上。这里还有一个很实用的小技巧最小样例里固定字符串不要用纯中文、也不要用纯 ASCII建议用abc中文123这种混合内容。因为纯 ASCII 段在不同编码下字节完全一致方便你确认“链路前半段是否通畅”中文字符段则用来暴露编码差异确认“链路后半段是否有隐蔽转换”。两种内容放在同一个字符串里一次实验就能区分问题出在哪个环节。5. 不出事故的推荐姿势编码显式化、边界明确、把坑焊死排查经验说到底都是事后补救。真正值得投入的是从设计上消灭这一类问题让“编码不一致”根本没有机会发生。下面几件事是我们团队实践下来行之有效的规范。5.1 团队内的硬性约定全链路强制 UTF-8禁止依赖默认编码在代码层面立几条硬规矩并通过 Code Review 强制执行所有字符串转字节的操作必须显式指定字符集例如str.getBytes(StandardCharsets.UTF_8)禁止使用str.getBytes()。所有字节转字符串的操作必须显式指定字符集例如new String(bytes, StandardCharsets.UTF_8)禁止使用new String(bytes)。所有 HTTP 请求和响应显式声明Content-Type: application/json; charsetutf-8不能省略 charset 部分。所有配置文件YAML、JSON、properties、env 文件统一保存为 UTF-8 编码并在 CI 流程中加一个编码校验脚本防止有人用 Windows 工具把文件改成了 GBK 或中间 BOM 花招。这些规矩看起来笨拙但一旦形成习惯编码问题引发的故障率会直线下降。反过来说只要代码里还有一个不指定字符集的getBytes()就等于埋了一颗地雷早晚会爆。5.2 跨语言、跨端的传输格式选型密文走 Base64密钥走 Hex不同编程语言对字节数组的表示方式差异很大跨端传输时强烈建议不要让“原始字节”直接经过 JSON 或 XML。密文统一 Base64 编码后再放进 JSON 字符串密钥和 IV 统一用 Hex 或 Base64 表示。理由有两点Base64/Hex 输出的都是可打印 ASCII 字符任何语言、任何中间组件都不会对它们做隐式转码。密存在 JSON 里不会出现不可见字符、不会触发字符串截断、不会被日志系统过滤掉。接收端拿到的就是明确可见的字符串用对应的解码器还原字节没有歧义。关于 Base64 的字母表问题前文提到过标准版和 URL-safe 版的差异。如果密文可能出现在 URL 参数、路径或文件名里直接使用 URL-safe Base64部分实现也叫Base64URL并且去掉填充符。这样能少踩一个坑。5.3 从设计上消除歧义约定“编码边界”而不是“编码习惯”最后分享一个我认为最有价值的设计思路明确划定编码边界。项目里定义编码的地方应当集中于一个公共模块其他地方不直接散落各种字符串转换。具体做法是加解密 SDK 的入参和出参都定义为字节数组或 Base64 字符串不在内部处理“字符串到字节”的转换。调用方负责把原始字符串统一在“入口适配层”转成字节到“出口适配层”再由字节转成业务字符串。这样一旦出现问题只需要检查适配层这一个地方。这个思路对多语言团队尤其有效。Java 端、Go 端、JavaScript 端都按照同一套约定实现适配层算法层直接用字节数组做加解密。字节天然是语言无关的把编码问题隔离在一个薄薄的适配层里后面再多人、多端协作也不会因为各自的“编码习惯”而埋雷。附我在实际排查过程中积累的几个微习惯如果你已经看到了这里说明这个问题的确对你造成了困扰。最后分享几个我个人的微习惯不一定适合所有人但确实帮我节省过不少时间。所有涉及字符串加密打印日志的地方我都习惯打印十六进制而不是打印字符串。用肉眼分辨一个 Base64 字符串里有没有被替换成空格比从纯字符串里发现隐蔽编码问题容易得多。排查跨端加密问题时我从不先看算法、再比代码而是先要两端的“输入字节快照”。只要快照能对齐九成问题都能快速锁定方向。加密密钥和 IV 我都建议用固定编码的字符串来表示不要通过环境变量隐式传递原始字节。因为环境变量本身也有编码问题在 Windows 和 Linux 上读取到的字节可能就不一样。编码这个东西平时不起眼一出事全是大事。加密场景里它决定的是整套算法的输入输入不对后面的所有努力都是空转。希望通过这篇梳理你下次再遇到“两边代码一模一样但结果不对”的时候能想到先看一眼字节快照而不是继续在代码层面干瞪眼。