核心功能特性
全平台适配
统一接口封装公众号、小程序、企业微信、微信开放平台,支持多账号配置管理,一套代码跨平台运行。
高安全性保障
内置消息加解密(AES/CBC/PKCS7)、签名验证、Token校验、IP白名单过滤、敏感词过滤机制,严格遵循微信安全规范。
消息中间件
支持异步消息队列处理(Redis/MySQL),实现消息重试、失败归档、延迟推送、模板消息批量发送、客服消息定时触发。
OAuth2授权体系
完整实现网页授权(snsapi_base/snsapi_userinfo)、静默授权与弹窗授权双流程,支持用户信息缓存与 unionID 统一身份识别。
微信支付集成
深度集成Native、JSAPI、小程序支付、企业付款,支持分账、退款、账单下载、支付回调验证与幂等处理。
数据统计分析
对接用户分析、消息分析、接口分析、网页分析接口,支持数据聚合、趋势图表生成与报表导出。
模块化技术架构
消息处理引擎
完整支持微信服务器消息推送与客服消息主动发送机制,提供消息类型识别、内容解析、状态回执、防重放攻击、消息加密解密、消息去重等核心能力。
支持消息类型:
- 文本消息(text)
- 图片消息(image)
- 语音消息(voice)
- 视频消息(video)
- 小视频消息(shortvideo)
- 地理位置消息(location)
- 链接消息(link)
- 事件推送(event):关注/取消关注、扫描二维码、点击菜单、地理位置上报、支付成功通知等
- 小程序消息卡片(miniprogrampage)
典型处理流程:
- 微信服务器推送消息 → 携带 signature、timestamp、nonce、encrypt_type
- 服务端校验 signature(SHA1(token+timestamp+nonce))
- 若 encrypt_type=aes,则使用 AESKey 解密消息体
- 解析 XML / JSON,提取消息类型与内容
- 业务逻辑处理(如:关键词回复、订单查询、用户咨询转人工)
- 构造响应消息(文本/图文/菜单/小程序卡片),加密后返回
示例代码:
| 消息类型 | 响应策略 |
|---|---|
| 关键词:优惠券 | 图文消息 + 活动链接 + 二维码 |
| 地理位置上报 | 附近门店列表(含距离排序) |
| 支付成功事件 | 发送订单详情 + 发票申请入口 |
| 菜单点击:customer_service | 跳转客服聊天窗口或返回“转人工”提示 |
用户管理与身份体系
基于微信 UnionID 机制,实现跨应用用户身份统一识别。支持用户信息缓存、标签管理、黑名单处理、粉丝分组、用户行为追踪等。
核心能力:
- 通过 OAuth2 授权获取用户 openid(单公众号)或 unionid(同一主体下多应用)
- 用户信息同步至本地数据库(昵称、头像、性别、地区、关注时间、标签)
- 标签批量绑定/解绑(单次最多50个用户)
- 黑名单管理(拉黑/取消拉黑,需用户主动操作)
- 用户分组迁移(旧分组ID映射至新分组)
UnionID 生成规则:
当用户在同一微信开放平台账号下的多个应用(公众号、小程序、移动应用)中授权登录后,微信将为该用户生成唯一 UnionID。若未绑定开放平台,则各应用返回独立 openid。
典型业务场景:
- 用户在公众号关注后,在小程序登录时自动识别为同一人
- 用户从APP跳转至公众号菜单页,无需重复授权
- 统一会员体系:订单、积分、等级跨平台同步
素材管理与内容运营
覆盖临时素材(3天有效期)与永久素材(图文、图片、语音、视频、封面)的上传、查询、删除、修改能力,支持图文消息批量管理与封面图预览。
永久素材类型:
- 图文消息(news):单条最多8张图文,支持封面+标题+摘要+原文链接
- 图片(image):上传后生成 media_id,用于消息发送或菜单
- 语音(voice):需符合微信格式(MP3/WMA/WAV/AMR),时长≤60秒
- 视频(video):需上传 description 字段(标题/简介)
图文素材管理最佳实践:
- 上传封面图 → 获取 media_id
- 构造图文消息 JSON:title、thumb_media_id、author、digest、show_cover、content、content_source_url
- 调用“新增永久图文素材”接口
- 返回 media_id,用于后续群发或菜单跳转
封面图规范:
- 尺寸建议:900×500像素
- 格式:JPG/PNG
- 大小:≤64KB
- 禁止含二维码、水印、第三方LOGO
微信支付集成
支持Native(扫码支付)、JSAPI(公众号支付)、小程序支付、H5支付、企业付款等全场景接入,严格遵循微信支付V3 API规范。
JSAPI支付流程:
- 用户点击“立即支付” → 调用统一下单接口(trade_type=JSAPI)
- 获取 prepay_id → 构造支付参数(appId、timeStamp、nonceStr、package、signType、paySign)
- 前端调用 WeixinJSBridge.invoke('getBrandWCPayRequest', ...)
- 用户输入密码 → 支付成功 → 微信服务器异步通知(POST /pay/notify)
- 服务端校验签名 → 更新订单状态 → 返回 SUCCESS
支付回调验签要点:
- 检查 request_id 是否重复(防重放)
- 验证签名(使用微信支付平台证书)
- 确认 out_trade_no 与本地订单匹配
- 校验 total_fee 是否一致
- 更新订单状态后,必须返回 <xml><return_code><![CDATA[SUCCESS]]></return_code></xml>
常见支付失败原因:
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| INVALID_REQUEST | 参数格式错误或缺失 | 检查 spbill_create_ip、notify_url 是否符合规范 |
| ORDER_PAID | 订单已支付 | 禁止重复下单,需返回“订单已存在”提示 |
| NOTENOUGH | 余额不足 | 提示用户更换支付方式(如券/红包) |
| AUTH_NO_AUTH | 无支付权限 | 检查商户号是否开通对应产品(如小程序支付需绑定小程序) |
版本演进与里程碑
完成微信支付V3 API(RFC7515签名)重构,新增商户券、商家券、分账、支付即服务(Payment as a Service)支持,适配微信支付商户平台V3接口规范。
新增企业微信会话存档API封装、客户联系(contact)能力支持(添加外部联系人、标签管理、客户详情查询),满足企业级办公协同需求。
采用模块化设计,解耦公众号、小程序、开放平台核心逻辑;引入PSR-18 HTTP客户端抽象层,兼容Guzzle/Swoole/ReactPHP;支持Laravel 9/10、ThinkPHP 6.0+无缝集成。
新增订阅消息模板管理(subscribe.getTemplateList)、订阅交互(subscribe.requestTemplateId)、消息发送(message.subscribe.send),适配小程序消息触达新机制。
实现移动应用/公众号/小程序三端账号绑定,支持unionid自动拉取、绑定关系查询、解绑操作,解决多应用用户身份割裂问题。
全面支持微信JS-SDK 1.6.0新特性:视频播放器、地理位置接口增强、摇一摇周边、设备信息获取,修复iOS 15 Safari兼容性问题。
开源php微信框架 2.0.0,提供Composer包管理、完整文档、Docker部署方案,累计Star数突破8,200+。
典型应用场景与案例
基于php微信框架构建会员中心,集成:
- 扫码点餐(JSAPI支付)
- 会员卡领取(OAuth2授权)
- 积分兑换(模板消息推送)
- 门店地图(地理位置上报)
实现用户转化率提升37%,复购频次提高1.8倍。
开发微信小程序+公众号双端系统:
- 小程序:课程购买(小程序支付)
- 公众号:学习提醒(订阅消息)、资料下载(素材管理)
- 后台:用户学习路径追踪、完课率统计
月活用户达24万,付费转化率12.6%。
构建企业微信客户联系系统:
- 自动分配客户(标签+地域匹配)
- 聊天记录存档(企业微信API)
- 客户标签自动打标(行为分析)
- 服务满意度调研(模板消息)
客服响应时效提升至23秒,客户留存率提高28%。
常见问题解答
A:请依次检查:
- 微信服务器配置中的Token、EncodingAESKey是否与代码一致
- 消息加解密模式是否与服务器配置匹配(兼容模式/安全模式)
- 开发者服务器是否正常响应(查看日志,确认无5xx错误)
- 是否在公众平台后台设置了自动回复规则(规则优先级高于代码)
A:需确认:
- 授权范围是否为 snsapi_userinfo(非 snsapi_base)
- 用户是否已关注公众号(未关注则仅返回openid)
- access_token 是否有效(检查 expires_in)
- 用户昵称是否含特殊字符(如emoji),需在数据库字段使用 utf8mb4 编码
A:常见原因:
- 未在公众号后台配置JS接口安全域名(设置 → 公众号设置 → 功能设置)
- 签名生成使用了错误的URL(必须是当前页面完整URL,不含#哈希)
- jsapi_ticket 是否过期(有效期7200秒,需缓存)
- AppID 是否与当前公众号一致
A:请排查:
- 回调URL是否能公网访问(微信服务器需直接访问,不可跳转)
- 是否正确解析POST数据(需使用 file_get_contents('php://input'))
- 是否返回正确格式的XML(必须为 <xml> 根节点,非 <response>)
- 微信服务器通知重试机制:失败后15秒/30秒/3分钟/5分钟/10分钟/30分钟/1小时/2小时/3小时重试,共8次
A:操作步骤:
- 查询分组ID:GET https://api.weixin.qq.com/cgi-bin/groups/get?access_token=ACCESS_TOKEN
- 查询某分组用户列表:GET https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID
- 批量移动用户:POST https://api.weixin.qq.com/cgi-bin/groups/members/batchtagging?access_token=ACCESS_TOKEN
- 删除空分组(可选):POST https://api.weixin.qq.com/cgi-bin/groups/update?access_token=ACCESS_TOKEN