优先使用 composer require lokielse/omnipay-alipay，它兼容主流框架、封装完整支付流程；密钥配置须严格区分应用私钥与支付宝公钥，且沙箱与正式环境公钥不可混用。
composer require 支付宝 SDK 时提示找不到包
支付宝官方没维护 Composer 可直接安装的 alipay 包，社区主流用的是 openpay/alipay 或更稳定的 lokielse/omnipay-alipay（基于 Omnipay）。但直接 composer require alipay 肯定失败——因为不存在这个包名。
实操建议：
- 优先用
composer require lokielse/omnipay-alipay：兼容 Laravel、ThinkPHP 等主流框架，封装了支付、查询、退款等完整流程 - 如果项目已用 Omnipay，只需再装驱动：
composer require omnipay/alipay（注意不是alipay单独） - 避免用老旧的
zhaofan/AlipayAopClient：PHP 8+ 下部分方法会报Deprecated: Required parameter $xxx follows optional parameter - 装完后检查
vendor/lokielse/omnipay-alipay是否存在，别只看 composer.json 是否写进去了
支付宝公钥私钥配错导致 sign error
调用 purchase() 或 completePurchase() 时抛出 Invalid signature 或 sign error，90% 是密钥配置翻车。支付宝要求「应用私钥」签名、「支付宝公钥」验签，但很多人把「应用公钥」当成「支付宝公钥」贴进去。
实操建议：
- 生成密钥必须用支付宝提供的
openssl命令或官方工具，别用第三方在线生成器——格式（PKCS#1/PKCS#8）、换行、头尾标记（-----BEGIN RSA PRIVATE KEY-----）全得对 -
alipay_public_key的内容，要从支付宝开放平台「开发者中心 → 应用详情 → 公钥管理」里「查看支付宝公钥」复制，不是你自己上传的应用公钥 - Laravel 中如果通过
config/services.php配置，确保值没被 .env 覆盖或 trim 掉换行符；可用dd(strlen(config('services.alipay.public_key')))检查长度是否异常短 - 沙箱环境和正式环境的公钥完全独立，切勿混用
notify_url 回调收不到或验签失败
用户付款后，你的 notify_url 没触发，或触发了但 $gateway->completePurchase()->send() 报 Invalid response，常见于服务器环境或参数传递问题。
实操建议：
- 支付宝回调只支持 HTTP 200 响应体为纯字符串
success（不能带空格、换行、HTML、JSON），返回任何其他内容（包括{"status":"ok"}）都会重试 15 次后丢弃 - 确认服务器没开 CSRF 防护（如 Laravel 的
VerifyCsrfToken中间件），需在app/Http/Middleware/VerifyCsrfToken.php的$except加上/alipay/notify - 不要在回调里做耗时操作（如发邮件、写日志到慢盘），先快速返回
success，再用队列处理后续逻辑 - 用
file_get_contents('php://input')手动捕获原始 POST 数据验签，别依赖$_POST——支付宝回调是application/x-www-form-urlencoded，但某些 Nginx + PHP-FPM 组合会丢字段
PHP 8.1+ 下 use Alipay\... 报 Class not found
升级 PHP 后，原来能跑的支付宝代码突然报 Class "Alipay\AopClient" not found，不是自动加载失效，而是命名空间或类路径不匹配。
实操建议：
-
lokielse/omnipay-alipay不提供Alipay\*命名空间，它走的是Omnipay\Alipay\*；别抄旧教程里的use Alipay\AopClient - 如果你非要用原生 SDK，推荐改用
alipaysdk-php（GitHub 上活跃维护的 fork），它支持 PHP 8.2，且自动注册 PSR-4 加载 - 运行
composer dump-autoload -o强制刷新 autoload，尤其在切换分支或手动改过 vendor 后 - 检查
composer show lokielse/omnipay-alipay输出的版本号，v3.x 起要求 PHP >= 7.4，v4.x 起要求 >= 8.0
密钥格式、回调响应体、PHP 版本与包版本的对应关系，这几处一错，调试时间远超集成时间。别急着写业务逻辑，先用支付宝沙箱的「通用下单 + 同步通知」跑通最小闭环。
