支付宝沙箱环境应使用alipay-sdk-php v4.9.2版本，兼容PHP 7.2–8.2且不依赖Guzzle，需配置沙箱网关、正确密钥格式、严格参数排序签名，并确保notify_url公网可达、验签用php://input原样读取及手动点击买家“确认付款”完成流程。
支付宝沙箱环境怎么配通，alipay-sdk-php 用哪个版本
别碰 v5.0.0+ 的 SDK，它强制依赖 guzzlehttp/guzzle 7+ 和 PHP 8.0+，而沙箱调试阶段你大概率还在用 PHP 7.4 或 8.1 且不想升级 Guzzle。实际能稳跑沙箱的，是官方已归档但仍在维护的 alipay-sdk-php v4.9.2（对应 GitHub release tag v4.9.2）。这个版本不依赖 Guzzle，用原生 cURL 发请求，兼容 PHP 7.2–8.2，也支持沙箱所需的 https://openapi.alipaydev.com/gateway.do 地址。
安装命令直接写死版本：
composer require alipay/alipay-sdk-php:v4.9.2
常见错误现象：Call to undefined function GuzzleHttp\Promise\promise_for()——这就是装了新版 SDK 却没装 Guzzle 或版本不匹配导致的；还有人填错网关地址，把生产网关 openapi.alipay.com 粘贴进沙箱代码里，结果一直返回 invalid app_id。
- 沙箱配置必须在 支付宝开放平台 > 沙箱环境 里手动开启，并复制「应用私钥」和「支付宝公钥」（不是「应用公钥」）
-
app_id是沙箱应用页顶部显示的 16 位数字，不是你自己的商户号 - 私钥必须是 PKCS#1 格式（以
-----BEGIN RSA PRIVATE KEY-----开头），如果用 OpenSSL 生成过，记得加-traditional参数
调用 alipay.trade.page.pay 时总跳转失败或提示「签名错误」
签名错不是密钥错了，八成是参数拼接顺序或编码惹的祸。v4.9.2 SDK 要求所有请求参数必须按字典序升序排列后，再做 urldecode → trim → urlencode 三连处理，最后才拼签名串。SDK 内部做了，但如果你手写了 biz_content JSON 字符串又没严格格式化，就容易崩。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
-
biz_content必须是合法 JSON，且键名按字母序（比如out_trade_no必须在subject前面），推荐用json_encode($arr, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)生成 - 别手动拼
sign字段——SDK 的$aop->execute($request)会自动算并追加，你硬塞一个会冲突 - 跳转 URL 里不能带空格或中文未编码字符，
subject和body务必urlencode()后再塞进biz_content - 测试时打开日志：
$aop->debugInfo = true;，看 SDK 实际发出的请求体和签名原文
沙箱支付成功后，notify_url 收不到异步通知或验签失败
支付宝沙箱不会主动推送通知到本地 127.0.0.1 或内网地址，这是最常卡住的点。你得让服务器有公网可访问的 URL，哪怕只是临时用 ngrok http 8080 映射一下。另外，验签失败往往不是公钥不对，而是收到的 POST 数据被框架自动解析、转义或截断过。
关键动作：
- PHP 接收通知必须用
file_get_contents('php://input')原样读取原始 POST body，不能用$_POST——后者已被 PHP 自动 urldecode 且丢掉了原始签名字段顺序 - 验签前先用
parse_str()把原始 body 解成数组，再传给$aop->verifyNotify($params)，不要自己手解sign和sign_type - 响应必须是纯文本
success（无空格、无换行、无 HTML），返回HTTP 200，任何其他输出（如var_dump、BOM 头、UTF-8 BOM）都会让支付宝重试 - 沙箱通知地址需在开放平台「开发管理 > 沙箱应用 > 编辑」里手动填写，且必须是 HTTP 协议（HTTPS 在沙箱里有时会握手失败）
回调验签通过但 trade_status 总是 WAIT_BUYER_PAY，查不到交易
这不是代码问题，是沙箱支付流程没走完。你在沙箱买家账号（页面右上角切换）扫码或输入密码后，支付宝沙箱不会立刻更新状态，要手动点「确认付款」按钮（藏在支付成功页底部小字里），否则订单一直卡在待支付。很多人以为扫完码就完了，其实漏了这一步。
验证方式：
- 登录沙箱买家账号，进「账单」页面，找刚付的那笔，状态是「交易成功」才算真完成
- 同步返回的
redirect_url里带的out_trade_no可以拿去调alipay.trade.query主动查，别只信前端跳转参数 - 异步通知里的
trade_status只有TRADE_SUCCESS或TRADE_CLOSED才代表终态，WAIT_BUYER_PAY是中间态，可能持续几分钟
沙箱里最麻烦的其实是「模拟真实链路」这件事本身：它要求你同时操作两个账号（商户 + 买家）、手动触发多个步骤、还要盯住不同页面的状态反馈。一旦某个环节没点到位，后面所有验签、查询、发货逻辑都对不上——这不是代码缺陷，是交互路径没跑通。
