# 微信公众号 / 小程序 / 微信支付 开发全流程教程

> 版本：2026-11 整理版
> 适用场景：LikeShop 类商城系统（服务号 H5 + 小程序 + 微信支付），ThinKPHP / Nginx / 阿里云 ESA / 1Panel 部署环境
> 用途：术语速查 + 数据流理解 + 配置落位 + 报错排查。开发时对照使用。

---

## 目录

1. [先分清五大平台](#一先分清五大平台)
2. [核心术语总表](#二核心术语总表)
3. [公众号（服务号）体系](#三公众号服务号体系)
4. [小程序体系](#四小程序体系)
5. [微信开放平台 / UnionID 体系](#五微信开放平台--unionid-体系)
6. [微信支付体系（重点）](#六微信支付体系重点)
7. [完整数据流总览](#七完整数据流总览)
8. [配置落位对照表](#八配置落位对照表)
9. [LikeShop 对接标准流程](#九likeshop-对接标准流程)
10. [错误码速查表](#十错误码速查表)
11. [避坑总纲](#十一避坑总纲)
12. [附录：常用接口清单](#十二附录常用接口清单)

---

## 一、先分清五大平台

很多混乱来自"后台入口搞不清"。微信生态实际是 **5 个互相独立的平台**，各有账号体系、各有 AppID/密钥、互不替代。

| # | 平台 | 域名 | 干什么 | 你在这里配什么 |
|---|------|------|--------|----------------|
| 1 | 微信公众平台（公众号） | mp.weixin.qq.com | 服务号/订阅号后台 | 网页授权域名、JS 安全域名、消息推送、AppSecret、IP 白名单 |
| 2 | 微信公众平台（小程序） | mp.weixin.qq.com | 小程序后台（独立账号） | request/upload/download/socket 域名、业务域名、订阅消息 |
| 3 | 微信开放平台 | open.weixin.qq.com | 跨应用身份打通 | 网站应用扫码登录、APP 登录、绑定公众号+小程序拿 UnionID |
| 4 | 微信支付商户平台 | pay.weixin.qq.com | 收款方后台 | 商户号、APIv3 密钥、支付证书、回调地址、交易/退款/对账 |
| 5 | 微信开发者中心 | developers.weixin.qq.com | 文档 + 监控 + 开发工具 | 只查资料、看接口日志，**不做业务配置** |

### 一句话记忆口诀

- **mp = 账号自家后台**（公众号、小程序分开登录，AppID 各自独立）
- **open = 打通用户身份**（UnionID、网站/APP 登录）
- **pay = 收钱的地方**（商户号、密钥、证书、回调）
- **developers = 查文档排错**

### 最容易踩的三个入口误区

1. ❌ 去 open.weixin.qq.com 找"网页授权回调域名""消息推送 URL" —— **这里没有**。
2. ❌ 以为公众号和小程序用户天然互通 —— **不互通**，必须开放平台绑定才能拿 UnionID。
3. ❌ 以为 pay 商户平台能改公众号配置 —— **完全独立**，商户号和公众号 AppID 是两套东西（只是可以互相关联绑定）。

---

## 二、核心术语总表

| 术语 | 归属 | 含义 | 有效期/限制 |
|------|------|------|-------------|
| AppID | mp / open | 应用唯一标识（公众号、小程序、开放平台各自一个） | 永久 |
| AppSecret | mp / open | 应用密钥，换取 access_token 用 | 永久，**务必保密、只存后端** |
| openid | 公众号 / 小程序 | 用户在**单个应用内**的唯一 ID | 永久，但换应用就变 |
| unionid | open | 同一主体下，用户跨公众号/小程序/APP **唯一不变** ID | 永久，需绑定开放平台 |
| code | 各处 | 临时授权票据 | **5 分钟、一次性** |
| access_token（基础） | 公众号 mp | 调公众号后台接口的全局凭证 | 2 小时，需缓存 + IP 白名单 |
| access_token（网页授权） | 公众号 OAuth | 拉取用户信息专用 | 2 小时，**与基础 token 不通用** |
| session_key | 小程序 | 解密手机号等敏感数据的会话密钥 | 随登录刷新 |
| jsapi_ticket | 公众号 mp | JS-SDK 签名票据 | 2 小时，需缓存 |
| prepay_id | pay | 统一下单返回的预支付订单号 | 2 小时 |
| mch_id | pay | 商户号 | 永久 |
| signature | 各处 | 请求签名，防伪造 | 单次 |
| echostr | 公众号 mp | 消息推送验证阶段的回显字符串 | 单次 |

---

## 三、公众号（服务号）体系

> 服务号才具备：网页授权、JS-SDK、消息推送、微信支付、模板/订阅消息。订阅号基本没有网页授权能力。

### 3.1 网页授权 OAuth2.0（拿 openid，实现微信登录）

#### 关键配置

**公众号后台 → 设置与开发 → 公众号设置 → 功能设置 → 网页授权域名**

- 只填裸域名：`xnb.me`
- **不带 `https://`、不带路径、不带端口、不支持泛域名 `*.xnb.me`**
- 需要上传微信提供的 `MP_verify_xxx.txt` 校验文件到网站根目录

#### 关键参数

| 参数 | 说明 |
|------|------|
| `appid` | 公众号 AppID |
| `redirect_uri` | 授权后跳回的地址，**必须 URL 编码**，域名必须在白名单内 |
| `response_type` | 固定 `code` |
| `scope` | `snsapi_base`（静默，只拿 openid）/ `snsapi_userinfo`（弹窗，可拿昵称头像） |
| `state` | 自定义参数（防 CSRF、带业务标识），回调会原样带回 |
| `code` | 回调带回的票据，换 token 用 |
| `#wechat_redirect` | 链接末尾必须带上，否则部分场景不跳转 |

#### 数据流（逐步）

```
1. 用户在微信内置浏览器打开：https://xnb.me/login

2. 后端拼接授权链接（返回 302 给浏览器）：
   https://open.weixin.qq.com/connect/oauth2/authorize
     ?appid=wx123456
     &redirect_uri=https%3A%2F%2Fxnb.me%2Fapi%2Fwechat%2Fcallback
     &response_type=code
     &scope=snsapi_base
     &state=abc123
     #wechat_redirect

3. 浏览器跳到微信服务器 open.weixin.qq.com

4. 微信校验阶段（★ 关键）：
   - 解析 redirect_uri → 提取域名 xnb.me
   - 对比后台【网页授权域名】白名单
   - 不一致 → 直接报 10003，页面显示"redirect_uri 域名与后台配置不一致"
   - 此阶段微信还没有访问你的服务器，不是网络问题！

5. 校验通过：
   - snsapi_base：不弹窗，直接 302 回 redirect_uri?code=xxx&state=abc123
   - snsapi_userinfo：弹授权框 → 用户同意 → 302 回 redirect_uri?code=xxx&state=abc123

6. 后端收到 code，服务器侧（不是浏览器）请求：
   GET https://api.weixin.qq.com/sns/oauth2/access_token
       ?appid=xx&secret=xx&code=xx&grant_type=authorization_code

   返回：{ access_token, expires_in, refresh_token, openid, scope, unionid? }

7. 若 scope=snsapi_userinfo，再请求：
   GET https://api.weixin.qq.com/sns/userinfo?access_token=xx&openid=xx&lang=zh_CN

8. 后端用 openid / unionid 建立商城会员会话
```

#### 常见坑

- `redirect_uri` 里协议必须是 `https`，ESA 回源协议错 → 后端拼出 `http://` → 10003
- 回调地址末尾斜杠、大小写、`www` 有无，**微信是完整字符串比对**
- code 只能用一次，刷新页面就失效，必须重新走授权

### 3.2 JS-SDK（调用微信原生能力）

#### 关键配置

**公众号后台 → 设置与开发 → 公众号设置 → 功能设置 → JS 接口安全域名**

- 与网页授权域名是**两条独立配置**，域名相同也要分别填两次
- 同样需要 `MP_verify_xxx.txt` 校验

#### 能力清单

| 接口 | 用途 |
|------|------|
| `wx.chooseImage` / `wx.chooseMedia` | 拍照、选图 |
| `wx.getLocation` / `wx.openLocation` | 定位、看地图 |
| `wx.scanQRCode` | 扫一扫 |
| `wx.updateAppMessageShareData` | 分享给好友 |
| `wx.updateTimelineShareData` | 分享到朋友圈 |
| `wx.chooseWXPay` | 拉起 JSAPI 支付 |
| `wx.startRecord` | 录音 |

#### 数据流

```
1. H5 页面加载完成，前端请求后端 /api/jssdk/config?url=当前页面url（不含#后内容）

2. 后端流程：
   a. 取缓存的基础 access_token（https://api.weixin.qq.com/cgi-bin/token）
   b. 用它换 jsapi_ticket（https://api.weixin.qq.com/cgi-bin/ticket/getticket?type=jsapi）
      → ticket 有效期 2 小时，必须缓存，全站共用
   c. 拼签名串：
      jsapi_ticket=xxx&noncestr=随机串&timestamp=时间戳&url=当前页面完整url
   d. sha1(签名串) → signature

3. 后端返回 { appId, timestamp, nonceStr, signature }

4. 前端执行：
   wx.config({ debug:false, appId, timestamp, nonceStr, signature,
               jsApiList:['chooseImage','updateAppMessageShareData',...] })

5. wx.ready 后即可调用各 wx.xxx 接口

6. wx.error 里能看到具体失败原因
```

#### 常见坑

- `invalid signature`：url 用了 SPA 路由后的地址、或 url 编码方式不对、或缓存了旧 ticket
- `url` 必须是**当前页面完整地址（不含 #hash 部分）**，前端传给后端时要做 encodeURIComponent
- 域名不在 JS 安全域名里 → config 直接失败
- iOS 与 Android 对 url 的处理有差异，前端应强制传 `location.href.split('#')[0]`

### 3.3 消息推送（接收用户消息与事件）

#### 关键配置

**公众号后台 → 设置与开发 → 基本配置 → 服务器配置**

| 字段 | 说明 |
|------|------|
| URL | 你的后端接口，如 `https://www.xnb.me/api/wechat/server` |
| Token | 自定义字符串，用于签名 |
| EncodingAESKey | 加密密钥（43 位） |
| 消息加解密方式 | 明文 / 兼容 / **安全（推荐）** |

#### 数据流（验证 + 收消息）

```
【验证阶段，只在保存配置时发生一次】
1. 点"提交"，微信服务器向你填的 URL 发 GET 请求：
   /api/wechat/server?signature=xxx&timestamp=xxx&nonce=xxx&echostr=abc

2. 后端算签名：sha1(sort([token, timestamp, nonce]).join(''))
   与 signature 比对

3. 一致 → 原样输出 echostr 字符串，HTTP 200
   ❗ 微信服务器不跟随 301/302！
   如果该 URL 被 Nginx/ESA 重定向，验证直接失败

【收消息阶段，持续发生】
4. 用户发消息 / 关注 / 扫码 / 点菜单 / 支付完成事件
5. 微信服务器 POST 到你的 URL（XML 或 JSON，看配置）
6. 后端验签 → 解析消息体 → 处理业务（自动回复、记 openid、发券）
7. 5 秒内返回响应 XML；超时微信会重试（共 3 次，容易重复处理）
```

#### 常见坑

- **推送 URL 允许被 301 跳转** → 必失败（你之前踩过：填 www 正常、填裸域失败，就是这个原因）
- 端口只支持 80/443，不支持自定义端口
- 明文模式最容易调试，但生产建议安全模式
- 微信重试机制必须有幂等处理，否则重复发券/重复加积分

### 3.4 公众号基础 access_token

- 接口：`GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=&secret=`
- 有效期 **7200 秒**
- **必须后台缓存**（Redis / 文件），全站共用一份
- 需要 **IP 白名单**：mp 后台 → 基本配置 → IP 白名单（填你服务器出口 IP）
- 与网页授权 access_token **完全独立、不可混用**
- 频繁刷新会导致旧 token 失效，建议提前 5 分钟刷新

### 3.5 模板消息 / 订阅通知

- 服务号：模板消息（用户关注即可发，2020 年后受限较多）
- 统一趋势：改用**订阅通知**（用户需主动点"允许"）
- 用途：订单支付成功提醒、发货提醒、预约提醒
- 依赖基础 access_token

---

## 四、小程序体系

> 小程序**没有网页授权 OAuth**，登录是一套独立体系。

### 4.1 小程序登录（wx.login）

#### 数据流

```
1. 前端 wx.login() → 拿到 code（5 分钟有效、一次性）

2. 前端把 code 传给后端

3. 后端请求：
   GET https://api.weixin.qq.com/sns/jscode2session
       ?appid=xx&secret=xx&js_code=xx&grant_type=authorization_code

   返回：{ openid, session_key, unionid? }

4. 后端生成自己的登录态（token/session），返回前端

5. 前端后续请求带自己的 token（★ 不要直接把 session_key 给前端保存太久）
```

#### 与公众号 OAuth 的区别

| | 公众号 OAuth | 小程序 wx.login |
|---|---|---|
| 触发 | 用户点开 H5 | 小程序启动调用 |
| code 接口 | `/sns/oauth2/access_token` | `/sns/jscode2session` |
| 返回 | access_token + openid | openid + session_key |
| 是否会弹窗 | snsapi_userinfo 会 | 不会 |

### 4.2 小程序四类域名（极易混淆）

**小程序后台 → 开发 → 开发管理 → 开发设置 → 服务器域名**

| 类型 | 作用 | 典型报错 |
|------|------|----------|
| **request 合法域名** | 前端 `wx.request` 调后端接口（查商品、下单） | `request:fail url not in domain list` |
| **uploadFile 合法域名** | `wx.uploadFile` 上传图片/文件 | 同上 |
| **downloadFile 合法域名** | `wx.downloadFile` 下载 | 同上 |
| **socket 合法域名** | WebSocket 长连接 | 同上 |

要求：**必须 HTTPS、必须备案、不能带端口、不能是 IP、每月修改次数有限**

### 4.3 业务域名（web-view 专用）

**小程序后台 → 开发 → 开发管理 → 开发设置 → 业务域名**

- 作用：`<web-view src="https://xnb.me/xxx">` 内嵌 H5 页面，该域名必须在业务域名列表
- 需要把微信给的校验文件放到该域名**根目录**
- 报错：页面提示"不支持打开该域名"

#### 一句话区分

- **request 域名** = 小程序自己的 JS 调接口
- **业务域名** = web-view 里加载的外部网页

> 你 LikeShop 小程序里用 web-view 打开 H5 商城 → `xnb.me` 必须加到业务域名；同时小程序自己的接口调用走 request 域名。

### 4.4 小程序订阅消息

- 替代旧的模板消息
- 用户必须**主动点击授权**（一次订阅一次推送 / 长期订阅）
- 后端接口：`POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send`
- 需要小程序 access_token（`/cgi-bin/token`，与公众号的是不同的）

### 4.5 获取手机号

- 前端 `<button open-type="getPhoneNumber">` → 拿到加密数据 + code
- 新版：直接用 code 调 `POST https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token=xx`
- 属于**付费能力**（每次调用计费，按量收费）

---

## 五、微信开放平台 / UnionID 体系

### 5.1 为什么需要

默认情况下：

- 用户在你的**服务号**里 openid = `oA_xxxxx`
- 同一用户在**小程序**里 openid = `oB_yyyyy`

两个 ID 完全不相干 → 商城会认成两个会员 → 账号不互通、积分不共享、订单分裂。

**把公众号 + 小程序绑定到同一个开放平台账号下**，两者的返回里都会带上**同一个 unionid**，用它做会员主键即可打通。

### 5.2 绑定前置条件

1. 注册开放平台账号（open.weixin.qq.com），完成**开发者资质认证**（300 元/年）
2. 公众号、小程序、APP、网站应用**主体必须一致**（同一营业执照）
3. 在开放平台 → 管理中心 → 公众账号 / 小程序 里逐个绑定（需管理员扫码确认）

### 5.3 UnionID 获取路径

| 场景 | 是否返回 unionid |
|------|------------------|
| 公众号 OAuth（snsapi_base / userinfo） | 绑定后返回 |
| 小程序 jscode2session | 绑定后返回 |
| 未绑定开放平台 | **不返回** |

### 5.4 数据流

```
用户A 在服务号 H5 登录  → openid_A + unionid_U
用户A 在小程序登录      → openid_B + unionid_U
                    ↓
LikeShop 会员表：以 unionid_U 作为唯一键
                    ↓
两种入口登录 → 落到同一个会员账户（积分、订单、优惠券共享）
```

### 5.5 开放平台另外两个用途

- **网站应用**：PC 官网"微信扫码登录"（`https://open.weixin.qq.com/connect/qrconnect`）
- **移动应用**：APP 微信登录、微信分享（需应用签名、包名报备）

> 注意：开放平台的 AppID/AppSecret 和公众号、小程序的**互不通用**。

---

## 六、微信支付体系（重点）

> 微信支付是**完全独立的第 4 个平台**（pay.weixin.qq.com），跟公众号/小程序只是"关联"关系。

### 6.1 平台与账号关系

| 概念 | 说明 |
|------|------|
| **商户号 mch_id** | 收款主体，可在 pay.weixin.qq.com 申请，需营业执照 |
| **AppID 关联** | 商户号需在【产品中心 → AppID 账号管理】里关联你的公众号/小程序 AppID，否则下单报错 |
| **APIv2 密钥** | 32 位，MD5/HMAC-SHA256 签名用（老接口） |
| **APIv3 密钥** | 32 位，AES-256-GCM 加解密 + 新版签名（**推荐全部用 V3**） |
| **商户 API 证书** | `apiclient_cert.pem` + `apiclient_key.pem`，V3 签名必需 |
| **平台证书 / 微信支付公钥** | 用于**验签**回调与响应（2023 后新商户改用"微信支付公钥"） |
| **支付回调 URL** | 微信服务器异步 POST 支付结果，**不能是 301 跳转地址** |
| **退款回调 URL** | 退款结果异步通知 |

### 6.2 支付产品类型速查（选错就白干）

| 产品 | 使用场景 | 调起方式 | 必备条件 |
|------|----------|----------|----------|
| **JSAPI 支付** | 微信内 H5（公众号） | `wx.chooseWXPay` | 公众号 AppID + JS 安全域名 + 商户号关联 + 用户 openid |
| **小程序支付** | 小程序内 | `wx.requestPayment` | 小程序 AppID + 用户 openid（小程序 openid） |
| **H5 支付（MWEB）** | 微信**外**的浏览器（手机浏览器、App 内） | 跳转中间页 | 单独开通 MWEB，需场景域名 |
| **Native 支付** | PC 网站显示二维码 | 扫码 | 开通 Native |
| **APP 支付** | 原生 App | SDK 调起 | 开放平台移动应用 + 应用签名 |
| **付款码支付** | 线下收银扫用户付款码 | 商户扫 | 开通刷卡支付 |
| **刷脸支付** | 线下设备 | 设备 SDK | 专用设备 |

> ⚠️ 最常见的错：**在微信内置浏览器里用 H5(MWEB) 支付** —— 微信内不支持 MWEB，必须用 JSAPI。反之在外部浏览器用 JSAPI 也不行。

### 6.3 JSAPI 支付完整数据流（公众号 H5，你最常用）

```
【前置】
- 商户号已关联公众号 AppID
- 已配置支付授权目录（若用旧版 V2；V3 不再强依赖，但建议配）
- 公众号已配置 JS 安全域名
- 用户已通过 OAuth 拿到 openid（★ 必须是该公众号 AppID 下的 openid）

【下单】
1. 前端点"立即支付" → 请求后端 /api/pay/create，带订单号、金额、openid

2. 后端组装请求，调 V3 统一下单：
   POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi
   Header: Authorization: WECHATPAY2-SHA256-RSA2048 mchid="..",nonce_str="..",
           signature="..",timestamp="..",serial_no=".."
   Body:
   {
     "appid": "公众号AppID",
     "mchid": "商户号",
     "description": "商品描述",
     "out_trade_no": "商城订单号（唯一）",
     "notify_url": "https://xnb.me/api/pay/notify",   ← 支付回调
     "amount": { "total": 100, "currency": "CNY" },   ← 单位：分
     "payer": { "openid": "用户openid" }
   }

   签名算法：SHA256-RSA2048，用商户私钥 apiclient_key.pem 签
   待签串：HTTP方法\nURL路径\n时间戳\n随机串\n请求体\n（每行末尾 \n）

3. 微信返回：{ "prepay_id": "wx3017xxxxxxxx" }

【二次签名（给前端调起用）】
4. 后端用 prepay_id 生成调起参数并签名：
   {
     "appId": "公众号AppID",
     "timeStamp": "时间戳字符串",
     "nonceStr": "随机串",
     "package": "prepay_id=wx3017xxxxxxxx",
     "signType": "RSA",
     "paySign": "用商户私钥对 appId\ntimeStamp\nnonceStr\npackage\n 签名"
   }

5. 前端：
   wx.chooseWXPay({ timeStamp, nonceStr, package, signType:'RSA', paySign,
     success(){ 跳支付成功页 },
     cancel(){ 用户取消 },
     fail(){ 报错 }
   })

【支付结果】
6. 用户输密码付款成功
7. 微信服务器异步 POST 到你 notify_url（★ 不跟随 301！）
   Body（V3 是 JSON，且加密）：
   {
     "id":"EV-xxx", "event_type":"TRANSACTION.SUCCESS",
     "resource": { "algorithm":"AEAD_AES_256_GCM",
                   "ciphertext":"...", "nonce":"...", "associated_data":"..." }
   }

8. 后端处理：
   a. 验签（用微信支付公钥/平台证书验 Wechatpay-Signature 头）
   b. 用 APIv3 密钥 AES-256-GCM 解密 resource.ciphertext → 明文交易对象
   c. 校验 out_trade_no、amount.total、trade_state=SUCCESS
   d. 幂等处理：同一笔订单重复通知只处理一次
   e. 更新订单状态、发货/发券/加积分
   f. 返回 HTTP 200 + {"code":"SUCCESS"}（或空 200/204）

9. 前端 success 回调只是"用户端感知"，**真正以回调通知为准**！
```

### 6.4 小程序支付数据流

与 JSAPI 几乎一致，差异只有三处：

| 环节 | JSAPI（公众号） | 小程序 |
|------|-----------------|--------|
| appid 传值 | 公众号 AppID | 小程序 AppID |
| payer.openid | 公众号 openid | 小程序 openid |
| 前端调起 | `wx.chooseWXPay` | `wx.requestPayment` |

`wx.requestPayment` 参数完全一致（timeStamp / nonceStr / package / signType / paySign）。

### 6.5 H5（MWEB）支付数据流

```
1. 后端下单（V3 H5 接口）：
   POST https://api.mch.weixin.qq.com/v3/pay/transactions/h5
   Body 增加：
   "scene_info": {
     "payer_client_ip": "用户真实IP",
     "h5_info": { "type": "Wap" }
   }

2. 返回 { "h5_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=..." }

3. 前端 location.href = h5_url
4. 用户在微信中间页付款
5. 回调同 JSAPI
```

**关键要求**

- 必须传**用户真实公网 IP**（在 ESA/CDN 后面必须从 `X-Forwarded-For` 里取第一个）
- 必须单独开通 MWEB 产品
- 必须在商户平台配置**H5 支付域名**（场景域名）
- 微信内置浏览器打开会失败 → 要判断 UA，微信内改走 JSAPI

### 6.6 回调验签（V3）关键细节

```
请求头：
  Wechatpay-Timestamp: 时间戳
  Wechatpay-Nonce: 随机串
  Wechatpay-Signature: 签名（base64）
  Wechatpay-Serial: 平台证书序列号 或 微信支付公钥ID

验签串：
  timestamp\nnonce\nbody\n   （每行末尾 \n，最后一行也要 \n）
用微信支付公钥（或对应平台证书公钥）做 SHA256-RSA 验签

★ 必须校验 timestamp 与当前时间差 < 5 分钟，防重放
```

### 6.7 支付回调的 Nginx / ESA 必配

因为微信服务器**不跟随 301/302**，回调路径必须直连：

```nginx
# 支付回调、微信消息推送，禁止域名跳转，直接透传
location ~ ^/api/(pay/notify|refund/notify|wechat/server) {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_read_timeout 10s;
}
```

同时在 ESA 上给这三个路径加**豁免重定向规则**，否则 ESA 直接返回 301。

### 6.8 退款流程

```
1. 后端调：
   POST https://api.mch.weixin.qq.com/v3/refund/domestic/refunds
   Body:
   {
     "out_trade_no": "原订单号",         // 或 transaction_id
     "out_refund_no": "退款单号（唯一）",
     "reason": "用户申请退款",
     "notify_url": "https://xnb.me/api/refund/notify",
     "amount": { "refund": 100, "total": 100, "currency": "CNY" }
   }

2. 同步返回 status=PENDING（处理中）
3. 异步通知：REFUND.SUCCESS / REFUND.ABNORMAL / REFUND.CLOSED
4. 收到 SUCCESS 后更新订单为已退款、回滚库存/积分
```

### 6.9 订单查询 / 关闭

| 功能 | V3 接口 |
|------|---------|
| 查单 | `GET /v3/pay/transactions/out-trade-no/{out_trade_no}?mchid=` |
| 关单 | `POST /v3/pay/transactions/out-trade-no/{out_trade_no}/close` |
| 对账单 | `GET /v3/bill/tradebill?bill_date=&bill_type=` → 返回下载链接 |

**典型用途**：前端 success 但回调丢了 → 后端主动查单兜底（**生产必备**）。

### 6.10 支付避坑清单

1. **金额单位是「分」**，1 元 = 100，不要传 1.00
2. `out_trade_no` 必须唯一，重复下单要幂等
3. `notify_url` 必须 **HTTPS 公网可访问、不能带参数、不能是 301**
4. 回调必须**验签 + 解密 + 校验金额**，否则可被伪造
5. **以回调为准，不以客户端 success 为准**
6. 回调要**幂等**，微信会重试最多 8 次（间隔递增）
7. 必须做**主动查单兜底**，回调丢失时不至于掉单
8. ESA / CDN 后面取客户端 IP 要用 `X-Forwarded-For` 第一段
9. 商户号必须**关联 AppID**，否则报 `APPID_MCHID_NOT_MATCH`
10. V3 签名串最后一行必须带 `\n`，少一个换行就验签失败（超高频坑）
11. 平台证书 / 微信支付公钥要**定期更新**，缓存过期会验签失败
12. 不要用 APIv2 的 MD5 签名去调 V3 接口

---

## 七、完整数据流总览

### 7.1 三层身份链路

```
【第一层：拿身份】
公众号 H5：OAuth → code → openid / unionid
小程序：wx.login → code → openid / unionid

【第二层：统一会员】
open.weixin.qq.com 绑定 → unionid 作为会员主键
LikeShop 会员表(unionid) → 一个用户一个账号

【第三层：交易】
会员下单 → 订单号 out_trade_no
      → 支付下单（appid + mchid + openid）→ prepay_id
      → 前端调起 → 用户付款
      → 微信异步回调 notify_url → 验签解密 → 更新订单
      → （兜底）主动查单
```

### 7.2 谁主动发起请求？——决定能不能 301

| 请求方 | 场景 | 是否跟随 301/302 |
|--------|------|------------------|
| **用户浏览器** | OAuth 授权跳转、H5 支付跳转 | ✅ 会跟随 |
| **微信服务器** | 消息推送验证、消息推送、**支付回调、退款回调** | ❌ **不跟随，遇跳转即失败** |

> 这是你之前"填 www 正常、填裸域失败"以及所有回调类故障的**总根源**。

### 7.3 ESA / CDN 代理下的头透传（必配）

```
用户 → ESA(HTTPS) → 源站 Nginx(HTTP回源) → PHP

必须保证：
1. ESA 回源协议 = follow（跟随客户端）
2. ESA 回源 Host = 客户端请求域名
3. ESA 转换规则加请求头：
   X-Forwarded-Proto = client scheme
   X-Forwarded-Host  = client host
   X-Forwarded-For   = client ip
4. Nginx:
   proxy_set_header Host $host;
   proxy_set_header X-Forwarded-Proto $scheme;
   proxy_set_header X-Forwarded-For $remote_addr;
5. ThinkPHP config/app.php:
   'proxy_server' => ['ESA回源IP段']
```

**少了第 5 步，TP6 会直接丢弃 X-Forwarded-Proto**，后端仍认为是 http → 拼出 http 的 redirect_uri → 10003。这是最隐蔽的坑。

---

## 八、配置落位对照表

| 配置项 | 平台 | 菜单路径 |
|--------|------|----------|
| 网页授权域名 | 公众号 mp | 设置与开发 → 公众号设置 → 功能设置 → 网页授权域名 |
| JS 接口安全域名 | 公众号 mp | 设置与开发 → 公众号设置 → 功能设置 → JS 接口安全域名 |
| 消息推送 URL/Token/AESKey | 公众号 mp | 设置与开发 → 基本配置 → 服务器配置 |
| 公众号 IP 白名单 | 公众号 mp | 设置与开发 → 基本配置 → IP 白名单 |
| 公众号 AppSecret | 公众号 mp | 设置与开发 → 基本配置 → 开发者密码 |
| 小程序 request 等域名 | 小程序 mp | 开发 → 开发管理 → 开发设置 → 服务器域名 |
| 小程序业务域名 | 小程序 mp | 开发 → 开发管理 → 开发设置 → 业务域名 |
| 小程序 AppSecret | 小程序 mp | 开发 → 开发管理 → 开发设置 → 开发者 ID |
| UnionID 绑定 | open | 管理中心 → 公众账号 / 小程序 → 绑定 |
| 网站应用（扫码登录） | open | 管理中心 → 网站应用 → 创建 |
| 商户号 / APIv3 密钥 | pay | 账户中心 → API 安全 → APIv3 密钥 |
| 商户 API 证书 | pay | 账户中心 → API 安全 → API 证书 |
| AppID 关联商户号 | pay | 产品中心 → AppID 账号管理 |
| 支付回调 URL | 代码里传 | notify_url 参数（不在此后台配，旧版需配支付目录） |
| H5 支付场景域名 | pay | 产品中心 → H5 支付 → 场景域名 |
| 支付授权目录（V2 遗留） | pay | 产品中心 → 开发配置 |

---

## 九、LikeShop 对接标准流程

### 阶段一：账号准备

1. 服务号（已认证）+ 小程序（已认证）+ 商户号 + 开放平台（已认证）
2. 四者**主体一致**
3. 商户号关联公众号 AppID 和小程序 AppID

### 阶段二：公众号配置（mp）

- [ ] 网页授权域名：`xnb.me`
- [ ] JS 接口安全域名：`xnb.me`
- [ ] 上传 `MP_verify_xxx.txt` 到网站根目录并可访问
- [ ] 服务器配置：URL = `https://www.xnb.me/api/wechat/server`，Token 记下，AESKey 记下，安全模式
- [ ] IP 白名单填服务器公网出口 IP

> ⚠️ 推送 URL 用 `www` 更稳（若裸域有 301 跳转）；或按第 6.7 节给该路径加豁免。

### 阶段三：小程序配置（mp）

- [ ] request 合法域名：`https://xnb.me`
- [ ] uploadFile / downloadFile 域名
- [ ] 业务域名：`xnb.me`（web-view 用，需放校验文件）
- [ ] 记录 AppID / AppSecret

### 阶段四：开放平台（open）

- [ ] 绑定服务号 + 小程序
- [ ] 确认 OAuth / jscode2session 返回里有 unionid
- [ ] （可选）创建网站应用做 PC 扫码登录

### 阶段五：支付（pay）

- [ ] 下载 API 证书（apiclient_cert.pem / apiclient_key.pem）放服务器安全目录
- [ ] 设置 APIv3 密钥（32 位）
- [ ] 下载微信支付公钥（或平台证书）
- [ ] 商户号关联公众号 + 小程序 AppID
- [ ] 若需外部浏览器支付：开通 H5 支付并配置场景域名
- [ ] 回调地址：`https://xnb.me/api/pay/notify`、`https://xnb.me/api/refund/notify`

### 阶段六：代码 / 服务器

- [ ] Nginx 给 `/api/pay/notify`、`/api/refund/notify`、`/api/wechat/server` 加豁免跳转
- [ ] ESA 给同样路径加豁免重定向规则
- [ ] Nginx 透传 Host / X-Forwarded-Proto / X-Forwarded-For
- [ ] ThinkPHP `proxy_server` 信任 ESA 回源 IP
- [ ] 基础 access_token、jsapi_ticket 做 Redis 缓存
- [ ] 支付回调做验签 + 解密 + 幂等 + 金额校验
- [ ] 支付加主动查单兜底定时任务

### 阶段七：联调顺序（务必按此顺序）

```
1. OAuth 登录（拿 openid）        ← 先解决 10003
2. JS-SDK 签名（wx.config 通过）
3. 消息推送验证（echostr 返回成功）
4. 小程序 wx.login（拿 openid）
5. UnionID 打通验证（两边 unionid 一致）
6. 下单 + JSAPI 支付（小额 0.01 元测试）
7. 支付回调接收 + 订单状态变更
8. 退款流程
9. 对账（下载昨日对账单核对）
```

---

## 十、错误码速查表

### 公众号 / 授权类

| 错误码/报错 | 原因 | 解决 |
|-------------|------|------|
| **10003** redirect_uri 域名与后台配置不一致 | redirect_uri 域名不在白名单 / 协议不对（http vs https） | 核对后台域名裸域名；修 ESA 回源协议 + 头透传 + TP proxy_server |
| 40001 | AppSecret 错误 / access_token 无效 | 重设 secret，清缓存重取 token |
| 40013 | AppID 无效 | 核对 AppID |
| 40029 | code 无效（已用过或过期） | 重新走授权，不要复用 code |
| 40125 | AppSecret 无效 | 商户/公众号后台重置 |
| 40164 | 调用 IP 不在白名单 | mp 后台加 IP |
| 45009 | 接口调用超限 | 加缓存，减少调用频率 |
| 48001 | 接口未授权（服务号未认证） | 完成认证 |
| 50002 | 用户受限（未关注/被封） | 提示用户关注 |
| invalid signature | JS-SDK 签名错误 | url 用 `split('#')[0]`；ticket 缓存校验；注意 encodeURIComponent |
| config:invalid url domain | 域名不在 JS 安全域名 | 补齐后台配置 |

### 小程序类

| 报错 | 原因 |
|------|------|
| `request:fail url not in domain list` | request 域名未配 / 未备案 / 带端口 |
| `不支持打开该域名` | web-view 域名未加业务域名 |
| `41004` | 小程序 AppSecret 缺失/错误 |
| `40165` | 请求的 openid 非本小程序 |
| `47001` | 数据格式错误（JSON 拼错） |

### 微信支付类

| 错误码 | 含义 | 处理 |
|--------|------|------|
| `APPID_MCHID_NOT_MATCH` | AppID 与商户号未关联 | pay 后台关联 |
| `PARAM_ERROR` | 参数错误（金额单位/字段名） | 检查 total 单位是分 |
| `SIGN_ERROR` / `SIGNATURE_ERROR` | 签名错误 | V3 签名串换行 `\n`、私钥路径、序列号 |
| `ORDERPAID` | 订单已支付 | 幂等处理，直接返回成功 |
| `ORDER_CLOSED` | 订单已关闭 | 重新下单 |
| `OUT_TRADE_NO_USED` | 订单号重复使用 | 换新单号/幂等复用原单 |
| `NOT_ENOUGH` | 余额不足 | 提示用户 |
| `PAYER_OPENID_NOT_MATCH` | openid 与 appid 不匹配（公众号 openid 用在小程序） | 用对应 AppID 的 openid |
| `NO_AUTH` | 无该接口权限 | 商户平台开通产品 |
| `FREQUENCY_LIMITED` | 频率超限 | 降低请求频率 |
| 验签失败（回调） | 平台证书/公钥过期、串拼错 | 更新证书，检查串格式与 timestamp |

---

## 十一、避坑总纲

### 1. 跳转是万恶之源

- **微信服务器主动发起的请求一律不跟随 301/302**：消息推送、支付回调、退款回调、授权验证 echostr
- 用户浏览器发起的跳转没问题：OAuth、H5 支付中间页
- **做法**：给这些路径在 Nginx 和 ESA 双向加豁免，或干脆推送/回调统一用 `www` 域名

### 2. 域名配置四条铁律

1. 公众号的"网页授权域名"和"JS 安全域名"是**两条独立配置**，各填一次
2. 都只填裸域名，不带协议、路径、端口、泛域名
3. 都需要 `MP_verify_xxx.txt` 校验文件在根目录可访问
4. 小程序的"业务域名"≠"request 域名"

### 3. 三种 token 不要混

- 基础 access_token（公众号后台接口）
- 网页授权 access_token（拉用户信息）
- 小程序 access_token（订阅消息等）
- jsapi_ticket（JS-SDK 签名）

全部要**缓存**，全部 **2 小时过期**，全部**不要每次请求现取**。

### 4. code 特性

- 5 分钟有效、一次性、不可缓存、不可复用、不可前端保存

### 5. 支付五条命

1. 金额单位是**分**
2. 回调必须**验签 + 解密 + 校验金额 + 幂等**
3. **以回调为准**，前端 success 只是提示
4. 必须有**主动查单兜底**
5. V3 签名串**最后一行必须带 `\n`**

### 6. 代理环境（ESA/CDN）三件套

1. 回源协议 follow
2. Host / X-Forwarded-Proto / X-Forwarded-For 透传
3. ThinkPHP `proxy_server` 信任代理 IP

**缺一环，后端识别成 http，OAuth 10003、支付回调异常一起爆发。**

### 7. openid 与 unionid

- openid 只在单应用内有效
- 打通账号必须走开放平台 unionid
- 支付时 openid 必须与下单传的 AppID 属于**同一应用**

---

## 十二、附录：常用接口清单

### 公众号

| 用途 | 接口 |
|------|------|
| 获基础 token | `GET https://api.weixin.qq.com/cgi-bin/token` |
| 获 jsapi_ticket | `GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?type=jsapi` |
| OAuth 换 token | `GET https://api.weixin.qq.com/sns/oauth2/access_token` |
| 刷新 OAuth token | `GET https://api.weixin.qq.com/sns/oauth2/refresh_token` |
| 拉用户信息 | `GET https://api.weixin.qq.com/sns/userinfo` |
| 校验 OAuth token | `GET https://api.weixin.qq.com/sns/auth` |
| 创建菜单 | `POST https://api.weixin.qq.com/cgi-bin/menu/create` |
| 模板消息 | `POST https://api.weixin.qq.com/cgi-bin/message/template/send` |
| 订阅通知 | `POST https://api.weixin.qq.com/cgi-bin/message/subscribe/bizsend` |
| 生成带参二维码 | `POST https://api.weixin.qq.com/cgi-bin/qrcode/create` |

### 小程序

| 用途 | 接口 |
|------|------|
| 登录换 openid | `GET https://api.weixin.qq.com/sns/jscode2session` |
| 获小程序 token | `GET https://api.weixin.qq.com/cgi-bin/token` |
| 订阅消息 | `POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send` |
| 获取手机号 | `POST https://api.weixin.qq.com/wxa/business/getuserphonenumber` |
| 生成小程序码 | `POST https://api.weixin.qq.com/wxa/getwxacodeunlimit` |
| 内容安全检测 | `POST https://api.weixin.qq.com/wxa/msg_sec_check` |

### 微信支付 V3

| 用途 | 接口 |
|------|------|
| JSAPI/小程序下单 | `POST https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi` |
| H5 下单 | `POST https://api.mch.weixin.qq.com/v3/pay/transactions/h5` |
| Native 下单 | `POST https://api.mch.weixin.qq.com/v3/pay/transactions/native` |
| APP 下单 | `POST https://api.mch.weixin.qq.com/v3/pay/transactions/app` |
| 查单 | `GET https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{no}?mchid=` |
| 关单 | `POST https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{no}/close` |
| 申请退款 | `POST https://api.mch.weixin.qq.com/v3/refund/domestic/refunds` |
| 查询退款 | `GET https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/{out_refund_no}` |
| 交易账单 | `GET https://api.mch.weixin.qq.com/v3/bill/tradebill` |
| 资金账单 | `GET https://api.mch.weixin.qq.com/v3/bill/fundflowbill` |
| 下载平台证书 | `GET https://api.mch.weixin.qq.com/v3/certificates` |

---

## 附：一页纸速记

```
平台：mp(账号配置) / open(身份打通) / pay(收钱) / developers(文档)

公众号三配置：
  网页授权域名 → 为 OAuth 登录（拿 openid）
  JS 安全域名  → 为拍照/定位/分享/JSAPI 支付
  消息推送 URL → 为收消息事件（禁 301）

小程序四域名 + 业务域名：
  request/upload/download/socket → 前端调接口
  业务域名 → web-view 嵌 H5

身份：openid (单应用) / unionid (跨应用，需 open 绑定)

支付：
  选对产品（微信内=JSAPI，小程序=小程序支付，外部浏览器=MWEB）
  金额单位分；回调验签解密校额幂等；以回调为准；查单兜底

代理：
  ESA 回源 follow + 头透传 + TP proxy_server

铁律：
  微信服务器主动请求 → 绝不能被 301
```

> （注：部分内容由豆包 AI 生成）