微信公众号网页开发中，调起JSAPI支付时经常遇到一个令人头疼的报错：支付签名验证失败。把商户号、AppID、API密钥反复核对都没有问题，最后在后端日志或前端截取的签名源串里发现一串类似 appId=wx123&nonceStr=abc&package=undefined&signType=MD5&timeStamp=1716... 的内容。参数值里出现 undefined 字样，意味着签名的输入本身就已经错了，后续再用任何密钥计算都不可能通过微信的验签。这篇文章围绕这个典型问题，把JSAPI支付二次签名的原理、后端生成逻辑、前端校验方法和联调排查路径完整梳理一遍。
一、JSAPI支付为什么需要二次签名，undefined是怎么混进去的
微信公众号内的网页支付走的是JSAPI通道。整个流程分为两步：第一步，商户服务端调用微信统一下单接口，拿到 prepay_id；第二步，服务端根据 prepay_id 重新组织一组参数，再次计算签名后返回给前端，由前端通过 wx.chooseWXPay 或 WeixinJSBridge.invoke 调起微信收银台。这一步的签名通常被称为二次签名，它和统一下单时的签名不是同一个签名串。
二次签名需要参与的参数包括 appId、timeStamp、nonceStr、package 和 signType。其中 package 的值必须是形如 prepay_id=wx201410272009395522657a690389285100 的完整字符串。很多开发者在返回给前端时只传了 prepayId 或者字段名写成了 prepay_id 而不是 package，导致前端读取时拿到 undefined。还有一种情况是后端使用弱类型语言返回JSON，某个字段被赋值为 null，前端在拼接字符串时自动转成 null 或 undefined，最终签名串中就会出现这些非预期值。
可以看一段典型的前端拼接代码，如果 res.package 没有正确返回，签名串就会变成 package=undefined：
// 错误示例：后端返回字段名不一致导致package为undefined
const res = {
appId: 'wx1234567890',
timeStamp: '1716000000',
nonceStr: 'abc123',
prepay_id: 'wx201410272009395522657a690389285100', // 字段名写错
signType: 'MD5'
};
const signStr = 'appId=' + res.appId + '&nonceStr=' + res.nonceStr + '&package=' + res.package + '&signType=' + res.signType + '&timeStamp=' + res.timeStamp;
console.log(signStr);
// 输出：appId=wx1234567890&nonceStr=abc123&package=undefined&signType=MD5&timeStamp=1716000000
这个签名串中出现了 undefined，拿去计算 paySign 后再传给微信，微信按照标准参数重新计算时使用的是真实的 package 值，两次结果自然不一致，直接报签名错误。所以排查此类问题时，第一步不是怀疑密钥，而是把参与签名的源串完整打印出来，看是否包含 undefined 或 null。
二、后端二次签名的标准实现与常见坑
正确的做法是由后端统一生成二次签名，前端只负责调起支付，不在浏览器中拼装签名串。后端拿到统一下单返回的 prepay_id 后，构造一个有序的参数集合，按照ASCII码从小到大排序，拼接成 key1=value1&key2=value2 的形式，最后再拼接上商户API密钥，做MD5或HMAC-SHA256加密，转成大写得到 paySign。Java中可以用 TreeMap 自动排序，示例代码如下：
import java.util.Map;
import java.util.TreeMap;
import java.security.MessageDigest;
public class WxPaySignUtil {
public static String buildJsapiSign(String appId, String prepayId, String nonceStr, String timeStamp, String apiKey) throws Exception {
// package必须拼上prepay_id=前缀
String packageValue = "prepay_id=" + prepayId;
Map<String, String> params = new TreeMap<>();
params.put("appId", appId);
params.put("timeStamp", timeStamp);
params.put("nonceStr", nonceStr);
params.put("package", packageValue);
params.put("signType", "MD5");
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
String key = entry.getKey();
String value = entry.getValue();
if (value == null || value.trim().length() == 0) {
continue; // 空值不参与签名，但这里必须保证所有参数都有值
}
sb.append(key).append("=").append(value).append("&");
}
sb.append("key=").append(apiKey);
String signStr = sb.toString();
String sign = md5(signStr).toUpperCase();
return sign;
}
private static String md5(String input) throws Exception {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] digest = md.digest(input.getBytes("UTF-8"));
StringBuilder hex = new StringBuilder();
for (byte b : digest) {
String h = Integer.toHexString(0xff & b);
if (h.length() == 1) hex.append("0");
hex.append(h);
}
return hex.toString();
}
}
这段代码有几个必须注意的细节。第一，package 的值必须由 prepay_id= 加上统一下单返回的 prepayId 组成，不能直接传 prepayId，更不能把字段名写成 package 之外的名称。第二，timeStamp 必须是字符串类型，值取当前Unix时间戳的秒级字符串，不能是数字，否则某些JSON序列化时可能丢精度或变成科学计数法。第三，nonceStr 建议由后端生成，使用32位以内的随机字符串，避免使用固定值。第四，参与签名的参数名区分大小写，appId 的 I 是大写，timeStamp 的 S 是大写，写错后签名串参数名顺序或值都会出错。
另一个常见坑出现在使用Node.js或PHP这类弱类型后端时。例如Node.js中如果对象属性未定义，直接拼接会得到字符串 "undefined"；PHP中 null 拼接会变成空字符串，但前端拿到空字符串后可能又转成 undefined。所以后端在返回支付参数前，必须逐个字段做非空校验，确保每个值都有实际内容。可以用类似下面的判断逻辑：
// Node.js 后端返回前校验
const payParams = {
appId: config.appId,
timeStamp: Math.floor(Date.now() / 1000).toString(),
nonceStr: randomString(16),
package: 'prepay_id=' + prepayId,
signType: 'MD5'
};
const requiredKeys = ['appId', 'timeStamp', 'nonceStr', 'package', 'signType'];
for (const key of requiredKeys) {
if (typeof payParams[key] === 'undefined' || payParams[key] === null || payParams[key] === '') {
throw new Error('支付参数缺失: ' + key);
}
}
const signStr = requiredKeys.map(k => k + '=' + payParams[k]).join('&') + '&key=' + apiKey;
payParams.paySign = md5(signStr).toUpperCase();
这样在服务端就拦截了参数缺失的情况，不会再把带有 undefined 的签名串发给前端。同时要注意，不同编程语言对字符串大小写的处理不同，MD5结果最终必须转成大写十六进制字符串，微信验签时使用的大写结果，小写会直接导致签名错误。
三、前端调用前的参数校验与联调排查思路
即使后端已经做了校验，前端拿到支付参数后仍然建议在调起 wx.chooseWXPay 之前做一次完整的参数检查。因为实际项目中可能存在网关转发、字段映射或缓存导致的数据丢失。前端可以封装一个校验函数，遍历必需字段，发现 undefined、null 或空字符串时立即阻断并给出明确错误提示，而不是直接调起微信支付，否则用户只会看到模糊的“支付失败”。下面是前端校验示例：
function checkWxPayParams(params) {
const required = ['appId', 'timeStamp', 'nonceStr', 'package', 'signType', 'paySign'];
for (let i = 0; i < required.length; i++) {
const key = required[i];
const value = params[key];
if (typeof value === 'undefined' || value === null || value === '') {
console.error('微信支付参数缺失，字段：' + key);
return false;
}
if (key === 'package' && value.indexOf('prepay_id=') !== 0) {
console.error('package字段格式错误，应为prepay_id=xxx，当前值：' + value);
return false;
}
}
return true;
}
// 调用微信支付
if (checkWxPayParams(payParams)) {
wx.chooseWXPay({
appId: payParams.appId,
timestamp: payParams.timeStamp, // 注意这里微信接口参数名是timestamp，不是timeStamp
nonceStr: payParams.nonceStr,
package: payParams.package,
signType: payParams.signType,
paySign: payParams.paySign,
success: function (res) {
console.log('支付成功', res);
},
fail: function (res) {
console.error('支付失败', res);
}
});
}
特别注意前端调用微信支付接口时，传入的参数名是 timestamp，而不是签名时的 timeStamp。这是一个很容易混淆的点：签名串中使用 timeStamp，但 wx.chooseWXPay 的参数对象中写的是 timestamp。两者虽然都表示时间戳，但大小写不同，不能混用。如果后端返回的字段名叫 timeStamp，前端调用时取了 payParams.timestamp，又会得到 undefined，虽然不影响签名，但会导致调起参数错误。
联调时最有效的排查方法是在后端把签名源串以日志形式输出，前端也在控制台打印即将传给微信的完整参数，然后使用微信官方提供的“微信支付接口签名校验工具”输入源串和密钥，对比生成的签名是否一致。如果工具生成的签名与后端返回的 paySign 不一致，说明后端计算过程有误；如果两者一致但微信仍然报签名错误，则要检查 appId、商户号是否与统一下单时一致，或者密钥是否使用了APIv3密钥（JSAPI二次签名应使用APIv2密钥）。
四、完整修复示例与最终效果
为了更直观地展示修复过程，假设统一下单返回的 prepay_id 为 wx201410272009395522657a690389285100，商户AppID为 wx1234567890abcdef，API密钥为 192006250b4c09247ec02edce69f6a2d。后端按照标准算法生成支付参数后返回给前端，前端再进行校验和调起。修复后的签名源串应该类似：
// 修复后的签名源串示例 // appId=wx1234567890abcdef&nonceStr=5K8264ILTKCH16CQ2502SI8ZNMTM67VS&package=prepay_id=wx201410272009395522657a690389285100&signType=MD5&timeStamp=1716000000&key=192006250b4c09247ec02edce69f6a2d
这段源串中每个参数都有明确的值，没有 undefined 或 null。对该源串做MD5并转大写后得到的 paySign 才是有效签名。实际项目中只需把上面Java或Node.js代码中的变量替换成真实值即可。
修复之后，用户端调起微信支付不会再出现“支付签名验证失败”。如果仍然报签名错误，建议按以下顺序排查：第一，确认统一下单接口中的 appid、mch_id 与二次签名使用的 appId、商户号完全一致；第二，确认 package 字段的值是 prepay_id= 加统一下单返回的原始值，没有被截断或转义；第三，确认 timeStamp 是10位秒级字符串，不是13位毫秒；第四，确认API密钥是商户平台的APIv2密钥，且密钥字符串没有多余空格或换行；第五，抓取前端实际调起参数与后端日志做逐字节对比。把这几项检查清楚，签名串中参数值为 undefined 导致的签名失败基本都能解决。
微信JSAPI支付签名错误参数undefined修改时间：2026-09-29 08:11:59