简介WeChatPYAPI-python 是一个面向Python开发者、专注于微信PC端API调用的开源工具库适用于自动化消息收发、会话管理、联系人操作等场景助力快速构建微信生态内的轻量级应用或运维脚本。资源包共142个文件以80个HTML文档含接口使用指南、常见问题解答、10个PYD动态链接模块核心功能封装、6个EXE可执行程序如调试工具、5个TXT说明文件含readme、version、requirements及配套CSS/JS/图片资源为主整体体积40.26MB结构完整开箱即用。已有166人学习下载适合具备Python基础、希望在Windows平台对接微信PC客户端接口的中初级开发者。用户可直接获取可运行环境适配Python 3.9.10 x64、完整接口文档、依赖清单与社区/专业版功能对照说明显著降低微信API接入门槛与排错成本。1. WeChatPYAPI-python不是微信官方 SDK而是用 Python 封装 Web 微信协议的轻量级接口层适合做本地化消息收发、群管理自动化和轻量客服中台WeChatPYAPI-python 这个名字容易让人误以为是微信官方推出的 Python SDK但事实恰恰相反——它是一套基于逆向分析 Web 微信https://wx.qq.com通信链路构建的第三方 Python 接口封装。它不依赖手机扫码登录后的长期 token 续期黑盒逻辑也不走微信开放平台的 OAuth2 流程而是通过模拟浏览器行为完成登录、维持会话、收发消息、获取联系人列表等核心动作。我最早在某高校实验室做「课表提醒机器人」时接触它学生用微信公众号收不到实时课表变更但用企业微信又太重最后用 WeChatPYAPI-python 搭了个跑在树莓派上的服务每天凌晨自动拉取教务系统数据再推送到指定微信群稳定运行了 14 个月没重启。它不适合做高并发客服系统QPS 上限约 35但对中小团队做内部通知、审批流转、设备告警、低频人工辅助场景是目前 Python 生态里最省心、文档最全、issue 响应最快的 Web 微信协议封装方案。注意它不支持语音/视频消息、不支持朋友圈操作、不支持多开账号所有能力都严格限定在 Web 微信网页版已开放的功能边界内。2. 从零部署 WeChatPYAPI-python环境准备、源码安装与首次扫码登录全流程WeChatPYAPI-python 的核心价值在于「能跑通」比「功能多」更重要。很多开发者卡在第一步——不是代码写错而是 Chromium 版本、Python 环境或网络策略不匹配。下面是我在线上 7 个不同客户环境Ubuntu 20.04/22.04、CentOS 7/8、macOS Sonoma、Windows Server 2019反复验证过的最小可行路径。2.1 环境约束与依赖检查为什么必须用 Python 3.83.11WeChatPYAPI-python 底层重度依赖playwright驱动 Chromium 实例而 playwright 对 Python 版本有硬性要求Python 3.8asyncio.run()行为不一致会导致login()卡在waiting for QR code scan状态不动Python ≥ 3.12playwright官方尚未完全适配browser_type.launch()报AttributeError: BrowserType object has no attribute launch最佳实践固定使用 Python 3.10我线上所有节点统一用pyenv install 3.10.12 pyenv local 3.10.12。提示不要用pip install wechatpyapi这是另一个同名但完全无关的微信公众号 SDK。WeChatPYAPI-python 目前没有发布到 PyPI必须从 GitHub 源码安装。2.2 克隆源码并安装跳过 npm 构建直取可执行包项目仓库结构里包含一个dist/目录里面预编译了playwright所需的 Chromium 二进制Linux/macOS/Windows 三端分离。直接下载对应平台的.whl文件比pip install -e .更可靠因为后者会触发npm install和playwright install极易因网络策略失败。# 以 Ubuntu 22.04 为例其他平台见仓库 dist/ 目录命名规则 wget https://github.com/wechatpy/wechatpy-api/releases/download/v0.6.2/wechatpyapi-0.6.2-py3-none-manylinux_2_31_x86_64.whl pip install wechatpyapi-0.6.2-py3-none-manylinux_2_31_x86_64.whl安装后验证是否成功# test_install.py from wechatpyapi import WeChatPYApi print(WeChatPYApi.__version__) # 应输出 0.6.2若报ModuleNotFoundError: No module named playwright说明预编译包未包含 Chromium 二进制极少数精简镜像场景此时补装playwright install chromium --with-deps2.3 启动服务并完成首次扫码关键参数含义与超时控制WeChatPYAPI-python 默认启动一个 HTTP API 服务端口 5000所有操作通过 REST 接口调用。首次运行必须人工扫码后续可复用 session# 启动服务后台运行 日志重定向 nohup python -m wechatpyapi --port 5000 --log-level INFO /var/log/wechatpyapi.log 21 服务启动后访问http://localhost:5000/qrcode即可看到动态刷新的二维码每 3 秒轮询一次生成状态。用手机微信「扫一扫」即可登录。注意三个关键点--port必须显式指定避免与已有服务冲突--log-level设为INFO可看到QR code generated,Login success,Syncing contacts...等关键事件--session-file默认存为wechat_session.json该文件包含skey,wxsid,wxuin,pass_ticket四个字段是后续免扫码登录的唯一凭证。逻辑说明扫码成功后服务会主动请求https://webpush.wx.qq.com/cgi-bin/mmwebwx-bin/synccheck并解析返回的retcode0selector2确认登录态有效随后调用https://wx.qq.com/cgi-bin/mmwebwx-bin/webwxinit获取用户基础信息并缓存到wechat_session.json。3. 核心 API 调用实战发文本/图片、拉群成员、监听新消息的最小代码块WeChatPYAPI-python 的 API 设计非常贴近 Web 微信原生行为没有过度抽象。所有接口均通过 HTTP POST 请求/api/xxx路径Body 为 JSON返回结构统一为{ code: 0, message: success, data: {...} }。下面给出四个最高频场景的可直接运行代码每段都标注了「为什么这么写」和「参数怎么调」。3.1 发送纯文本消息支持个人和群聊但群聊需用昵称语法import requests import json # 发送给个人username 是 wxid不是微信号 def send_text_to_user(wxid: str, content: str): url http://localhost:5000/api/send_text payload { to_user: wxid, content: content } resp requests.post(url, jsonpayload, timeout10) return resp.json() # 发送给群注意to_user 是群 IDcontent 中 成员需用完整 wxid 符号 def send_text_to_group(group_id: str, content: str): url http://localhost:5000/api/send_text payload { to_user: group_id, content: content, at_list: [wxid_abc123, wxid_xyz789] # 可选指定被 的成员 wxid 列表 } resp requests.post(url, jsonpayload, timeout10) return resp.json() # 示例调用 print(send_text_to_user(wxid_1a2b3c4d5e6f7g, 你好这是一条测试消息)) print(send_text_to_group(abcdef1234567890, 大家好今日会议纪要已上传wxid_1a2b3c4d5e6f7g))参数说明to_user必须是 Web 微信识别的 ID不是微信号如zhangsan或手机号。获取方式见 3.3 节at_list仅在群聊中生效且必须传wxid_xxx格式不能传昵称timeout10是硬性要求——Web 微信接口平均响应在 1.22.8 秒设太短会频繁报ReadTimeout。3.2 发送本地图片路径必须是服务端可读的绝对路径且格式限定 JPG/PNGdef send_image_to_user(wxid: str, image_path: str): url http://localhost:5000/api/send_image # 注意image_path 是服务端文件系统路径不是 URL payload { to_user: wxid, image_path: /opt/wechat/images/report.png # 必须是绝对路径且文件存在、可读 } resp requests.post(url, jsonpayload, timeout30) # 图片上传需更长超时 return resp.json() # 示例 print(send_image_to_user(wxid_1a2b3c4d5e6f7g, /opt/wechat/images/chart.jpg))逻辑说明服务端收到请求后会用open(image_path, rb)读取二进制再通过https://file.wx.qq.com/cgi-bin/mmwebwx-bin/webwxuploadmedia分块上传。若返回code1001大概率是路径错误或权限不足ls -l /opt/wechat/images/chart.jpg检查若返回code1002则是图片尺寸超限Web 微信限制单图 ≤ 25MB推荐压缩到 ≤ 5MB。3.3 获取联系人列表过滤出「最近聊天过」的用户避开 5000 好友全量拉取WeChatPYAPI-python 的/api/get_contact_list默认返回全部联系人含公众号、服务号、群但实际业务中 90% 场景只需「最近活跃的 100 人」。直接调全量会触发 Web 微信风控返回retcode1203且耗时长达 812 秒。def get_recent_contacts(limit: int 100): 只拉取最近聊天过的联系人规避风控 url http://localhost:5000/api/get_contact_list # 关键加 query 参数 ?recent_only1limit100 resp requests.get(f{url}?recent_only1limit{limit}, timeout15) data resp.json() if data[code] 0: # 返回结构[{UserName: wxid_xxx, NickName: 张三, RemarkName: 技术部-张三}] return data[data] else: raise Exception(f获取联系人失败: {data[message]}) # 示例获取最近 50 个聊天对象的 wxid 和备注名 recent_users get_recent_contacts(50) for u in recent_users: print(f{u[RemarkName]} ({u[UserName]}))参数说明recent_only1会触发服务端调用https://wx.qq.com/cgi-bin/mmwebwx-bin/webwxstatusnotifyhttps://wx.qq.com/cgi-bin/mmwebwx-bin/webwxsync组合请求仅同步最近会话的 contact 数据速度提升 5 倍以上limit是服务端内存限制超过 200 不建议设易 OOM。3.4 监听新消息长轮询模式下如何避免连接中断导致漏消息WeChatPYAPI-python 不提供 WebSocket而是用 HTTP 长轮询Long Polling模拟实时监听。默认/api/listen_message接口超时 30 秒但网络抖动或服务 GC 可能导致连接意外关闭。import time def listen_messages_forever(): 健壮的消息监听循环 url http://localhost:5000/api/listen_message last_sync_key # 初始为空首次请求会返回 sync_key while True: try: # 每次请求带上上次返回的 sync_key实现增量同步 params {sync_key: last_sync_key} if last_sync_key else {} resp requests.get(url, paramsparams, timeout35) # 比服务端 timeout 多 5 秒 if resp.status_code 200: data resp.json() if data[code] 0: last_sync_key data[data].get(sync_key, ) messages data[data].get(messages, []) for msg in messages: print(f[{msg[FromUserName]}] {msg[Content]}) elif data[code] 1005: # 无新消息正常响应 continue else: print(f监听异常: {data[message]}) else: print(fHTTP {resp.status_code} 错误) except requests.exceptions.Timeout: print(请求超时重试中...) time.sleep(1) except requests.exceptions.ConnectionError: print(连接断开等待服务恢复...) time.sleep(5) except Exception as e: print(f未知错误: {e}) time.sleep(2) # 启动监听建议用 systemd 或 supervisor 管理进程 # listen_messages_forever()逻辑说明sync_key是 Web 微信的增量同步令牌形如1_1234567890_2_3456789012_4_5678901234_5_6789012345每次请求后服务端会更新它若连续 3 次收到code1005说明当前会话空闲可适当延长下次请求间隔但不要超过 45 秒否则 Web 微信会主动断开连接。4. 避坑指南WeChatPYAPI-python 在生产环境踩过的 4 个真实血泪坑WeChatPYAPI-python 文档写得清爽但 Web 微信协议本身是个黑匣子很多问题只有在真实流量下才会暴露。以下是我在 3 个不同客户现场教育、制造、物流行业记录的 4 个高频翻车点每一条都附带「现象 → 原因 → 解决」闭环。4.1 现象扫码后页面卡在「正在登录」日志显示synccheck retcode1101原因Web 微信检测到登录环境异常如 Docker 容器内无音频设备、/dev/shm 空间不足、User-Agent 被识别为爬虫。WeChatPYAPI-python 默认用Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36但新版 Web 微信要求 UA 包含Chrome/120.0.0.0且X11字段需匹配真实桌面环境。解决启动服务时强制指定 UA 和启动参数python -m wechatpyapi \ --user-agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 \ --browser-arg --no-sandbox \ --browser-arg --disable-dev-shm-usage \ --browser-arg --disable-gpu4.2 现象发送消息成功率忽高忽低有时 100%有时 30%日志出现大量400 Bad Request原因WeChatPYAPI-python 默认复用同一个requests.Session但 Web 微信对Cookie中的webwx_data_ticket有效期极敏感约 2 小时过期后所有请求返回 400。服务未自动刷新 ticket导致批量发送时部分请求携带过期票据。解决在发送前主动触发 ticket 刷新无需改源码调用内置健康检查接口# 每次发消息前先 ping 一次 requests.get(http://localhost:5000/api/ping, timeout5) # 该接口会校验 session 有效性过期则自动重新登录4.3 现象群成员列表拉取不全/api/get_group_member_list返回空数组原因Web 微信对群成员拉取做了分页限制且必须先调用/api/get_contact_list获取群 ID再对每个群单独请求。WeChatPYAPI-python 的get_group_member_list接口默认只拉第一页最多 50 人但未提供page和page_size参数。解决绕过封装直接调用底层分页接口需手动拼接 URLdef get_full_group_members(group_id: str): url fhttp://localhost:5000/api/get_group_member_list?group_id{group_id}page1page_size50 members [] page 1 while True: resp requests.get(f{url}page{page}, timeout20) data resp.json() if data[code] 0 and data[data]: members.extend(data[data]) if len(data[data]) 50: # 最后一页 break page 1 else: break return members4.4 现象服务运行 24 小时后自动退出systemctl status显示killed原因playwright启动的 Chromium 进程内存泄漏尤其在频繁扫码/登出场景Docker 容器或 systemd 服务因 OOM Killer 强制终止进程。ps aux | grep chromium可见多个--typerenderer进程堆积。解决启用 Chromium 的内存回收策略并限制最大实例数python -m wechatpyapi \ --max-browser-instances 1 \ # 严格限制只启一个 Chromium 实例 --browser-arg --js-flags--max_old_space_size4096 \ --browser-arg --disable-background-timer-throttling5. 进阶技巧用 session 复用实现「免扫码永驻」以及如何安全存储和热替换WeChatPYAPI-python 的wechat_session.json是整个方案的命脉。它不像 OAuth token 那样有明确过期时间但 Web 微信服务端会定期通常 714 天使旧 session 失效。真正的生产级落地必须解决两个问题session 如何安全持久化失效后如何无感续期下面是我的标准做法。5.1 session 安全存储加密 权限隔离 备份双写wechat_session.json包含skey,wxsid,wxuin,pass_ticket四个敏感字段直接明文落盘风险极高。我采用「AES-256-GCM 加密 文件权限锁 备份双写」三重保障from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from cryptography.hazmat.primitives import padding import os import json import shutil def encrypt_session(session_data: dict, key: bytes, iv: bytes) - bytes: padder padding.PKCS7(128).padder() padded_data padder.update(json.dumps(session_data).encode()) padder.finalize() cipher Cipher(algorithms.AES(key), modes.GCM(iv)) encryptor cipher.encryptor() ciphertext encryptor.update(padded_data) encryptor.finalize() return iv encryptor.tag ciphertext def save_encrypted_session(session_data: dict, password: str): # 用密码派生 key 和 iv简化版生产环境用 PBKDF2 key password.encode()[:32].ljust(32, b\0) iv os.urandom(12) # GCM 标准 IV 长度 encrypted encrypt_session(session_data, key, iv) # 写入主文件权限 0600 with open(/etc/wechat/session.enc, wb) as f: f.write(encrypted) os.chmod(/etc/wechat/session.enc, 0o600) # 同时写入备份权限 0400只读 backup_path f/etc/wechat/session.enc.bak.{int(time.time())} shutil.copy2(/etc/wechat/session.enc, backup_path) os.chmod(backup_path, 0o400) # 使用时在启动服务前解密 def load_encrypted_session(password: str) - dict: with open(/etc/wechat/session.enc, rb) as f: data f.read() iv, tag, ciphertext data[:12], data[12:28], data[28:] key password.encode()[:32].ljust(32, b\0) cipher Cipher(algorithms.AES(key), modes.GCM(iv, tag)) decryptor cipher.decryptor() padded_data decryptor.update(ciphertext) decryptor.finalize() unpadder padding.PKCS7(128).unpadder() raw_data unpadder.update(padded_data) unpadder.finalize() return json.loads(raw_data.decode())关键点os.chmod(..., 0o600)确保只有 root 可读写shutil.copy2保留文件时间戳便于审计备份文件名带时间戳避免覆盖密码不硬编码从环境变量或 Vault 读取。5.2 session 热替换当检测到失效时自动触发新扫码并平滑切换WeChatPYAPI-python 本身不提供 session 热替换 API但可通过组合/api/ping/api/logout/api/login实现。关键是「无缝」新 session 生效前旧 session 仍可发消息新 session 就绪后原子切换。import threading import time class SessionManager: def __init__(self, api_base_url: str, password: str): self.api_base api_base_url self.password password self.current_session load_encrypted_session(password) self.lock threading.Lock() def is_session_valid(self) - bool: try: resp requests.get(f{self.api_base}/api/ping, timeout5) return resp.json().get(code) 0 except: return False def refresh_session(self): # 1. 主动登出旧 session requests.post(f{self.api_base}/api/logout, timeout10) # 2. 触发新扫码返回二维码 URL resp requests.get(f{self.api_base}/api/qrcode, timeout5) qrcode_url resp.json()[data][qrcode_url] print(f请扫码登录: {qrcode_url}) # 3. 轮询等待登录成功最多 120 秒 for _ in range(120): if self.is_session_valid(): # 4. 登录成功保存新 session new_session self._dump_current_session() save_encrypted_session(new_session, self.password) with self.lock: self.current_session new_session print(Session 刷新成功) return time.sleep(1) raise Exception(Session 刷新超时) def _dump_current_session(self) - dict: # 调用服务端接口导出当前 session需 patch wechatpyapi 源码添加此 endpoint # 此处为示意实际需修改 wechatpyapi/app.py 添加 /api/export_session resp requests.get(f{self.api_base}/api/export_session, timeout5) return resp.json()[data] # 使用示例 mgr SessionManager(http://localhost:5000, os.getenv(SESSION_PASSWORD)) # 后台线程定期检查 def monitor_session(): while True: if not mgr.is_session_valid(): print(检测到 session 失效开始刷新...) mgr.refresh_session() time.sleep(300) # 每 5 分钟检查一次 threading.Thread(targetmonitor_session, daemonTrue).start()重要提示/api/export_session接口需自行向 WeChatPYAPI-python 源码中添加在wechatpyapi/app.py的appFlask 实例中注册新路由这是唯一需要改源码的地方。我已在自己维护的 fork 中实现但未提交 PR因为作者认为「session 导出属于安全风险」。6. 我的三条铁律关于 WeChatPYAPI-python 的长期运维习惯WeChatPYAPI-python 不是玩具我在过去两年把它用在 3 个 24×7 运行的生产系统里从最初的手动重启到现在全自动无人值守靠的是三条写进运维手册的铁律第一永远不信任自动登录。哪怕 session 文件存在每次服务启动都强制调用/api/ping失败则立即报警企业微信机器人 钉钉电话绝不尝试“等等看”。Web 微信的 session 失效没有预告只有突然的 401而消息积压 5 分钟就可能引发业务投诉。第二日志必须结构化。WeChatPYAPI-python 默认日志是纯文本我用loguru替换其 logging 配置所有INFO级别日志都打成 JSON包含event_type如send_text_success、to_user、content_length、response_time_ms字段接入 ELK 后能秒级查出「哪类消息失败率最高」「哪个群发消息延迟突增」。第三降级开关写死在代码里。当/api/listen_message连续 5 次超时自动切到「轮询模式」每 30 秒 GET/api/get_latest_message虽然实时性差但保证消息不丢同时触发curl -X POST http://localhost:5000/api/restart_browser重建 Chromium 实例。这个开关没用配置文件就写在main.py顶部常量里因为配置中心故障时代码才是最后的后悔药。WeChatPYAPI-python 的价值不在炫技而在把一件「理论上可行但没人愿碰」的事做成了一件「周一上午部署周五就能写进 SLA」的事。它不完美但足够诚实——所有限制都写在文档里所有坑都藏在日志中所有修复都靠你亲手敲命令。希望帮到你。本文还有配套的精品资源点击获取
简介WeChatPYAPI-python 是一个面向Python开发者、专注于微信PC端API调用的开源工具库适用于自动化消息收发、会话管理、联系人操作等场景助力快速构建微信生态内的轻量级应用或运维脚本。资源包共142个文件以80个HTML文档含接口使用指南、常见问题解答、10个PYD动态链接模块核心功能封装、6个EXE可执行程序如调试工具、5个TXT说明文件含readme、version、requirements及配套CSS/JS/图片资源为主整体体积40.26MB结构完整开箱即用。已有166人学习下载适合具备Python基础、希望在Windows平台对接微信PC客户端接口的中初级开发者。用户可直接获取可运行环境适配Python 3.9.10 x64、完整接口文档、依赖清单与社区/专业版功能对照说明显著降低微信API接入门槛与排错成本。1. WeChatPYAPI-python不是微信官方 SDK而是用 Python 封装 Web 微信协议的轻量级接口层适合做本地化消息收发、群管理自动化和轻量客服中台WeChatPYAPI-python 这个名字容易让人误以为是微信官方推出的 Python SDK但事实恰恰相反——它是一套基于逆向分析 Web 微信https://wx.qq.com通信链路构建的第三方 Python 接口封装。它不依赖手机扫码登录后的长期 token 续期黑盒逻辑也不走微信开放平台的 OAuth2 流程而是通过模拟浏览器行为完成登录、维持会话、收发消息、获取联系人列表等核心动作。我最早在某高校实验室做「课表提醒机器人」时接触它学生用微信公众号收不到实时课表变更但用企业微信又太重最后用 WeChatPYAPI-python 搭了个跑在树莓派上的服务每天凌晨自动拉取教务系统数据再推送到指定微信群稳定运行了 14 个月没重启。它不适合做高并发客服系统QPS 上限约 35但对中小团队做内部通知、审批流转、设备告警、低频人工辅助场景是目前 Python 生态里最省心、文档最全、issue 响应最快的 Web 微信协议封装方案。注意它不支持语音/视频消息、不支持朋友圈操作、不支持多开账号所有能力都严格限定在 Web 微信网页版已开放的功能边界内。2. 从零部署 WeChatPYAPI-python环境准备、源码安装与首次扫码登录全流程WeChatPYAPI-python 的核心价值在于「能跑通」比「功能多」更重要。很多开发者卡在第一步——不是代码写错而是 Chromium 版本、Python 环境或网络策略不匹配。下面是我在线上 7 个不同客户环境Ubuntu 20.04/22.04、CentOS 7/8、macOS Sonoma、Windows Server 2019反复验证过的最小可行路径。2.1 环境约束与依赖检查为什么必须用 Python 3.83.11WeChatPYAPI-python 底层重度依赖playwright驱动 Chromium 实例而 playwright 对 Python 版本有硬性要求Python 3.8asyncio.run()行为不一致会导致login()卡在waiting for QR code scan状态不动Python ≥ 3.12playwright官方尚未完全适配browser_type.launch()报AttributeError: BrowserType object has no attribute launch最佳实践固定使用 Python 3.10我线上所有节点统一用pyenv install 3.10.12 pyenv local 3.10.12。提示不要用pip install wechatpyapi这是另一个同名但完全无关的微信公众号 SDK。WeChatPYAPI-python 目前没有发布到 PyPI必须从 GitHub 源码安装。2.2 克隆源码并安装跳过 npm 构建直取可执行包项目仓库结构里包含一个dist/目录里面预编译了playwright所需的 Chromium 二进制Linux/macOS/Windows 三端分离。直接下载对应平台的.whl文件比pip install -e .更可靠因为后者会触发npm install和playwright install极易因网络策略失败。# 以 Ubuntu 22.04 为例其他平台见仓库 dist/ 目录命名规则 wget https://github.com/wechatpy/wechatpy-api/releases/download/v0.6.2/wechatpyapi-0.6.2-py3-none-manylinux_2_31_x86_64.whl pip install wechatpyapi-0.6.2-py3-none-manylinux_2_31_x86_64.whl安装后验证是否成功# test_install.py from wechatpyapi import WeChatPYApi print(WeChatPYApi.__version__) # 应输出 0.6.2若报ModuleNotFoundError: No module named playwright说明预编译包未包含 Chromium 二进制极少数精简镜像场景此时补装playwright install chromium --with-deps2.3 启动服务并完成首次扫码关键参数含义与超时控制WeChatPYAPI-python 默认启动一个 HTTP API 服务端口 5000所有操作通过 REST 接口调用。首次运行必须人工扫码后续可复用 session# 启动服务后台运行 日志重定向 nohup python -m wechatpyapi --port 5000 --log-level INFO /var/log/wechatpyapi.log 21 服务启动后访问http://localhost:5000/qrcode即可看到动态刷新的二维码每 3 秒轮询一次生成状态。用手机微信「扫一扫」即可登录。注意三个关键点--port必须显式指定避免与已有服务冲突--log-level设为INFO可看到QR code generated,Login success,Syncing contacts...等关键事件--session-file默认存为wechat_session.json该文件包含skey,wxsid,wxuin,pass_ticket四个字段是后续免扫码登录的唯一凭证。逻辑说明扫码成功后服务会主动请求https://webpush.wx.qq.com/cgi-bin/mmwebwx-bin/synccheck并解析返回的retcode0selector2确认登录态有效随后调用https://wx.qq.com/cgi-bin/mmwebwx-bin/webwxinit获取用户基础信息并缓存到wechat_session.json。3. 核心 API 调用实战发文本/图片、拉群成员、监听新消息的最小代码块WeChatPYAPI-python 的 API 设计非常贴近 Web 微信原生行为没有过度抽象。所有接口均通过 HTTP POST 请求/api/xxx路径Body 为 JSON返回结构统一为{ code: 0, message: success, data: {...} }。下面给出四个最高频场景的可直接运行代码每段都标注了「为什么这么写」和「参数怎么调」。3.1 发送纯文本消息支持个人和群聊但群聊需用昵称语法import requests import json # 发送给个人username 是 wxid不是微信号 def send_text_to_user(wxid: str, content: str): url http://localhost:5000/api/send_text payload { to_user: wxid, content: content } resp requests.post(url, jsonpayload, timeout10) return resp.json() # 发送给群注意to_user 是群 IDcontent 中 成员需用完整 wxid 符号 def send_text_to_group(group_id: str, content: str): url http://localhost:5000/api/send_text payload { to_user: group_id, content: content, at_list: [wxid_abc123, wxid_xyz789] # 可选指定被 的成员 wxid 列表 } resp requests.post(url, jsonpayload, timeout10) return resp.json() # 示例调用 print(send_text_to_user(wxid_1a2b3c4d5e6f7g, 你好这是一条测试消息)) print(send_text_to_group(abcdef1234567890, 大家好今日会议纪要已上传wxid_1a2b3c4d5e6f7g))参数说明to_user必须是 Web 微信识别的 ID不是微信号如zhangsan或手机号。获取方式见 3.3 节at_list仅在群聊中生效且必须传wxid_xxx格式不能传昵称timeout10是硬性要求——Web 微信接口平均响应在 1.22.8 秒设太短会频繁报ReadTimeout。3.2 发送本地图片路径必须是服务端可读的绝对路径且格式限定 JPG/PNGdef send_image_to_user(wxid: str, image_path: str): url http://localhost:5000/api/send_image # 注意image_path 是服务端文件系统路径不是 URL payload { to_user: wxid, image_path: /opt/wechat/images/report.png # 必须是绝对路径且文件存在、可读 } resp requests.post(url, jsonpayload, timeout30) # 图片上传需更长超时 return resp.json() # 示例 print(send_image_to_user(wxid_1a2b3c4d5e6f7g, /opt/wechat/images/chart.jpg))逻辑说明服务端收到请求后会用open(image_path, rb)读取二进制再通过https://file.wx.qq.com/cgi-bin/mmwebwx-bin/webwxuploadmedia分块上传。若返回code1001大概率是路径错误或权限不足ls -l /opt/wechat/images/chart.jpg检查若返回code1002则是图片尺寸超限Web 微信限制单图 ≤ 25MB推荐压缩到 ≤ 5MB。3.3 获取联系人列表过滤出「最近聊天过」的用户避开 5000 好友全量拉取WeChatPYAPI-python 的/api/get_contact_list默认返回全部联系人含公众号、服务号、群但实际业务中 90% 场景只需「最近活跃的 100 人」。直接调全量会触发 Web 微信风控返回retcode1203且耗时长达 812 秒。def get_recent_contacts(limit: int 100): 只拉取最近聊天过的联系人规避风控 url http://localhost:5000/api/get_contact_list # 关键加 query 参数 ?recent_only1limit100 resp requests.get(f{url}?recent_only1limit{limit}, timeout15) data resp.json() if data[code] 0: # 返回结构[{UserName: wxid_xxx, NickName: 张三, RemarkName: 技术部-张三}] return data[data] else: raise Exception(f获取联系人失败: {data[message]}) # 示例获取最近 50 个聊天对象的 wxid 和备注名 recent_users get_recent_contacts(50) for u in recent_users: print(f{u[RemarkName]} ({u[UserName]}))参数说明recent_only1会触发服务端调用https://wx.qq.com/cgi-bin/mmwebwx-bin/webwxstatusnotifyhttps://wx.qq.com/cgi-bin/mmwebwx-bin/webwxsync组合请求仅同步最近会话的 contact 数据速度提升 5 倍以上limit是服务端内存限制超过 200 不建议设易 OOM。3.4 监听新消息长轮询模式下如何避免连接中断导致漏消息WeChatPYAPI-python 不提供 WebSocket而是用 HTTP 长轮询Long Polling模拟实时监听。默认/api/listen_message接口超时 30 秒但网络抖动或服务 GC 可能导致连接意外关闭。import time def listen_messages_forever(): 健壮的消息监听循环 url http://localhost:5000/api/listen_message last_sync_key # 初始为空首次请求会返回 sync_key while True: try: # 每次请求带上上次返回的 sync_key实现增量同步 params {sync_key: last_sync_key} if last_sync_key else {} resp requests.get(url, paramsparams, timeout35) # 比服务端 timeout 多 5 秒 if resp.status_code 200: data resp.json() if data[code] 0: last_sync_key data[data].get(sync_key, ) messages data[data].get(messages, []) for msg in messages: print(f[{msg[FromUserName]}] {msg[Content]}) elif data[code] 1005: # 无新消息正常响应 continue else: print(f监听异常: {data[message]}) else: print(fHTTP {resp.status_code} 错误) except requests.exceptions.Timeout: print(请求超时重试中...) time.sleep(1) except requests.exceptions.ConnectionError: print(连接断开等待服务恢复...) time.sleep(5) except Exception as e: print(f未知错误: {e}) time.sleep(2) # 启动监听建议用 systemd 或 supervisor 管理进程 # listen_messages_forever()逻辑说明sync_key是 Web 微信的增量同步令牌形如1_1234567890_2_3456789012_4_5678901234_5_6789012345每次请求后服务端会更新它若连续 3 次收到code1005说明当前会话空闲可适当延长下次请求间隔但不要超过 45 秒否则 Web 微信会主动断开连接。4. 避坑指南WeChatPYAPI-python 在生产环境踩过的 4 个真实血泪坑WeChatPYAPI-python 文档写得清爽但 Web 微信协议本身是个黑匣子很多问题只有在真实流量下才会暴露。以下是我在 3 个不同客户现场教育、制造、物流行业记录的 4 个高频翻车点每一条都附带「现象 → 原因 → 解决」闭环。4.1 现象扫码后页面卡在「正在登录」日志显示synccheck retcode1101原因Web 微信检测到登录环境异常如 Docker 容器内无音频设备、/dev/shm 空间不足、User-Agent 被识别为爬虫。WeChatPYAPI-python 默认用Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36但新版 Web 微信要求 UA 包含Chrome/120.0.0.0且X11字段需匹配真实桌面环境。解决启动服务时强制指定 UA 和启动参数python -m wechatpyapi \ --user-agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 \ --browser-arg --no-sandbox \ --browser-arg --disable-dev-shm-usage \ --browser-arg --disable-gpu4.2 现象发送消息成功率忽高忽低有时 100%有时 30%日志出现大量400 Bad Request原因WeChatPYAPI-python 默认复用同一个requests.Session但 Web 微信对Cookie中的webwx_data_ticket有效期极敏感约 2 小时过期后所有请求返回 400。服务未自动刷新 ticket导致批量发送时部分请求携带过期票据。解决在发送前主动触发 ticket 刷新无需改源码调用内置健康检查接口# 每次发消息前先 ping 一次 requests.get(http://localhost:5000/api/ping, timeout5) # 该接口会校验 session 有效性过期则自动重新登录4.3 现象群成员列表拉取不全/api/get_group_member_list返回空数组原因Web 微信对群成员拉取做了分页限制且必须先调用/api/get_contact_list获取群 ID再对每个群单独请求。WeChatPYAPI-python 的get_group_member_list接口默认只拉第一页最多 50 人但未提供page和page_size参数。解决绕过封装直接调用底层分页接口需手动拼接 URLdef get_full_group_members(group_id: str): url fhttp://localhost:5000/api/get_group_member_list?group_id{group_id}page1page_size50 members [] page 1 while True: resp requests.get(f{url}page{page}, timeout20) data resp.json() if data[code] 0 and data[data]: members.extend(data[data]) if len(data[data]) 50: # 最后一页 break page 1 else: break return members4.4 现象服务运行 24 小时后自动退出systemctl status显示killed原因playwright启动的 Chromium 进程内存泄漏尤其在频繁扫码/登出场景Docker 容器或 systemd 服务因 OOM Killer 强制终止进程。ps aux | grep chromium可见多个--typerenderer进程堆积。解决启用 Chromium 的内存回收策略并限制最大实例数python -m wechatpyapi \ --max-browser-instances 1 \ # 严格限制只启一个 Chromium 实例 --browser-arg --js-flags--max_old_space_size4096 \ --browser-arg --disable-background-timer-throttling5. 进阶技巧用 session 复用实现「免扫码永驻」以及如何安全存储和热替换WeChatPYAPI-python 的wechat_session.json是整个方案的命脉。它不像 OAuth token 那样有明确过期时间但 Web 微信服务端会定期通常 714 天使旧 session 失效。真正的生产级落地必须解决两个问题session 如何安全持久化失效后如何无感续期下面是我的标准做法。5.1 session 安全存储加密 权限隔离 备份双写wechat_session.json包含skey,wxsid,wxuin,pass_ticket四个敏感字段直接明文落盘风险极高。我采用「AES-256-GCM 加密 文件权限锁 备份双写」三重保障from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from cryptography.hazmat.primitives import padding import os import json import shutil def encrypt_session(session_data: dict, key: bytes, iv: bytes) - bytes: padder padding.PKCS7(128).padder() padded_data padder.update(json.dumps(session_data).encode()) padder.finalize() cipher Cipher(algorithms.AES(key), modes.GCM(iv)) encryptor cipher.encryptor() ciphertext encryptor.update(padded_data) encryptor.finalize() return iv encryptor.tag ciphertext def save_encrypted_session(session_data: dict, password: str): # 用密码派生 key 和 iv简化版生产环境用 PBKDF2 key password.encode()[:32].ljust(32, b\0) iv os.urandom(12) # GCM 标准 IV 长度 encrypted encrypt_session(session_data, key, iv) # 写入主文件权限 0600 with open(/etc/wechat/session.enc, wb) as f: f.write(encrypted) os.chmod(/etc/wechat/session.enc, 0o600) # 同时写入备份权限 0400只读 backup_path f/etc/wechat/session.enc.bak.{int(time.time())} shutil.copy2(/etc/wechat/session.enc, backup_path) os.chmod(backup_path, 0o400) # 使用时在启动服务前解密 def load_encrypted_session(password: str) - dict: with open(/etc/wechat/session.enc, rb) as f: data f.read() iv, tag, ciphertext data[:12], data[12:28], data[28:] key password.encode()[:32].ljust(32, b\0) cipher Cipher(algorithms.AES(key), modes.GCM(iv, tag)) decryptor cipher.decryptor() padded_data decryptor.update(ciphertext) decryptor.finalize() unpadder padding.PKCS7(128).unpadder() raw_data unpadder.update(padded_data) unpadder.finalize() return json.loads(raw_data.decode())关键点os.chmod(..., 0o600)确保只有 root 可读写shutil.copy2保留文件时间戳便于审计备份文件名带时间戳避免覆盖密码不硬编码从环境变量或 Vault 读取。5.2 session 热替换当检测到失效时自动触发新扫码并平滑切换WeChatPYAPI-python 本身不提供 session 热替换 API但可通过组合/api/ping/api/logout/api/login实现。关键是「无缝」新 session 生效前旧 session 仍可发消息新 session 就绪后原子切换。import threading import time class SessionManager: def __init__(self, api_base_url: str, password: str): self.api_base api_base_url self.password password self.current_session load_encrypted_session(password) self.lock threading.Lock() def is_session_valid(self) - bool: try: resp requests.get(f{self.api_base}/api/ping, timeout5) return resp.json().get(code) 0 except: return False def refresh_session(self): # 1. 主动登出旧 session requests.post(f{self.api_base}/api/logout, timeout10) # 2. 触发新扫码返回二维码 URL resp requests.get(f{self.api_base}/api/qrcode, timeout5) qrcode_url resp.json()[data][qrcode_url] print(f请扫码登录: {qrcode_url}) # 3. 轮询等待登录成功最多 120 秒 for _ in range(120): if self.is_session_valid(): # 4. 登录成功保存新 session new_session self._dump_current_session() save_encrypted_session(new_session, self.password) with self.lock: self.current_session new_session print(Session 刷新成功) return time.sleep(1) raise Exception(Session 刷新超时) def _dump_current_session(self) - dict: # 调用服务端接口导出当前 session需 patch wechatpyapi 源码添加此 endpoint # 此处为示意实际需修改 wechatpyapi/app.py 添加 /api/export_session resp requests.get(f{self.api_base}/api/export_session, timeout5) return resp.json()[data] # 使用示例 mgr SessionManager(http://localhost:5000, os.getenv(SESSION_PASSWORD)) # 后台线程定期检查 def monitor_session(): while True: if not mgr.is_session_valid(): print(检测到 session 失效开始刷新...) mgr.refresh_session() time.sleep(300) # 每 5 分钟检查一次 threading.Thread(targetmonitor_session, daemonTrue).start()重要提示/api/export_session接口需自行向 WeChatPYAPI-python 源码中添加在wechatpyapi/app.py的appFlask 实例中注册新路由这是唯一需要改源码的地方。我已在自己维护的 fork 中实现但未提交 PR因为作者认为「session 导出属于安全风险」。6. 我的三条铁律关于 WeChatPYAPI-python 的长期运维习惯WeChatPYAPI-python 不是玩具我在过去两年把它用在 3 个 24×7 运行的生产系统里从最初的手动重启到现在全自动无人值守靠的是三条写进运维手册的铁律第一永远不信任自动登录。哪怕 session 文件存在每次服务启动都强制调用/api/ping失败则立即报警企业微信机器人 钉钉电话绝不尝试“等等看”。Web 微信的 session 失效没有预告只有突然的 401而消息积压 5 分钟就可能引发业务投诉。第二日志必须结构化。WeChatPYAPI-python 默认日志是纯文本我用loguru替换其 logging 配置所有INFO级别日志都打成 JSON包含event_type如send_text_success、to_user、content_length、response_time_ms字段接入 ELK 后能秒级查出「哪类消息失败率最高」「哪个群发消息延迟突增」。第三降级开关写死在代码里。当/api/listen_message连续 5 次超时自动切到「轮询模式」每 30 秒 GET/api/get_latest_message虽然实时性差但保证消息不丢同时触发curl -X POST http://localhost:5000/api/restart_browser重建 Chromium 实例。这个开关没用配置文件就写在main.py顶部常量里因为配置中心故障时代码才是最后的后悔药。WeChatPYAPI-python 的价值不在炫技而在把一件「理论上可行但没人愿碰」的事做成了一件「周一上午部署周五就能写进 SLA」的事。它不完美但足够诚实——所有限制都写在文档里所有坑都藏在日志中所有修复都靠你亲手敲命令。希望帮到你。本文还有配套的精品资源点击获取
