uni-app 平台接入 · 微信支付配置说明

版本：V1.0
更新日期：2026-09-14
对应基础库：reglow 0.4.5（Python / Node.js / Java / Rust 四语言一致）
适用场景：用 uni-app（含 uni-app x / uvue）开发的应用接入微信支付，一个后端要同时服务小程序、微信内 H5、普通 H5、App、PC 扫码多端。
读者假设：没接触过微信支付，或接过一次但被 AppID / openid 绕晕过。
确定性说明：文中微信后台的菜单名、报错提示语与错误码会随微信改版而变化，实际以微信官方后台与官方文档为准；代码、接口与配置项部分对本仓库（reglow 0.4.5）是确定的。

写在前面：一个大白话故事

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│  微信支付就像一家大公司，进去办事要出示"工牌"：                   │
│                                                              │
│   ① 公众号工牌   → 在【微信里的网页】办事用它                    │
│   ② 小程序工牌   → 在【小程序】里办事用它                        │
│   ③ 移动应用工牌 → 在【自家 App】里办事用它                      │
│                                                              │
│  而"钱"这件事，公司另有规矩：                                   │
│                                                              │
│   商户号          = 你的收款账户（钱进哪儿）                     │
│   三张工牌都要先"挂靠"到这个收款账户，才允许收钱                   │
│                                                              │
│  最坑的一点：同一个人在三个窗口的"客户编号"（openid）不一样！      │
│  所以你不能拿公众号的编号去小程序窗口办事 → 会被驳回。             │
│                                                              │
└──────────────────────────────────────────────────────────────┘

一句话总结：

复杂的是微信的规则，不是我们的代码。 好消息是：Reglow 基础库已经把这些规则吸收掉了 —— 业务侧只需要说清楚「我现在跑在哪个端」，剩下的 AppID 选择、接口选择、openid 换取，全部由库里自动处理。

目录

1. 先搞懂：为什么会有这么多 AppID 和 openid
2. 五端配置矩阵与对照表
3. 微信 + 商户后台配置步骤（保姆级）
4. 常见报错排查清单
5. 联调验证：按这个顺序自测
6. 附录 A：本仓库代码与接口速查
7. 附录 B：十条铁律

一、先搞懂：为什么会有这么多 AppID 和 openid

1.1 三张工牌：三个互相独立的应用实体

微信生态里，公众号、小程序、移动应用是三个独立的应用，各自申请、各自审核、各自有一个 AppID。它们不是"同一个东西的三种形态"。

                    你的服务器（Reglow 后端）
                              │
              ┌───────────────┼───────────────┐
              │               │               │
         ① 小程序工牌     ② 公众号工牌     ③ 移动应用工牌
       wechat_mini_app_id  wechat_app_id   wechat_app_app_id
              │               │               │
              ▼               ▼               ▼
        小程序里支付     微信里打开H5支付    自家App里支付
      (JSAPI 接口)      (JSAPI 接口)      (APP 接口)

                    ↑ 三张工牌都必须先"挂靠"到 ↓
                          商户号 wechat_mch_id
                    （在【微信支付商户平台】完成关联）

不要试图只配一个 AppID 打通所有端。微信支付 V3 在下单时会校验 appid 与 payer.openid 的同源性，也会校验 AppID 是否已关联到该商户号；混用会被微信拒绝。

1.2 openid 是「用户 × 应用」的身份证

openid 不是用户的微信号，而是「某个微信用户，在某一个应用里的编号」。

同一个人的 openid：

所以两种 openid 的获取方式、以及能用在哪种下单接口上，是绑定死的：

为什么小程序不需要网页授权，而微信内 H5 需要？ 因为小程序内有 wx.login() 这个原生能力，可以直接拿到 code 交给后端换 openid；而浏览器页面没有这个能力，只能借道「网页授权」——先整页跳到微信、用户授权后带着 code 跳回来。这就是微信内 H5 比小程序「多一次跳转」的根本原因。

这正是「appid 和 openid 不匹配」这类报错的根本原因。 库内部已经按「端」自动挑对了 AppID（见第二章矩阵表），业务代码不需要手动传 AppID。

想要打通同一个用户？ 只有把公众号、小程序、移动应用都绑定到同一个微信开放平台账号下，才会多出一个跨应用共享的 unionid。但注意：

unionid 只解决「这是同一个人」，不解决「用哪个 AppID 下单」。下单仍然必须用对应端自己的 AppID。

1.3 商户号与证书：收钱的那一端

AppID 解决「谁在调用」，商户号解决「钱进哪里」。

1.4 那 11 个配置项，到底谁在用

后端的支付配置分组是 payment，在后台「运营 → 系统设置 → 支付设置」里维护。逐项的"用途 / 什么时候必须填"如下：

只做某几端时，未用到的项可以不填。 下表里的「基础四项」指 wechat_mch_id、wechat_serial_no、wechat_private_key（下单签名必需）、wechat_api_v3_key（回调验签解密必需）：

只做这个端	必须填	可以不填
PC 扫码（web）	基础四项 + 公众号 AppID	两个 AppSecret、wechat_app_app_id
微信小程序（miniapp）	基础四项 + wechat_mini_app_id + wechat_mini_app_secret	wechat_app_id / wechat_app_secret、wechat_app_app_id
微信内 H5（mpweb）	基础四项 + wechat_app_id + wechat_app_secret	wechat_mini_app_id / wechat_mini_app_secret、wechat_app_app_id
普通浏览器 H5（h5）	基础四项 + wechat_app_id	两个 AppSecret、wechat_app_app_id
App（app）	基础四项 + wechat_app_app_id	wechat_app_id、两个 AppSecret

• wechat_notify_url 强烈建议填：不填微信无法回调，支付结果只能靠前端轮询兜底，线上会延迟入账甚至漏入账。
• wechat_enabled 要在后台打开（渠道开关）。
• 多个端都要做时，取各端并集即可。

关于兜底：库对 miniapp 有「小程序 AppID 未配则回退公众号 AppID」的逻辑，对 web 扫码也有「公众号 AppID 未配则回退小程序 AppID」的逻辑。两处兜底互相独立，都只是防止初始化直接报错；一旦回退后 openid 与 AppID 不同源，微信会拒绝下单。所以生产环境请把用到的 AppID 全部配齐 —— 小程序端一定要填小程序 AppID 与 AppSecret。

1.5 名词速查（看不懂就回来查）

二、五端配置矩阵与对照表

2.1 一张表看懂五端差异

业务侧只需要告诉后端「我现在跑在哪个端」——这个值就是 platform。AppID 由库按 platform 自动选，前端不许也不需要传 AppID。

三个必须知道的"反常点"：

1. 小程序和公众号用的是同一个微信接口（/v3/pay/transactions/jsapi），区别只在 appid 与 openid 的来源必须配对。
2. 微信内置浏览器里不能用 H5 支付（platform=h5）。微信会拦截，提示「请到微信外打开」。微信内必须走 mpweb。
3. App 支付不需要 openid，这是五端里最简单的一环。

2.2 前端怎么判定当前端

项目已封装好，不要在页面里自己写判断。见 common/utils/pay.uts：

import { resolvePayPlatform } from "../../common/utils/pay.uts"

const platform = resolvePayPlatform()
// 小程序 → "miniapp"
// App    → "app"
// H5（微信内）  → "mpweb"
// H5（普通浏览器）→ "h5"
// PC / 桌面浏览器 → "web"

判定规则：编译期按平台裁剪（MP-WEIXIN / APP-ANDROID / APP-IOS / WEB），H5 端再用 UA 判断是否微信内置浏览器（UA 含 MicroMessenger）。

2.3 前端标准调用流程

五端流程统一为三步，差异全部被工具函数吃掉了：

import {
  resolvePayPlatform, preparePayOpenid, needPayOpenid,
  invokeWechatPay, startPayPolling, stopPayPolling,
  savePendingPay, takePendingPay, PAY_WEB, PAY_H5
} from "../../common/utils/pay.uts"

const platform = resolvePayPlatform()

// ① 准备 openid（小程序走 wx.login；微信内 H5 走公众号网页授权；其它端返回空串）
preparePayOpenid(platform).then((openid : string) => {
  if (needPayOpenid(platform) && openid == "") {
    // 微信内 H5：首次会整页跳转公众号授权，回跳后再发起即可
    return
  }
  // ② 下单（后端接口：把 platform + openid 交给服务端，AppID 由服务端决定）
  //    payOrder(订单id, method, provider, platform, openid)
  //    method：支付方式，"wechat"（人民币）/ "points"（积分抵扣）
  //    provider：支付渠道，这里固定 "wechat"
  return payOrder(orderId, "wechat", "wechat", platform, openid)
}).then((data) => {
  // ③ 调起支付（五端差异在此收敛）
  if (platform == PAY_WEB) {
    // 渲染 data.qr_code 二维码 + startPayPolling(...) 轮询
    startPayPolling(data.payment_order_id, onPaid, onClosed)
  } else if (platform == PAY_H5) {
    savePendingPay(data.payment_order_id, orderId, orderNo) // 落盘，回跳后恢复
    invokeWechatPay(platform, data.pay_params)               // 跳转 h5_url
  } else {
    invokeWechatPay(platform, data.pay_params).then(onPaid)  // 小程序 / mpweb / App
  }
})

invokeWechatPay 内部对各端的处理：

微信内 H5 首次支付需要点两次：第一次点击会跳转到微信授权页换取 openid，回跳后 openid 已缓存，再点一次即正常拉起支付。 授权在同一浏览器、且本地缓存未被清除的前提下只会发生一次（openid 存在本地 Key K_WX_OPENID）；换设备、换浏览器或清缓存后会重新授权一次。

2.4 后端接口清单

三、微信 + 商户后台配置步骤（保姆级）

所有后台菜单名以微信官方后台实际显示为准（微信会改版）。下面给的是大致路径 + 你要得到什么。 建议按 3.6 的推荐顺序操作，能显著减少来回返工。

3.1 商户平台（微信支付）——先把"收钱的地方"建好

打开 pay.weixin.qq.com，用商户号登录。

第 5 步是「appid 和 mch_id 不匹配」最直接的解法：AppID 没关联商户号，下单会失败。 第 3 步的私钥与序列号必须成对：序列号对不上私钥，会报签名错误。

3.2 公众号（负责"微信内 H5"）

打开 mp.weixin.qq.com，用公众号管理员登录。

第 2 步是「redirect_uri 域名与后台配置不一致（10003）」最直接的解法。 注意：网页授权域名只填域名，不带路径、不带端口，且必须是已备案的 HTTPS 域名。

3.3 小程序（负责"小程序内支付"）

打开小程序后台（mp.weixin.qq.com，切换到小程序）。

小程序 AppSecret 只在服务端使用（换 openid、换 access_token），绝不能写进前端代码。 manifest.json 里的 mp-weixin.appid 只需填 AppID（不是 AppSecret）。

3.4 开放平台·移动应用（负责"App 内支付"）

打开 open.weixin.qq.com，用开放平台账号登录。

包名/签名填错是 App 支付的常见失败原因，且报错信息往往很含糊。务必用正式打包的 APK 取签名。 iOS 还需在 manifest.json 里配置微信支付的 appid 与 Universal Links。

3.5 配置核对清单（可勾选）

商户平台

• 商户号已复制到 wechat_mch_id
• APIv3 密钥已设置并填入 wechat_api_v3_key
• 证书已下载，序列号填入 wechat_serial_no，私钥内容填入 wechat_private_key
• 已开通所需支付产品（JSAPI / H5 / Native / APP）
• 公众号 / 小程序 / 移动应用 AppID 已逐一关联到本商户号
• JSAPI 支付授权目录已配置（微信内 H5 用）
• H5 支付域名已配置（普通浏览器 H5 用，域名需备案）

公众号

• wechat_app_id / wechat_app_secret 已填
• 网页授权域名已配置（H5 站点域名）
• 公众号为服务号且已认证

小程序

• wechat_mini_app_id / wechat_mini_app_secret 已填
• request / downloadFile 合法域名已配置
• manifest.json 中小程序 appid 已填

移动应用

• wechat_app_app_id 已填
• Android 包名 + 签名 / iOS Bundle ID + Universal Links 已填

服务器

• wechat_notify_url 为公网可访问的 HTTPS 地址
• H5 站点为 HTTPS + 已备案域名
• 反向代理已正确透传 X-Forwarded-For（H5 支付要用真实客户端 IP）
• 后端已重启，加载最新库版本

3.6 推荐的配置顺序

① 商户平台：拿商户号 + 设置 APIv3 密钥 + 下载证书
        ↓
② 公众号 / 小程序 / 开放平台：拿到三个 AppID 与两个 AppSecret
        ↓
③ 商户平台：把三个 AppID 关联到商户号 + 开通支付产品
        ↓
④ 商户平台：配置 JSAPI 支付授权目录 + H5 支付域名
        ↓
⑤ 公众号后台：配置网页授权域名（放校验文件）
        ↓
⑥ 小程序后台：配置 request / downloadFile 合法域名
        ↓
⑦ 后台「支付设置」：把**本端用得到的项**一次填完并保存（对照 1.4 的按端最小配置表）
        ↓
⑧ 重启后端 → 按第五章顺序联调

顺序反了会怎样：先配前端、后关联 AppID，你会一直以为是代码问题，其实是商户号没关联。

四、常见报错排查清单

4.1 下单阶段

4.2 调起阶段

4.3 回调与到账阶段

4.4 小程序码 / access_token

五、联调验证：按这个顺序自测

按「从简单到复杂」的顺序，每步都能独立验证，避免多端问题混在一起排查。

第 1 步不通，先别测其它端。扫码链路最短，建议先用它暴露商户号、证书、回调地址这类配置问题。

本地开发时，微信服务器无法回调 localhost：请用内网穿透把本地端口暴露成公网 HTTPS，再把 wechat_notify_url 指向它。

附录 A：本仓库代码与接口速查

A.1 前端（uni-app / uvue）

common/utils/pay.uts 对外导出：

A.2 后端（Reglow 基础库）

Node.js / Java / Rust 版库提供了同名同语义的能力，接口路径与 platform 取值完全一致，四语言可互换。

附录 B：十条铁律

1. 三张工牌各管一摊，不要试图用一个 AppID 打通所有端。
2. openid 与 AppID 必须同源，且三张工牌都要先在商户平台关联。
3. AppID 与 AppSecret 只在服务端使用，AppSecret 绝不进前端代码。
4. AppID 不需要前端传，前端只传 platform，选哪个 AppID 是后端的事。
5. 微信内浏览器只能用 JSAPI（mpweb），H5 支付（h5）只在微信外的浏览器可用。
6. 金额单位是分，且金额一律由后端计算。
7. 回调地址必须公网 HTTPS，本地开发用内网穿透。
8. access_token 全库单点缓存，业务代码不要自己获取。
9. 先配商务后台，再配代码；很多"代码问题"其实是 AppID 没关联。
10. 按 PC 扫码 → 小程序 → App → 微信内 H5 → 普通 H5 的顺序联调，一次只排查一个变量。