技术文章

微信公众号 / 小程序 / 微信支付 开发全流程教程
技术文章 2026-11-17 13 阅读

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

小泥巴 重庆市小泥吧科技有限公司 2026-11-17


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


目录

  1. 先分清五大平台

  2. 核心术语总表

  3. 公众号(服务号)体系

  4. 小程序体系

  5. 微信开放平台 / UnionID 体系

  6. 微信支付体系(重点)

  7. 完整数据流总览

  8. 配置落位对照表

  9. 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 是两套东西(只是可以互相关联绑定)。


二、核心术语总表


术语归属含义有效期/限制
AppIDmp / open应用唯一标识(公众号、小程序、开放平台各自一个)永久
AppSecretmp / open应用密钥,换取 access_token 用永久,务必保密、只存后端
openid公众号 / 小程序用户在单个应用内的唯一 ID永久,但换应用就变
unionidopen同一主体下,用户跨公众号/小程序/APP 唯一不变 ID永久,需绑定开放平台
code各处临时授权票据5 分钟、一次性
access_token(基础)公众号 mp调公众号后台接口的全局凭证2 小时,需缓存 + IP 白名单
access_token(网页授权)公众号 OAuth拉取用户信息专用2 小时,与基础 token 不通用
session_key小程序解密手机号等敏感数据的会话密钥随登录刷新
jsapi_ticket公众号 mpJS-SDK 签名票据2 小时,需缓存
prepay_idpay统一下单返回的预支付订单号2 小时
mch_idpay商户号永久
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
scopesnsapi_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 + openidopenid + 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 支付原生 AppSDK 调起开放平台移动应用 + 应用签名
付款码支付线下收银扫用户付款码商户扫开通刷卡支付
刷脸支付线下设备设备 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方法 URL路径 时间戳 随机串 请求体 (每行末尾 )

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

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

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.chooseWXPaywx.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 nonce body (每行末尾 ,最后一行也要 )
用微信支付公钥(或对应平台证书公钥)做 SHA256-RSA 验签

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

6.7 支付回调的 Nginx / ESA 必配

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

# 支付回调、微信消息推送,禁止域名跳转,直接透传
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 签名串最后一行必须带 ,少一个换行就验签失败(超高频坑)

  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
40001AppSecret 错误 / access_token 无效重设 secret,清缓存重取 token
40013AppID 无效核对 AppID
40029code 无效(已用过或过期)重新走授权,不要复用 code
40125AppSecret 无效商户/公众号后台重置
40164调用 IP 不在白名单mp 后台加 IP
45009接口调用超限加缓存,减少调用频率
48001接口未授权(服务号未认证)完成认证
50002用户受限(未关注/被封)提示用户关注
invalid signatureJS-SDK 签名错误url 用 split('#')[0];ticket 缓存校验;注意 encodeURIComponent
config:invalid url domain域名不在 JS 安全域名补齐后台配置


小程序类


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


微信支付类


错误码含义处理
APPID_MCHID_NOT_MATCHAppID 与商户号未关联pay 后台关联
PARAM_ERROR参数错误(金额单位/字段名)检查 total 单位是分
SIGN_ERROR / SIGNATURE_ERROR签名错误V3 签名串换行 、私钥路径、序列号
ORDERPAID订单已支付幂等处理,直接返回成功
ORDER_CLOSED订单已关闭重新下单
OUT_TRADE_NO_USED订单号重复使用换新单号/幂等复用原单
NOT_ENOUGH余额不足提示用户
PAYER_OPENID_NOT_MATCHopenid 与 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 签名串最后一行必须带

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 属于同一应用


十二、附录:常用接口清单

公众号


用途接口
获基础 tokenGET https://api.weixin.qq.com/cgi-bin/token
获 jsapi_ticketGET https://api.weixin.qq.com/cgi-bin/ticket/getticket?type=jsapi
OAuth 换 tokenGET https://api.weixin.qq.com/sns/oauth2/access_token
刷新 OAuth tokenGET https://api.weixin.qq.com/sns/oauth2/refresh_token
拉用户信息GET https://api.weixin.qq.com/sns/userinfo
校验 OAuth tokenGET 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


小程序


用途接口
登录换 openidGET https://api.weixin.qq.com/sns/jscode2session
获小程序 tokenGET 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

微信开发全流程教程_公众号小程序支付.md


相关标签:

发表评论:

评论记录:

未查询到任何数据!
QQ咨询
回电话
回拨通话

我们稍后回拨您的电话

座机请加区号

微信联系
微信扫一扫
微信二维码

扫码加微信