UniApp多端支付完整实践：从后端设计到前端封装

第一次在 UniApp 项目里接支付时我是照着网上最热门的 demo 抄的。拷贝完代码在微信开发者工具里点了一下支付秒弹“支付成功”当时我一拍大腿多端支付也不过如此。后来到了真机联调iOS 唤起微信后黑屏、Android 掉不起来、H5 直接报chooseWXPay is not a function我才意识到UniApp 的uni.requestPayment只是把多端入口收拢在了一起但每一端背后的支付流程依然是微信支付、支付宝支付各自的门规。这篇文章就把我后来在几个实际项目里沉淀下来的一套完整的多端支付方案写清楚后端接口怎么设计、前端怎么封装、各个平台的配置怎么查、订单状态怎么确认、线上掉单怎么兜底。不管你是刚接触 UniApp还是已经写过一段时间但一直被支付问题卡着按着这条链路走完基本就能做到“一套业务代码多端都能安稳收钱”。1. 先建立正确认知多端支付的本质是“一套订单体系 N 种拉起渠道”1.1 别把“多端”理解成“同一个接口调三遍”很多人一看到 UniApp 能一套代码跑小程序、App、H5就默认支付也应该“一套代码通吃”。这个预期是错的。UniApp 能统一的是 JavaScript 层的调用方式但每一端背后的支付产品、拉起参数、签名规则、回调机制都是平台各自定义的。你真正要写的不是“三个 requestPayment”而是“一个订单系统 三条符合各自平台规则的对接逻辑”。我更喜欢把多端支付拆成两层看业务层创建订单、查询订单状态、超时关闭、退款、对账这些业务逻辑对所有端都是共用的。渠道层微信小程序支付、App 微信支付、App 支付宝支付、H5 微信支付、H5 支付宝支付每一路都有自己的下单接口和参数规范。UniApp 能统一的是渠道层里“唤起支付”的那一步调用但也只是把入口统一了传什么参数、怎么签名、支付结果从哪儿回来每一路仍然是独立的。1.2 决定你工作量的不是 UniApp而是每端的支付产品规则先看一张对照表这是我在项目里给自己画的支付产品地图运行端常见支付产品前端拉起方式结果通知方式微信小程序微信小程序支付JSAPIuni.requestPayment传小程序专用参数后端异步通知AppApp 微信支付uni.requestPayment传入orderInfo后端异步通知AppApp 支付宝支付uni.requestPayment传入orderInfo后端异步通知H5 嵌微信公众号公众号支付JSAPI引入微信 JSSDKwx.chooseWXPay后端异步通知H5 微信外浏览器微信 H5 支付跳转mweb_url收银台后端异步通知H5 支付宝手机网站支付跳转支付宝收银台地址后端异步通知 同步返回表格列完你就发现了uni.requestPayment只覆盖了表格里的前三行。H5 那三行里iframe 内嵌 JS 一般不能用实际做业务时后端会返回一个收银台跳转地址前端直接window.location.href跳过去支付完成后再由后端异步通知订单结果。这个认知很重要因为很多 H5 支付问题出在“想用一个uni.requestPayment打天下”。一旦你把“订单接口”和“拉起方式”分开看待后面所有代码和排错逻辑都会清晰很多。2. 后端才是多端支付的命门下单、签名、回调验签2.1 用一套 createOrder 接口返回“前端可直接用”的支付参数虽然我们是前端开发者但多端支付后端接口设计的合理与否直接决定前端代码要写多少分支。我的建议是后端不要把所有下单逻辑堆给前端也不要只返回“预支付 ID”让前端自己去拼签名。前端应该拿到的是“拿来就能拉起收银台的参数”。我在项目里习惯这样设计接口POST /api/pay/create 请求体 { orderId: ORD2025010100001, payChannel: wxpay_mWeb, // 前端根据当前环境传入的渠道标识 platform: h5 // mp-weixin / app / h5 } 响应体 { code: 0, data: { payOrderId: PAY2025010100001, provider: wxpay, // 告诉前端调 uni.requestPayment 还是跳转 payParams: { ... }, // 不同渠道的支付参数整体塞在这个对象里 h5PayUrl: https://... // H5 渠道时前端直接 location.href } }后端在这个接口里要做的核心事情有三件查单/建单确认订单状态未支付、金额未被篡改创建一条支付流水单。调对应渠道的下单接口微信小程序支付走 JSAPI 下单App 微信支付走 APP 下单H5 微信外浏览器走 H5 下单支付宝 App 走手机 App 支付下单H5 支付宝走手机网站支付下单。生成并返回前端需要的支付参数签名必须在这里完成后端前端不接触商户私钥。这里有几个容易被后端忽略、却被前端反复坑的点金额单位微信支付和支付宝的 API 金额单位精确到分业务系统里如果是以元入库接口层一定要做一次Math.round(amount * 100)不要直接传浮点数浮点计算会导致个别订单差一分钱。订单号唯一性同一个业务订单重复点击下单时后端应该幂等处理返回同一个支付参数而不是生成多笔预支付单否则用户会看到重复扣款。超时关闭微信、支付宝对预支付订单都有默认的失效时间通常后端下单时传入time_expire更好不能放任订单无限有效否则用户隔天再支付会出现金额对不上、库存已变等一堆问题。说白了后端这个接口做得越“胖”前端就越轻松项目排错就越快。2.2 回调验签与幂等不验签等于给业务留了一个流量入口级的洞支付成功之后微信和支付宝会发送异步通知到后端接口。这个回调处理是支付系统里最容易出问题的地方。安全上的要求是明确的必须验签、必须校验金额、必须幂等发货。我见过不少项目在校验流程上偷懒只判断trade_status是SUCCESS或TRADE_SUCCESS就更新订单状态。这种情况遇到正常支付没问题一旦遇到伪造的回调、重复推送、通知乱序就会出现“订单还没支付就发货”或者“重复发货”的线上事故。我自己在项目里沉淀的回调处理流程是这样的收到异步通知 - 解析报文 - 用平台公钥/证书验签失败直接丢弃 - 根据业务订单号查本地订单 - 比较回调金额与本地订单金额是否一致不一致记日志并返回失败 - 原子更新订单状态仅当订单处于“未支付”时才更新为“已支付” - 更新成功后触发“支付成功”业务动作发消息队列或异步任务 - 返回微信/支付宝要求的成功应答以微信支付 V3 为例核心伪代码大概是// 伪代码实际实现以你的开发语言和微信 SDK 为准 function handleWxNotify(rawBody, signatureInfo) { if (!verifyWxSign(rawBody, signatureInfo)) { return { code: FAIL }; } const notifyData JSON.parse(rawBody); const { out_trade_no: bizOrderNo, transaction_id: tradeNo, amount } notifyData; const order await orderService.getByOrderNo(bizOrderNo); if (!order) { logger.error(支付回调找不到订单, bizOrderNo); return { code: FAIL }; } if (!orderService.isUnpaid(order)) { // 已经处理过的通知直接返回成功避免微信重复推送 return { code: SUCCESS }; } if (amount.total ! order.amount) { logger.error(支付回调金额不一致, order.orderNo, amount.total); return { code: FAIL }; } const updated await orderService.markPaidIfUnpaid(order, tradeNo); // 用数据库乐观锁/条件更新保证同一时间只有一个线程把状态改成已支付 if (updated) { await mq.send({ topic: ORDER_PAID, data: { orderNo: bizOrderNo } }); } return { code: SUCCESS }; }这段代码里有两个关键习惯强烈建议保留验签失败和订单不存在都要返回非成功应答让第三方继续重试通知不轻易吞掉异常。用“仅当订单是未支付状态才更新为已支付”的原子条件防止回调乱序或重复通知导致重复发货。这一步是最廉价的幂等方案也是我最推荐先加上的。还有个细节回调里的金额必须校验但前端返回的成功回调是不需要信任的。前端success只用于提升用户体验真正确定订单是否支付成功要以后端回调更新状态为准。这也是后面第 5 节轮询逻辑能够成立的根基。3. 前端适配uni.requestPayment 各端差异与统一封装3.1 三种典型的拉起方式后端接口设计好了前端就只做一件事根据渠道把支付参数交给正确的“拉起器”。第一种微信小程序支付微信小程序里uni.requestPayment可以直接使用但参数是独立字段和 App 的调用方式完全不一样uni.requestPayment({ provider: wxpay, timeStamp: payParams.timeStamp, // 注意大写 S nonceStr: payParams.nonceStr, // 注意大写 S package: payParams.package, // 形如 prepay_idwx... signType: payParams.signType, // 小程序通常为 RSA / MD5 paySign: payParams.paySign, success: (res) {}, fail: (err) {} });这里package和paySign的值必须来自后端下单接口前端永远不应该自己拼。第二种App 微信支付和 App 支付宝支付App 端调用方式和微信小程序不同主要靠orderInfo这一个字段把整个支付串传下去// App 微信支付 uni.requestPayment({ provider: wxpay, orderInfo: payParams.orderInfo, // 后端返回的微信 App 支付参数串 success: () {}, fail: (err) {} }); // App 支付宝支付 uni.requestPayment({ provider: alipay, orderInfo: payParams.orderInfo, // 支付宝签名后的 orderInfo 字符串 success: () {}, fail: (err) {} });orderInfo具体是什么结构取决于你后端用的是哪个平台的 SDK 参数格式。前端不关心里面是 JSON 还是拼接字符串只需要原样传下去。这也是为什么我上面强调“后端返回拿来即用的参数”能明显降低前端出错的概率。第三种H5 渠道的支付H5 是大多数 UniApp 项目里最容易翻车的场景。先说结论H5 端不能完全依赖uni.requestPayment拉起微信支付。如果 H5 页面是嵌在微信公众号里需要后端生成 JSAPI 下单参数并在页面里配置微信 JSSDK。配置成功之后用wx.chooseWXPay拉起支付wx.chooseWXPay({ timestamp: payParams.timeStamp, nonceStr: payParams.nonceStr, package: payParams.package, signType: payParams.signType, paySign: payParams.paySign, success: (res) { // 用户支付成功但严格说这里只是“支付完成”订单状态还是要轮询后端 } });如果 H5 页面运行在微信外的浏览器比如支付宝 H5、抖音内打开的链接等则需要后端返回一个收银台跳转地址h5PayUrl前端直接做跳转window.location.href data.h5PayUrl;支付完成后渠道方会回调后端前端再主动向前端接口查询订单状态完成 UI 刷新。注意 H5 的window.location.href跳走后页面可能直接跳离了当前 SPA所以一定要在订单页保存好“待支付订单号”并在用户返回后继续查询状态。3.2 把差异收敛成同一个 pay 函数有了上面的认知前端封装其实就很机械了。我在项目里统一封装了一个pay.js所有业务页面只调用pay.start({ orderId, payChannel })内部再按平台条件编译去走不同分支。// pay.js import { getPayParams, getBizOrderStatus } from /api/pay; export async function startPayment({ orderId, payChannel, platform }) { // 1. 后端创建支付单并返回支付参数 const payResult await getPayParams({ orderId, payChannel, platform }); // 2. 根据返回参数判断该走哪种拉起方案 if (payResult.h5PayUrl) { // H5 渠道直接跳转收银台 window.location.href payResult.h5PayUrl; return { status: pending }; } // 3. 小程序和 App 走普通派发 return new Promise((resolve, reject) { uni.requestPayment({ ...getProviderConfig(payResult), success: () resolve({ status: completed }), fail: (err) { const errCode normalizePayError(err); if (errCode cancel) { resolve({ status: cancel }); } else { reject(err); } } }); }); }这里最关键的是getProviderConfig它负责把后端返回的payParams映射成当前平台需要的字段。因为微信小程序和 App 的字段名、大小写都不一样一定要在这里做一次转换而不是在业务页面里到处处理。我自己会在getProviderConfig里用条件编译明确区分平台function getProviderConfig(payResult) { const params payResult.payParams; // #ifdef MP-WEIXIN return { provider: wxpay, timeStamp: params.timeStamp, nonceStr: params.nonceStr, package: params.package, signType: params.signType, paySign: params.paySign }; // #endif // #ifdef APP-PLUS return { provider: params.provider, // wxpay / alipay orderInfo: params.orderInfo }; // #endif // #ifdef H5 // H5 正常走 location.href不应进入到这里 return {}; // #endif }这段封装的收益很直接业务页面永远不关心当前是 App、小程序还是 H5只管调一个函数拿一个统一的结果。最多在页面里判断status cancel时弹一句“你取消了支付”。3.3 H5 嵌公众号时微信 JSSDK 的配置是绕不开的坎很多项目是“UniApp 开发 H5 嵌入微信公众号”这种场景下微信支付必须在当前公众号的 JSAPI 域名下完成。前端需要先在页面里注入并配置 JSSDKimport wx from weixin-js-sdk; // 通过接口从后端获取 JS-SDK 签名 const { appId, timestamp, nonceStr, signature } await getJsSdkConfig({ url: window.location.href.split(#)[0] // 必须去掉 hash用当前完整 URL 做签名 }); wx.config({ debug: false, appId, timestamp, nonceStr, signature, jsApiList: [chooseWXPay] }); wx.ready(() { // 此时才能调用 wx.chooseWXPay });这里最常见的坑是签名用的 URL 和当前页面 URL 不一致。SPA 路由多走 history 模式还好如果是 hash 模式签名时一定要去掉#后面的部分否则wx.config大概率报invalid signature。另外JSSDK 签名成功过一次后会缓存 7200 秒如果后端签名接口实现有问题联调阶段经常出现“第一次能付三分钟后报 invalid signature”排查起来很折腾。我的建议是在后端给 JSSDK 签名单独加一个日志接口方便前端把url、timestamp、nonceStr、signature连成一串打出来和微信官方签名工具对比生成结果一下子就能定位是 URL 问题还是后端签名问题。4. 配置清单与联调准备几个我反复检查的配置点4.1 manifest.json 和原生工程配置UniApp 项目里支付能力依赖manifest.json的 App 模块配置。进到App 模块配置把Payment勾选上并填入对应的支付参数微信支付需要填开放平台申请到的appIdiOS 还要填Universal Links。支付宝支付需要填支付宝开放平台的应用appIdiOS 端通常还需要配置 URL Scheme便于支付宝支付完成后回跳 App。Android 端还需要注意包名一致性。微信开放平台里填的包名、manifest.json里的包名、你实际打出的 APK 包名三者必须完全一致。签名也一样微信支付 SDK 在 Android 端会校验应用签名如果开发环境签名和线上环境签名不一致就会出现“正式包可以支付开发包不能支付”的诡异问题。这块在云打包时尤其容易踩坑。用 HBuilderX 云打包时要注意有没有上传正确的 Keystore并确保微信开放平台里填的是同一个证书的 MD5 签名。我遇到过项目换了台电脑重新云打包后包名没变但签名变了结果排查了一整天才发现是打包机上的 keystore 被换了。4.2 商户平台侧的配置商户平台的配置点是联调前必须逐项核对的内容配置项位置容易出错的地方支付授权目录微信商户平台H5 项目里目录末尾多一个斜杠、少一个斜杠都会造成拉起失败回调域名微信商户平台必须是公网可访问的 https 域名不能带路径APIv3 密钥 / API 证书微信商户平台证书文件只放在后端绝不下发到前端支付宝公钥 / 应用私钥支付宝开放平台沙箱公钥混进真实环境导致验签永远失败App 包名 / 应用签名微信开放平台同步给后端联调时要确保是同一个环境其中“支付授权目录”是 H5 微信支付里特别坑的一个配置。它精确到路径比如你的 H5 项目支付页面路径是https://shop.xxx.com/h5/pay那授权目录可以配成https://shop.xxx.com/h5/。如果项目里路由带 hash比如https://shop.xxx.com/h5/#/pay那么授权目录也要按原始 URL 的路径来配。很多时候前端拉起支付报“当前页面 URL 未注册”都是这个目录的问题。4.3 沙箱环境和真实环境的切换支付宝有一个完整的沙箱环境用于模拟接入。微信没有独立的支付宝那种沙箱但可以用“真实环境中 0.01 元单笔测试”来模拟。这里最需要注意的是环境配置必须用统一开关来控制。我在项目里会在后端配置中心维护一个pay.env字段sandbox和production分开。前端不感知沙箱逻辑只在后端根据开关选择对应的支付宝应用私钥、支付宝公钥和回调地址。这种隔离的好处是避免出现最让人血压升高的事故联调阶段把一笔 0.01 元的单子打到了真实生产账户或者生产环境把支付回调里的验签证书读成了沙箱证书。5. 完整流程串联从创建订单到支付结果确认5.1 一单支付的生命周期把所有代码串起来之后一次完整的支付流程是这样的用户在业务页面提交订单订单状态为“待支付”。前端调POST /api/pay/create把orderId、payChannel、platform传给后端。后端创建支付单、调第三方下单接口、生成签名返回支付参数或跳转地址。前端根据参数拉起支付收银台用户在第三方页面完成支付。第三方支付平台异步通知后端后端验签、核对金额、更新订单状态。前端在支付结果不确定时主动轮询GET /api/pay/status直到订单状态变为“已支付”或“已关闭”。业务后端收到订单已支付的消息后执行发货、开票、发放权益等动作。我把每步的职责整理成一张清单步骤责任方结果创建业务订单业务后端订单待支付创建支付单并调下单接口支付后端返回支付参数拉起支付收银台前端用户看到支付界面发起支付第三方平台用户完成扣款异步通知第三方平台 - 支付后端订单改为已支付轮询查单前端 - 业务后端UI 更新为已支付发货/权益发放业务后端完成业务闭环5.2 前端怎么处理取消、超时和掉单支付结果天然是“不确定”的。uni.requestPayment的success不等于订单一定支付成功fail也不等于一定失败。用户可能在收银台页面停留很久、可能支付完成后 App 被杀、可能网络抖动导致异步通知延迟。所以前端不能只依赖一次回调就更新 UI。我在项目里的通用做法是requestPayment的fail回调里如果错误码是用户取消比如cancel或-2直接提示“你取消了支付”。如果不是取消则进入“查单中”状态启动轮询。轮询接口返回“已支付”就跳转成功页返回“已关闭”或“支付失败”就提示重新支付超过 30 秒还没有最终状态就提示用户“支付结果确认中请稍后在订单列表查看”。轮询参数我习惯固定为首次查询在支付调用后 1 秒开始间隔 2 秒最多 10 次。如果 20 秒内没有结果前端不再无限轮询而是引导用户回到订单列表人工刷新。这个设计是从实际教训里来的——曾经做过一个支付页面渲染层一直在转圈轮询结果用户退出页面了请求还在发既占用资源也没实际意义。5.3 金额兜底逻辑多端支付里还有一个特别值得强调的点金额必须在后端每次重新确认前端传的金额只能作为展示参考。用户在 A 端下单时传了 100 元后端生成支付单时应该从数据库重新读取订单金额而不是直接信任前端传来的amount。否则抓包改参数后一笔 100 元的订单可能被改成 1 元完成支付。我在后端下单接口里会做两件事根据orderId重新查询订单金额用数据库金额作为支付单金额。在回调验签时再一次比对amount.total和本地订单金额。有这两道校验在即使前端被改了参数最终也会在回调环节被拦截不会出现“金额对不上还发发货”的事故。6. 联调排错和自我总结6.1 高频报错与排查路径写上几个我在群里被问烂、也亲自踩过的典型问题现象常见原因排查方向微信开发者工具点击支付立即成功真机不行开发者工具使用模拟支付真机调试确认真机和工具不是同一套环境requestPayment:fail -1参数错误、签名错误、商品信息缺失打印后端返回的完整参数对照微信官方文档逐项核对requestPayment:fail -2用户主动取消支付属于正常流程不要当成系统异常处理chooseWXPay is not a functionJSSDK 未正常注入或jsApiList没配chooseWXPay检查wx.config和wx.ready是否执行到config:fail invalid signatureJSSDK 签名 URL 不对去掉#后的部分重新生成签名支付宝 H5 支付后一直不回跳业务页同步返回 URL 配置错误检查支付宝开放平台的回调地址和 sync return url同一订单收到两次回调重复发货回调处理没有幂等用条件更新 唯一支付流水号兜底排查这类问题时我最推荐的办法是先把“请求链路日志”完整打出来。前端打印“我调用支付接口时发出了什么参数后端返回了什么参数”后端打印“回调内容、验签结果、金额校验结果、更新行数”。大多数支付问题都能在这一步定位到人。6.2 几个值得早点知道的开发习惯多端支付的项目开发到后期真正拼的不是写出支付功能而是出现故障时能多快定位问题。我给自己定的几条规矩长期看非常有效所有支付接口请求必须留痕。前端把请求参数、返回参数原样打印到控制台线上加日志不能只打印失败信息。联调时统一用小金额。真实支付测试金额设置为 0.01 元避免无意间造成大额扣款。环境开关独立。后端维护一个PAY_ENV配置沙箱和生产的密钥、回调地址彻底隔离。补单任务必须有。线上总会出现“用户付了钱但回调没到”的情况后端要提供“按业务订单号主动向支付平台查单”的接口通常是做一个定时任务扫描超时未支付的订单向上游主动查询最终状态。最后一个习惯尤其重要。异步通知不可能百分之百可靠微信、支付宝都提供了主动查单接口。没有补单任务就等于把线上资金安全寄托在第三方通知的稳定性上早晚会出账实不符。6.3 关于支付本质的一点体会做了几个项目的多端支付之后我最大的体会是支付这个功能UI 只是最表层稳定性的核心在订单状态机。前端调用uni.requestPayment只是整个流程里的一小步真正的收尾工作在后端回调、验签、幂等、补单这些看起来不起眼的环节。不要高估“一套代码多端运行”在支付场景里的神话程度。老老实实把每端的配置搞清楚、每个渠道的参数映射做明白、把订单结果确认链条画清楚比抄十个支付 demo 都有用。真机联调时准备一台 Android、一台 iOS、一个微信开发者工具把上面的流程从头到尾走几遍支付这个模块基本就能稳下来了。