微信公众号接口使用说明

本文档介绍 Laravel Skel 项目中微信公众号模块的接口使用方法、流程与注意事项。

模块概览

微信公众号模块基于 EasyWeChat 封装，提供以下能力：

网页授权：支持 snsapi_base 与 snsapi_userinfo 两种授权方式

用户信息：通过授权 code 获取微信用户基本信息

AccessToken：获取公众号全局 AccessToken

消息回调：接收微信推送的消息与事件，并以事件形式分发

网络检测：检测服务器与微信服务器的通信链路

前置配置

在使用微信公众号接口前，请确保以下环境变量已正确配置：

变量名	说明	必填
`WECHAT_APP_ID`	公众号 AppID	是
`WECHAT_APP_SECRET`	公众号 AppSecret	是
`WECHAT_TOKEN`	服务器配置 Token（消息回调校验用）	消息回调必填
`WECHAT_AES_KEY`	消息加解密密钥（安全模式）	否
`WECHAT_USE_STABLE_ACCESS_TOKEN`	是否使用稳定版 AccessToken，默认 true	否

配置文件位于 config/services.php，键名为 wechat。

接口清单

接口	方法	路径	说明
网络通信检测	POST	`/wechat/check`	调用微信网络检测接口
跳转微信授权	GET	`/wechat/auth`	标准网页授权入口（snsapi_userinfo）
授权回调	GET	`/wechat/auth-callback`	标准授权回调地址
授权重定向	GET	`/wechat/authorize-redirect/{redirect_uri?}`	带自定义回跳地址的授权中转
授权代理	GET	`/wechat/authorize-proxy/{redirect_uri?}`	纯 URL 拼接式授权代理
获取用户信息	GET	`/wechat/user-info`	通过 code 换取用户信息
获取 AccessToken	GET	`/wechat/token`	获取公众号全局 AccessToken
消息回调	ANY	`/wechat/serve`	微信服务器配置的消息/事件接收地址

网页授权流程

方式一：标准授权（推荐）

适合业务系统自身的微信登录场景。

前端重定向到 /wechat/auth

用户在微信中确认授权

微信回调到 /wechat/auth-callback?code=xxx

后端通过 code 换取用户信息并返回 JSON

方式二：带自定义 redirect_uri 的授权中转

适合需要把微信 code 透传给第三方业务系统的场景。

构造请求地址：

/wechat/authorize-redirect?redirect_uri={你的业务回调地址}&scope=snsapi_userinfo

redirect_uri 为明文的业务回调地址，需 URL 编码

scope 可选，默认 snsapi_base

接口自动跳转到微信授权页

微信授权后回跳到本接口，并携带 code 参数

接口再将 code（作为 wx_code 参数）拼接到原始 redirect_uri 后，重定向回业务系统：

{redirect_uri}?wx_code=xxx&state=xxx

redirect_uri 在 URL 路径中传递时使用 Base64 URL 安全编码（base64_urlencode），避免特殊字符问题。

方式三：授权代理（透明转发）

直接拼接微信授权 URL 并跳转，不经过 SDK 封装层，适合需要完全自定义授权参数的场景。

请求参数与微信官方一致：appid、redirect_uri、response_type、scope、state 等。

消息与事件回调

服务器配置

在微信公众平台「开发者工具 → 基本配置 → 服务器配置」中填写：

URL：https://your-domain.com/wechat/serve

Token：与 WECHAT_TOKEN 一致

EncodingAESKey：与 WECHAT_AES_KEY 一致（明文模式可留空）

消息加解密方式：根据需要选择

事件分发机制

服务端收到微信推送后，会通过 Laravel 事件机制分发业务逻辑：

微信事件	Laravel 事件类	是否异步队列	说明
`subscribe`	`WechatSubscribed`	是	新用户关注公众号
`subscribe`（带 EventKey）	`WechatScan`	否	扫描带参数二维码关注
`unsubscribe`	`WechatUnsubscribed`	是	用户取消关注
`SCAN`	`WechatScan`	否	已关注用户扫描二维码

事件均实现 ShouldHandleEventsAfterCommit，确保在数据库事务提交后才触发。

自定义事件监听

在 app/Providers/EventServiceProvider.php 中注册监听器，或使用属性注解：

常见问题

Q1: 调用接口报「微信公众号未配置」错误

检查 .env 文件中是否设置了 WECHAT_APP_ID 和 WECHAT_APP_SECRET。

Q2: 消息回调验签失败

确认 WECHAT_TOKEN 与微信后台服务器配置中的 Token 完全一致

检查 URL 是否可被微信服务器公网访问

确认服务器时间准确（用于签名校验）

Q3: AccessToken 获取频繁受限

AccessToken 有每日调用次数限制，请使用缓存。本项目已将 EasyWeChat 的缓存驱动接入 Laravel 缓存系统，默认会自动缓存。

Q4: 网页授权提示「redirect_uri 参数错误」

确保回调域名已在微信公众平台「设置 → 公众号设置 → 功能设置 → 网页授权域名」中配置

回调地址必须使用配置的域名，不能是 IP 地址

注意 redirect_uri 需要 URL 编码

安全建议

网页授权的 state 参数建议携带业务校验值，防止 CSRF 攻击

消息回调接口已由 EasyWeChat 内置验签，不要关闭签名校验

接口使用说明

微信公众号接口使用说明#

模块概览#

前置配置#

接口清单#

网页授权流程#

方式一：标准授权（推荐）#

方式二：带自定义 redirect_uri 的授权中转#

方式三：授权代理（透明转发）#

消息与事件回调#

服务器配置#

事件分发机制#

自定义事件监听#

常见问题#

Q1: 调用接口报「微信公众号未配置」错误#

Q2: 消息回调验签失败#

Q3: AccessToken 获取频繁受限#

Q4: 网页授权提示「redirect_uri 参数错误」#

安全建议#