TP6接口签名验证失败的核心原因是服务端重算签名时与客户端逻辑存在细微偏差，需严格统一参数、顺序、编码、密钥、时间窗口五要素，并确保请求头（appid、timestamp、nonce、X-Signature）齐全合规，重算过程须完全复现客户端步骤。
TP6接口签名验证失败，核心问题不是算法写错，而是服务端重算签名时与客户端原始计算过程存在细微偏差。只要参数、顺序、编码、密钥、时间窗口这五点有一处不一致，hash_equals()就会返回false，验签即失败。
关键头部必须齐全且合规
服务端收到请求后，需第一时间提取并校验以下四个请求头：
-
appid：必须存在，且在数据库或配置中可查到对应
app_secret - timestamp：标准 Unix 时间戳（秒级），服务端要检查是否在允许窗口内（如±300秒）
- nonce：长度≥10位的随机字符串，Redis中需查重，避免重放
-
X-Signature（或约定名如
signature）：不能为空，且为小写十六进制字符串（如32位MD5）
重算签名必须严格还原客户端逻辑
验签中间件中重算签名，不能凭印象拼接，而要完整复现客户端步骤：
- 合并所有参与签名的参数：GET参数 + 解析后的body（JSON或form-data）
- 剔除
sign、sign_version、appid等无关字段（先isset()再unset，防警告） - 对参数数组执行
ksort($params, SORT_STRING)，确保字典序升序 - 遍历拼接
key=value，每个value单独rawurlencode()（不是urlencode()） - 拼接完整路径（不含域名和协议）+
&+ 排序后参数串 +&+appid=xxx&nonce=yyy×tamp=zzz - 末尾追加
$appSecret（注意：不是app_key，且配置中不能含BOM、换行、全角空格） - 统一用UTF-8编码后，执行
hash_hmac('sha256', $str, $secret)，输出小写hex
常见隐藏坑与调试建议
这些细节不报错，但会让重算结果永远对不上：
- 客户端用
http_build_query()自动编码，服务端却手动拼接未rawurlencode() - timestamp单位错配：客户端传毫秒，服务端按秒解析（或反之）
- JSON body反序列化后字段顺序改变，或
null/""处理不一致 - 从Header取值时未
trim()，或大小写混淆（如传X-AppId，代码取appid） -
app_secret在.env里带不可见字符（可用hexdump -C排查）
调试时，在比对前打印完整参与计算的字符串（脱敏后），例如：
[DEBUG] signing string: /api/user?uid=123&type=normal&appid=abc&nonce=xyz×tamp=1724774160&secret=your_real_secret
中间件注册与执行时机
签名校验必须放在业务逻辑之前，且顺序关键：
- 中间件类须在
app/middleware.php中注册，格式为\app\middleware\CheckSign::class（开头反斜杠不可少） - 必须排在
\think\middleware\AllowCrossDomain::class之后、其他业务中间件之前 - 若注册位置错误或命名空间写错，中间件完全不执行，验签形同虚设
