微信JSAPI支付调起失败，页面弹出“支付验证签名失败”或者统一下单接口直接返回sign error，是接入微信支付时最让人头疼的问题之一。排这类问题时，多数人第一反应是检查商户号、API密钥是否填对，反复核对之后发现配置完全没问题，签名却依然算不对。这种情况下，很大概率是签名算法里的字符编码格式出了岔子——密钥是对的，参数也是对的，但把字符串转成字节的那一步用错了编码，算出来的签名自然和微信服务器对不上。这篇文章就来把编码问题导致的签名错误彻底讲清楚。
一、签名为什么会因为编码而算错
先回顾一下签名的本质。无论是微信支付V2的MD5签名，还是V3的RSA-SHA256签名，本质都是同一件事：把待签名的字符串按照指定的字符编码转换成字节数组，再对这个字节数组做摘要或加密运算。关键点就在“转换成字节数组”这一步——同一个中文字符串，用UTF-8编码得到的字节序列和用GBK编码得到的字节序列完全不同，算出来的签名自然也天差地别。
微信支付的官方文档明确规定了：V2接口的请求参数和签名统一使用UTF-8编码，V3接口同样强制UTF-8。也就是说，微信服务器在校验签名时，是把你提交的参数值按UTF-8解码后再重新拼接、重新计算签名的。如果你本地代码运行在Windows环境，默认编码很可能是GBK，拼接出来的待签名串里包含了中文商品名称（比如“会员充值套餐”），你用GBK算出签名A，微信用UTF-8算出签名B，两者必然不一致，于是返回签名错误。
这里有一个非常隐蔽的坑：如果待签名的参数值全部是英文和数字，GBK和UTF-8编码结果是一样的，所以测试环境用“test”这种参数能通过，一上生产环境换成真实中文商品名就报错。很多人误以为是自己密钥配置出了问题，反复重置API密钥，越搞越乱，其实是编码差异在特定场景下才显现出来。
二、V2 MD5签名的正确写法与常见错误
V2签名的规则是：把所有非空参数按key的ASCII码从小到大排序，用key=value&key=value的格式拼接，最后拼上&key=商户密钥，对整个字符串做MD5后转大写。规则不复杂，但每一步都可能踩编码相关的坑。
先看一段典型的Java错误代码：
// 错误示例：依赖平台默认编码
public static String createSign(SortedMap<String, String> params, String apiKey) {
StringBuffer sb = new StringBuffer();
for (Map.Entry<String, String> entry : params.entrySet()) {
sb.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
}
sb.append("key=").append(apiKey);
// 问题在这里：没有显式指定UTF-8
try {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] digest = md.digest(sb.toString().getBytes());
StringBuilder hex = new StringBuilder();
for (byte b : digest) {
hex.append(String.format("%02X", b));
}
return hex.toString();
} catch (Exception e) {
throw new RuntimeException(e);
}
}
这段代码在Linux服务器上通常没问题，因为Linux默认编码一般是UTF-8。但一旦部署到Windows机器上本地调试，或者某些老项目的JVM启动参数里带着-Dfile.encoding=GBK，getBytes()就会用GBK编码，中文参数一出现签名必错。正确的写法非常简单，就是显式指定编码：
// 正确示例：显式指定UTF-8 byte[] digest = md.digest(sb.toString().getBytes(StandardCharsets.UTF_8));
除了编码问题，还有一个和编码密切相关的错误：对参数值做了URL编码（百分号编码）之后再参与签名。V2签名规则要求用参数原始值参与拼接，而不是编码后的值。有些开发者习惯性地先调一次URLEncoder.encode()再拼签名串，结果中文变成了%E4%BC%9A%E5%91%98这种形式，签名自然算不对。记住一个原则：URL编码只发生在最终发送HTTP请求的阶段，签名的输入永远是原始值。
PHP开发者也要留意，如果在代码里用了md5($str)，而文件本身保存成了GBK编码，或者用iconv转码时目标编码写错，同样会出问题。确保PHP文件保存为UTF-8无BOM格式，是排查这类问题的基本功。
三、V3 RSA签名中的编码陷阱
微信支付V3接口改用了RSA-SHA256的非对称签名，商户用私钥对待签名串签名，微信用商户证书里的公钥验签。V3的待签名串由四部分组成：HTTP请求方法、URL路径、时间戳、随机串，以及请求报文主体，用换行符\n分隔。编码要求同样是UTF-8。
V3签名最常见的编码问题出在请求体JSON的序列化上。很多开发者先手动把对象序列化成JSON字符串用于计算签名，然后框架在发送请求时又自动序列化了一次。两次序列化的结果哪怕只差一个空格、一个转义字符的写法，签名串就变了。比如商品名称里包含双引号，手动序列化时写成\"，框架序列化时用了Unicode转义\u0022，字符串内容语义相同但字节不同，算出的签名必然不一致。正确做法是序列化一次，签名和发送都用同一个字符串：
// 只序列化一次，签名和请求体共用同一份内容
String body = objectMapper.writeValueAsString(requestObj);
String message = "POST\n" + "/v3/pay/transactions/jsapi\n"
+ timestamp + "\n" + nonce + "\n"
+ body + "\n";
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
signature.update(message.getBytes(StandardCharsets.UTF_8));
String sign = Base64.getEncoder().encodeToString(signature.sign());
// 后续发送HTTP请求时，请求体必须原样使用这个body变量
另一个V3特有的坑是私钥文件本身的编码。商户API私钥文件是PEM格式，内容是Base64编码的DER数据，前后有-----BEGIN PRIVATE KEY-----的标记行。如果读取文件时用了错误的字符集把换行符\n处理成了\r\n，或者截取Base64正文时混入了不可见字符，私钥加载会直接报错，这类报错容易被误判成签名错误。解析私钥时务必按行严格处理，去掉首尾标记行后拼接中间的Base64内容。
调起支付的JSAPI签名也要注意。从后端返回给前端的paySign，是对appId、timeStamp、nonceStr、package这几个参数用V3方式重新签的结果，而不是直接复用统一下单时的请求签名。有些开发者偷懒把两个签名混用，前端报“当前的订单签名不对”，这其实不是编码问题而是签名对象搞错了，但报错信息容易误导排查方向。
四、快速定位签名错误的自检清单
排查编码导致的签名问题，最有效的手段是把待签名串原样打出来，和微信官方的签名校验工具对比。具体步骤是：在代码里把最终参与签名的完整字符串输出到日志，复制到微信支付官方文档提供的签名生成工具里，用相同的密钥生成签名，再和自己代码算出的结果比对。如果工具生成的签名能通过验签而你的不能，说明问题就在编码环节。
逐项核对时可以参考下面这个清单：
- 计算摘要前的字节转换是否显式指定了UTF-8，杜绝依赖平台默认编码。
- 参与签名的参数值是否为原始值，有没有提前做URL编码或HTML转义。
- 请求体是否只序列化一次，签名用的字符串和实际发送的报文是否为同一个对象。
- 源代码文件本身的保存编码是否为UTF-8，尤其注意Windows下的IDE默认编码。
- HTTP请求头中的
Content-Type是否声明了charset=utf-8，避免框架按其他编码重新编码请求体。 - V3私钥文件解析是否正确，换行符和PEM标记行处理是否干净。
还有一个容易被忽略的细节：数据库层面。如果商品名称存在数据库时就是乱码，或者从上游系统接收数据时编码已经错了，那么不管签名算法写得多规范，源头数据就是坏的。遇到“英文参数正常、中文参数报错”的现象，优先怀疑整条数据链路上的编码一致性，从数据库连接串的characterEncoding参数，到中间各服务的传输编码，逐段确认。
总结一下，微信支付签名错误绝大多数不是算法理解问题，而是细节执行问题。记住三个原则：签名输入用原始值、字节转换显式UTF-8、签名与发送共用同一份报文内容，基本就能避开这一类反复折腾的坑。排查时先打印待签名串做比对，比盲目重置密钥有效得多。