.net SDK 调用 alipay.trade.precreate 报 sign check fail 如何排查？

2026-10-24支付阿杰

结论

这个错误通常不是 alipay.trade.precreate 的业务参数有问题，而是 .NET SDK 验证支付宝响应签名时失败。

alipay.trade.wap.pay 能正常生成支付链接，不代表支付宝公钥配置正确。该接口通常通过 PageExecute 在本地生成请求表单或 URL，主要使用应用私钥为请求签名，不一定会验证支付宝的响应签名。alipay.trade.precreate 则通过 Execute 获取同步响应，SDK 随后会使用支付宝公钥验签。

建议优先检查以下几项：

SDK 中配置的是“支付宝公钥”，不是“应用公钥”。
AppId、支付宝公钥和应用私钥来自同一个应用，并且属于同一环境。
sign_type 与应用配置一致，通常是 RSA2。
SDK 初始化参数的顺序是否正确。
网关响应是否被代理、日志组件或业务代码修改。
当前 SDK 版本能否正确解析该接口返回的 JSON。

先分清两类密钥

支付宝开放平台的普通公钥模式通常涉及两套密钥：

应用私钥：保存在商户侧，用来为请求签名。
支付宝公钥：从支付宝开放平台获取，用来验证支付宝返回结果的签名。

不要把“应用公钥”填入 SDK 的 alipayPublicKey 参数。应用公钥由应用私钥推导生成，需要上传到开放平台，但它不能用于验证支付宝的响应签名。

alipay.trade.wap.pay 能够运行，只能在一定程度上说明应用私钥可以用于生成请求签名，无法据此排除支付宝公钥配置错误。

检查 SDK 初始化代码

普通公钥模式可以参考以下初始化代码：

using Aop.Api;

string gateway = "https://openapi.alipay.com/gateway.do";
string appId = "你的 AppId";
string appPrivateKey = "应用私钥";
string alipayPublicKey = "支付宝公钥";

IAopClient client = new DefaultAopClient(
    gateway,
    appId,
    appPrivateKey,
    "json",
    "1.0",
    "RSA2",
    alipayPublicKey,
    "UTF-8",
    false
);

不同版本的 .NET SDK 可能有不同的构造函数重载，具体参数应以项目实际引用版本的定义为准。尤其要检查参数位置，避免传错 charset、signType 或公钥。

末尾的 false 通常表示传入的是密钥内容，而不是密钥文件路径。它不是“关闭响应验签”的开关，所以改成 false 后仍然报错并不意外。如果传入的实际内容是文件路径，应按照当前 SDK 对该参数的定义配置。

密钥内容通常应为连续的 Base64 字符串，例如：

string alipayPublicKey =
    "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...";

如果密钥从 PEM 文件读取，需要确认当前 SDK 是否接受包含以下头尾的内容：

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

部分 SDK 或特定版本要求去掉头尾、空格和换行。在没有确认格式要求之前，不要随意转换 PKCS#1、PKCS#8 或公钥格式。

核对应用和运行环境

以下配置必须来自同一个应用：

appId
应用私钥
上传到开放平台的应用公钥
开放平台显示的支付宝公钥
签名算法
网关环境

正式环境一般使用：

https://openapi.alipay.com/gateway.do

沙箱环境需要使用对应的沙箱网关、沙箱 AppId 和沙箱支付宝公钥，不能与正式环境的密钥混用。

如果应用重新设置过接口加签方式，或者更换过应用公钥，本地保存的支付宝公钥可能已经不再匹配当前配置。此时应从该 AppId 对应的开放平台配置页面重新复制，不要继续使用其他项目中的配置。

使用最小请求排除业务代码干扰

先只使用必要参数调用接口：

using Aop.Api;
using Aop.Api.Request;
using Aop.Api.Response;

AlipayTradePrecreateRequest request =
    new AlipayTradePrecreateRequest();

request.BizContent = """
{
  "out_trade_no": "ORDER_202609090001",
  "total_amount": "0.01",
  "subject": "测试订单"
}
""";

try
{
    AlipayTradePrecreateResponse response = client.Execute(request);

    if (response.IsError)
    {
        Console.WriteLine($"Code: {response.Code}");
        Console.WriteLine($"SubCode: {response.SubCode}");
        Console.WriteLine($"SubMsg: {response.SubMsg}");
    }
    else
    {
        Console.WriteLine(response.QrCode);
    }
}
catch (Exception ex)
{
    Console.WriteLine(ex.ToString());
}

每次测试都应使用唯一的 out_trade_no。如果最小请求仍在解析业务响应前报 sign check fail，应重点排查响应验签、密钥和 SDK，而不是 BizContent 中的业务字段。

获取原始响应进行定位

需要记录支付宝网关返回的原始 HTTP 响应，而不是反序列化后重新生成的 JSON。

典型响应结构如下：

{
  "alipay_trade_precreate_response": {
    "code": "10000",
    "msg": "Success",
    "out_trade_no": "ORDER_202609090001",
    "qr_code": "https://qr.alipay.com/..."
  },
  "sign": "..."
}

验签使用响应节点对应的原始内容和顶层 sign。如果先解析 JSON，再格式化、调整字段顺序或重新序列化，空格、转义方式和字段顺序都可能发生变化，使用这些修改后的内容验签会失败。

原始响应可以帮助判断问题出在哪一层：

如果返回 HTML，可能是请求发往了错误网关，也可能被代理、WAF 或登录页拦截。
如果返回内容为空或被截断，应检查网络代理、超时设置和响应读取逻辑。
如果返回标准 JSON 且包含 sign，应重点核对支付宝公钥和 sign_type。
如果 SDK 提示无法解析 JSON，应检查响应中是否有 BOM、额外日志或非法字符，并确认 SDK 是否过旧。
如果原始响应验签成功，但 SDK 仍然报错，更可能是 SDK 解析或版本兼容问题。
如果原始响应也无法通过验签，更可能是公钥、AppId 或环境不匹配，也可能是响应内容被修改。

不要只打印 response.Body 等已经过 SDK 处理的对象。如果 SDK 支持 HTTP 调试日志，可以开启日志并保存完整的网关响应。记录时要做好脱敏，避免输出应用私钥、用户信息或完整交易数据。

检查 SDK 版本和引用冲突

如果密钥、环境和原始响应都没有异常，还需要检查：

项目是否同时引用了多个版本的支付宝 SDK。
NuGet 包是否与手工复制的 DLL 并存。
发布目录中是否残留旧版 DLL。
运行中的进程加载的程序集版本是否与开发环境一致。
当前版本是否支持正在使用的签名算法和响应格式。

升级 SDK 前，先记录当前包名和版本，并在测试环境完成验证。不要只替换 DLL，却保留与其不兼容的依赖程序集。

常见误区

将最后一个 `false` 当成验签开关

这个参数通常控制传入的密钥是字符串内容还是文件路径，不能解决支付宝公钥错误，也不应该通过关闭验签来绕过问题。

用应用公钥验证支付宝响应

这是常见的配置错误。验证支付宝响应签名需要使用支付宝公钥。

认为 WAP 支付正常就说明所有密钥正确

PageExecute 成功生成表单，只能说明本地构造请求的过程没有立即失败。它与 Execute 收到响应后的验签流程不同。

对响应 JSON 重新序列化后再验签

签名针对的是原始待验签内容。重新排版、改变转义方式或调整字段顺序后，验签结果将不再可靠。

临时关闭验签继续上线

响应验签用于确认数据确实来自支付宝，并且未被修改。即使某个 SDK 版本支持跳过验签，也只能用于短时间定位问题，不能作为生产环境的解决方案。