Wechatpy 已停更，因不支持新版消息加解密、OAuth 域名校验、订阅通知等，且模板消息接口已下线；推荐迁移到 wechatpy-ng 或手写 requests 封装。
Wechatpy 已停止维护，wechatpy 从 2023 年起不再发布新版本，官方明确建议迁移到 wechatpy-ng 或自行封装原生 API；直接用旧版接入新微信平台（尤其是消息加解密、网页授权回调域名校验、模板消息停用等）大概率失败。
为什么 wechatpy 在 2024 年后很难跑通公众号后台
微信官方自 2022 年起逐步收紧接口策略，而 wechatpy 最后稳定版（2.3.1）发布于 2021 年，缺失以下关键支持：
-
AESDecryptMsg对新版消息加解密协议（含encodingAESKey长度校验、PKCS#7 填充兼容）处理不严谨，常见报错：ValueError: Input strings must be a multiple of 16 in length - 未适配「网页授权域名白名单强制 HTTPS + 二级域名校验」逻辑，
WeChatOAuth构造的 redirect_uri 在新后台会直接被拦截 - 模板消息接口已全量下线，但
client.message.send_template仍存在，调用返回{"errcode":48002,"errmsg":"api forbidden"} - 不支持「订阅通知」（即新模板消息替代方案）所需的
subscribe_msg接口与 JWT 签名流程
用 wechatpy-ng 替代时必须改写的三处核心代码
wechatpy-ng 是社区维护的活跃分支，兼容 Python 3.8+，修复了加解密、OAuth 域名校验等关键问题，但接口有 Breaking Change：
- 初始化客户端不再用
WeChatClient，改用wechatpy_ng.WeChatClient，且app_id/app_secret必须显式传入，不能靠全局配置 - 消息解密逻辑移至
WeChatMessageHandler类，需手动传入token、encoding_aes_key、app_id，不再隐式读取wechatpy.conf -
WeChatOAuth的authorize_url方法新增force_refresh参数，默认为False；若用户已授权但需要重新拉授权页，必须设为True，否则跳转后直接报错invalid scope
示例：旧写法（失效）→ 新写法（有效）
立即学习“Python免费学习笔记（深入）”；
# 旧（wechatpy） from wechatpy import WeChatClient client = WeChatClient(appid, secret) <h1>新（wechatpy-ng）</h1><p>from wechatpy_ng import WeChatClient client = WeChatClient(appid=appid, secret=secret)
绕过库直接对接微信 API 的最小可行路径
当业务涉及「客服消息」、「用户标签管理」或「微信支付回调验签」等冷门接口，或需要精确控制 HTTP 超时/重试逻辑时，硬依赖库反而增加调试成本。推荐保留 requests + 手写封装：
- 所有 POST 请求统一加
json参数（非data），微信 API 严格要求Content-Type: application/json - access_token 获取必须带
grant_type=client_credential，且每次请求需校验返回体中的errcode字段，0才算成功，否则要记录errmsg日志 - 消息推送接口（如
https://api.weixin.qq.com/cgi-bin/message/custom/send）要求openid必须是目标用户真实 ID，测试时若用test_openid模拟会静默失败，无任何错误提示
关键点：微信服务器对 header 大小写敏感，Authorization 不能写成 authorization；timestamp 和 nonce 必须参与签名，且时间戳误差不能超过 5 分钟，否则验签失败返回 {"errcode":40001,"errmsg":"invalid credential"}
真正卡住开发的往往不是「怎么写」，而是微信后台配置项和代码参数的映射关系——比如 encodingAESKey 在公众平台填的是 43 位 Base64 字符串，但代码里要用 base64.b64decode() 解码后传给解密函数，漏掉这步就必然报填充错误。
