支付宝SDK私钥必须为无密码PEM格式，回调地址需与开放平台配置完全一致，且沙箱与正式环境配置须严格隔离。
支付宝 SDK 的私钥配置必须用 PEM 格式，且不能带密码
支付宝官方 PHP SDK（alipay-sdk-php）只接受 PEM 编码的 RSA2 私钥，且明确拒绝带密码保护的密钥文件。如果你用 openssl genrsa -aes256 生成了带密码的私钥，SDK 初始化时会直接抛出 openssl_sign(): supplied key param cannot be coerced into a private key 错误。
正确做法是：用以下命令生成无密码 PEM 私钥：
openssl genrsa -out app_private_key.pem 2048 openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem
然后将 app_private_key.pem 文件内容（含 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY----- 行）完整复制进 SDK 配置的 private_key 字段；不要 base64 解码、不要删换行、不要转成单行字符串。
- 公钥（
app_public_key.pem）需上传到支付宝开放平台「应用公钥」处，不是开发者公钥 - 支付宝返回的
alipay_public_key是平台公钥，必须从开放平台「查看支付宝公钥」页面复制，不能自己生成 - 如果用 Windows 记事本编辑过私钥文件，可能引入 BOM 或 CR/LF 混乱，建议用 VS Code 或 Vim 保存为 UTF-8 无 BOM 格式
回调地址必须在支付宝后台显式配置，且协议/域名/端口需完全一致
支付宝验签回调请求时，会严格校验 notify_url 是否与开放平台「应用信息 → 开发信息 → 回调地址」中填写的一致——包括 http 还是 https、是否带 www、端口号是否显式写出（如 :8080）、末尾是否带斜杠。
立即学习“PHP免费学习笔记（深入）”；
常见错误现象：notify_url 在代码里写的是 https://example.com/pay/notify，但后台填的是 https://www.example.com/pay/notify/，会导致支付宝持续重发通知，而你的接口始终收不到有效请求。
- 本地开发调试可用
ngrok或localtunnel映射公网地址，但必须把映射后的完整 URL 填进后台，不能填localhost:8000 - SDK 初始化时传入的
notify_url参数只是用于下单接口拼参，不替代后台配置；两者必须一致，否则验签失败 - 回调接口必须能被公网访问，且响应时间建议控制在 3 秒内，超时支付宝会认为失败并重试
验签逻辑必须用 SDK 提供的 verifyNotify()，不能手写签名比对
支付宝回调参数是普通 POST 表单（application/x-www-form-urlencoded），但签名字段 sign 不参与验签，且所有参数需按字典序排序、键值拼接、UTF-8 编码后，再用支付宝公钥验签。手写逻辑极易出错，比如忽略空值过滤、误含 sign_type、未 urldecode 参数值等。
正确做法是：用 SDK 的 AlipayTradeService::verifyNotify() 方法，它已处理全部边界情况：
$alipay = new \AlipayTradeService($config);
$result = $alipay->verifyNotify($_POST); // 自动解析 $_POST 并验签
if ($result) {
// 验签通过，处理业务逻辑（查订单、改状态、发消息）
echo 'success'; // 必须原样输出 'success'，不能加空格或 HTML
} else {
echo 'fail';
}
- 输出必须是纯文本
success或fail，不能是 JSON、不能有 HTTP 头、不能有额外空格或换行 -
verifyNotify()内部会自动过滤sign和sign_type字段，你无需手动剔除 - 若用 Swoole 或 Hyperf 等框架，注意
$_POST可能为空，需从原始输入流解析：parse_str(file_get_contents('php://input'), $data)，再传给verifyNotify($data)
沙箱环境和正式环境的配置项不能混用
支付宝沙箱环境（https://openapi.alipaydev.com）和正式环境（https://openapi.alipay.com）使用完全独立的密钥对、APP_ID 和公钥。一个常见疏漏是：本地调试用沙箱，上线后忘了把 gatewayHost、app_id、alipay_public_key 全部切换成正式环境的值，导致支付成功但回调验签一直失败。
- 建议用环境变量区分配置，例如：
ALIPAY_ENV=sandbox或ALIPAY_ENV=prod，不同环境加载不同$config数组 - 沙箱 APP_ID 和密钥在开放平台「沙箱环境」页面获取，不是主账号的 APP_ID
- 正式环境首次上线前，务必在「应用管理 → 应用详情 → 沙箱环境」关闭沙箱开关，否则部分接口可能仍走沙箱链路
