企业官网建设流程全解析

• 后端
• 即时通讯

本文以 wxpy 的 Bot 机器人对象文档 为核心脉络，系统讲解微信个人号机器人核心对象Bot的初始化登录、聊天对象获取与搜索、加好友与建群、文件上传与多开控制等完整能力。读完本文，你将掌握Bot的全部初始化参数与回调用法、puid稳定唯一 ID 的启用方式、基于关键词与属性组合的搜索技巧，以及自动接受好友请求、创建群聊等多开实战方案，并可从源码层面理解其底层实现原理。

Bot对象是 wxpy 的入口，可被理解为一个Web 微信客户端。它负责扫码登录、消息收发监听、聊天对象的管理与调度，几乎所有 wxpy 功能都从创建一个Bot实例开始。

from wxpy import * bot = Bot()

关于消息的发送，可参见 chats 文档；关于消息对象与自动处理，可参见 messages 文档。本文聚焦Bot本身的初始化、登录、聊天对象管理与相关操作。

初始化与登录

Bot在初始化时便会执行登录操作，需要手机扫描二维码确认登录（这一点在 wxpy/api/bot.py 的__init__中直接调用itchat的auto_login()实现，扫描的是 Web 微信二维码）。

构造参数详解

Bot.__init__提供多个参数，用于控制缓存、二维码显示方式与生命周期回调，完整定义见 wxpy/api/bot.py：

cache_path：扫码缓存，避免重复登录

• 设为None（默认）时不开启缓存，每次运行都要重新扫码；
• 设为True时，使用默认缓存路径wxpy.pkl（源码中会做cache_path = 'wxpy.pkl'的转换，见 wxpy/api/bot.py）；
• 设为具体路径字符串时，使用该路径保存登录状态。

开启缓存后，短时间内再次运行无需扫码，缓存失效时会重新要求登录。该缓存最终被透传给itchat的auto_login(hotReload=..., statusStorageDir=...)，并由Bot.dump_login_status()落盘。

console_qr：无图形界面的终端二维码

适用于服务器、树莓派等纯命令行环境，登录二维码直接以字符形式打印在终端：

• 传True时在内部被当作整数2（单元格宽度为 2）；
• 传正整数表示二维码单元格宽度；
• 传负数表示以反色显示二维码，适合浅底深字的命令行界面。例如：大部分 Linux 终端可设True或2，而 macOS Terminal 默认白底配色下应设-2。

使用终端二维码需要安装pillow模块（pip3 install pillow）。若运行环境没有图形界面又未指定console_qr，初始化时会因找不到xdg-open而抛出异常，源码中专门对此做了提示（见 wxpy/api/bot.py）。

# 在纯命令行环境登录，终端打印反色二维码 bot = Bot(console_qr=-2, cache_path='bot.pkl')

回调参数

• qr_callback：获得二维码后的回调，接收参数(uuid, status, qrcode)，可用于自定义二维码的处理方式（如推送到其他设备、转存图片等）；
• login_callback：登录成功后的回调；若不指定，wxpy 默认会执行清屏并删除二维码文件；
• logout_callback：登出时的回调。

自动完成的后台工作

初始化除了登录，还会自动完成若干准备工作（见 wxpy/api/bot.py）：

1. 对底层itchat.Core()的会话连接做增强（enhance_connection）；
2. 构建机器人自身聊天对象self与文件传输助手file_helper；
3. 初始化消息队列messages、注册中心registered；
4. 启动消息监听线程（self.start()），并注册进程退出时的清理动作（atexit）。

因此创建Bot()之后即可直接收发消息，无需额外启动步骤。

登出与生命周期

• bot.logout()：登出当前账号（见 wxpy/api/bot.py）；
• bot.alive：只读属性，登录状态为True，否则为False；
• bot.join()：堵塞当前进程，直到消息监听结束（例如机器人被登出时），适合在脚本主流程末尾保持程序运行（见 wxpy/api/bot.py）。

启用 puid：稳定唯一的聊天对象 ID

微信的user_name、wxid等 ID 属性会因隐私策略、会话变化等原因不可获取或发生改变（Chat类文档对此有明确说明，见 wxpy/api/chats/chat.py）。为此 wxpy 提供了puid：wxpy 特有的聊天对象/用户 ID，可始终被获取到，且具有稳定的唯一性，非常适合长期持久化保存。

启用方式为调用Bot.enable_puid()，可指定映射数据的保存/载入路径（见 wxpy/api/bot.py）：

bot = Bot(cache_path=True) # 启用 puid 属性，指定映射数据保存/载入路径 bot.enable_puid('wxpy_puid.pkl') # 指定一个好友 my_friend = bot.friends().search('游否')[0] # 查看他的 puid print(my_friend.puid) # 'edfe8468'

从源码看，enable_puid()会构造一个PuidMap（见 wxpy/utils/puid_map.py），其中维护 4 个双向映射字典：user_name -> puid、wxid -> puid、remark_name -> puid、caption(昵称, 性别, 省份, 城市) -> puid。查询某个聊天对象的puid时，按顺序用其自身的user_name、wxid、remark_name、caption轮询这 4 个字典：

• 命中任一映射则复用已有puid，并把其他属性补充进映射；
• 全部未命中则为该对象生成新的puid（默认取user_name后 8 位）。

映射数据会在退出时自动pickle落盘、下次启动自动载入。注意：puid 映射数据不可跨机器人使用，且调用bot.enable_puid()前访问chat.puid会抛出TypeError提示先启用 puid（见 wxpy/api/chats/chat.py）。相关行为在测试用例TestBot.test_enable_puid中有验证（见 tests/api/test_bot.py）。

获取聊天对象

Bot初始化后，可通过以下属性与方法获取各类聊天对象。所有“合集”对象（好友、群、公众号、全部聊天）均为Chats类型——它是list的子类，支持搜索、统计与加法合并（见 wxpy/api/chats/chats.py）。

机器人自身与文件传输助手

# 机器人账号自身（作为一个聊天对象） myself = bot.self # 文件传输助手 bot.file_helper.send('Hello from wxpy!')

• bot.self：机器人自身，是一个User对象，对应源码中的User(self.core.loginInfo['User'], self)（见 wxpy/api/bot.py）。若需要给自己发送消息，需先在 Web 微信中把自己加为好友，进行一次性的操作：

# 在 Web 微信中把自己加为好友 bot.self.add() bot.self.accept() # 发送消息给自己 bot.self.send('能收到吗？')

• bot.file_helper：文件传输助手，常用于调试时快速给自己传文件或文本，对应源码中的Chat(wrap_user_name('filehelper'), self)。

获取好友 / 群聊 / 公众号 / 全部聊天

• 不传参数时，从本地缓存（itchat 的storageClass）读取，速度快；传update=True时强制向服务器同步最新数据。
• groups()的contact_only=True可只获取保存为联系人的群聊。另外需注意：一些不活跃的群可能无法被获取到，可通过在群内发言或修改群名称来激活（见 wxpy/api/bot.py）。
• bot.chats()内部等价于friends() + groups() + mps()，这一关系在测试TestBot.test_chats中被断言验证（见 tests/api/test_bot.py）。

# 更新并获取所有好友 my_friends = bot.friends(update=True) # 获取全部聊天对象 all_chats = bot.chats()

auto_mark_as_read：自动消除小红点

bot.auto_mark_as_read默认为False；设为True后，机器人收到新消息时将自动调用mark_as_read()消除手机端的新消息小红点提醒。源码中该逻辑位于消息处理流程_process_message内：处理完消息后，若auto_mark_as_read为真、消息非系统消息且发送者不是自己，则对聊天对象执行mark_as_read()（见 wxpy/api/bot.py）。底层通过 Web 微信的webwxstatusnotify接口实现（见 wxpy/api/chats/chat.py）。

搜索聊天对象

Bot与各类合集（Chats、Groups）都提供了search()方法，用于按关键词与属性组合过滤聊天对象。

注意：通过.search()获得的搜索结果均为列表（Chats对象）；若希望找到唯一结果，应使用ensure_one()。

ensure_one()确保列表中仅有一个项并返回该唯一项，否则抛出ValueError（未找到或找到多个时），见 wxpy/utils/tools.py。

搜索好友：关键词 + 属性组合

# 搜索名称包含 '游否' 的深圳男性好友 found = bot.friends().search('游否', sex=MALE, city='深圳') # [<Friend: 游否>] # 确保搜索结果是唯一的，并取出唯一结果 youfou = ensure_one(found) # <Friend: 游否>

其中sex使用常量MALE（值为 1）或FEMALE（值为 2），定义见 wxpy/api/consts.py。

搜索群聊：成员条件

# 搜索名称包含 'wxpy'，且成员中包含 `游否` 的群聊对象 wxpy_groups = bot.groups().search('wxpy', [youfou]) # [<Group: wxpy 交流群 1>, <Group: wxpy 交流群 2>]

在群聊中搜索成员

# 在刚刚找到的第一个群中搜索 group = wxpy_groups[0] # 搜索该群中所有浙江的群友 found = group.search(province='浙江') # [<Member: 浙江群友 1>, <Member: 浙江群友 2>, <Member: 浙江群友 3> ...]

Group.search()实际委托给群成员合集self.members.search()，见 wxpy/api/chats/group.py。

搜索任何类型的聊天对象

# 搜索名称含有 'wxpy' 的任何聊天对象（不包含群内成员） found = bot.search('wxpy') # [<Friend: wxpy 机器人>, <Group: wxpy 交流群 1>, <Group: wxpy 交流群 2>]

Bot.search()内部等价于self.chats().search(keywords, **attributes)（见 wxpy/api/bot.py）。

搜索匹配规则（源码级）

Chats.search()的实现见 wxpy/api/chats/chats.py，其核心是两个匹配函数（见 wxpy/utils/misc.py）：

• 名称匹配match_name：不区分大小写；关键词可为空白分隔的字符串或多个精准关键词组成的列表，要求聊天对象的remark_name（备注名）、display_name（群内显示名）、nick_name（昵称/群名）、wxid中至少有一个属性包含全部关键词；
• 属性匹配match_attributes：传入的键值对（如sex=MALE、province='浙江'、city='深圳'）必须与聊天对象属性或raw数据逐项相等。可用属性键包括sex、province、city、nick_name等。

搜索结果会保留source（来源Bot或Group），测试用例TestBot.test_search验证了搜索返回类型与来源（见 tests/api/test_bot.py）。此外合集还提供了stats()与stats_text()方法，可统计合集内用户按性别、省份、城市等属性的分布情况（见 wxpy/api/chats/chats.py）。

加好友与建群

主动添加好友与公众号

# 添加用户为好友（user 可为用户对象或 user_name） bot.add_friend(user, verify_content='我是 xxx') # 添加/关注公众号 bot.add_mp(mp)

• Bot.add_friend(user, verify_content='')：添加用户为好友，verify_content为验证说明信息。底层调用core.add_friend(status=2, ...)（见 wxpy/api/bot.py）；
• Bot.add_mp(user)：添加/关注公众号，底层调用core.add_friend(status=1, ...)（见 wxpy/api/bot.py）。

接受好友请求

Bot.accept_friend(user, verify_content='')接受用户为好友，成功后返回新的好友对象（Friend）。底层通过core.add_friend(status=3, ...)实现（见 wxpy/api/bot.py）。

自动接受好友请求是常见玩法：注册好友请求类消息（msg_types=FRIENDS），在回调中判断验证文本并调用accept_friend：

# 注册好友请求类消息 @bot.register(msg_types=FRIENDS) # 自动接受验证信息中包含 'wxpy' 的好友请求 def auto_accept_friends(msg): # 判断好友请求中的验证文本 if 'wxpy' in msg.text.lower(): # 接受好友 (msg.card 为该请求的用户对象) new_friend = bot.accept_friend(msg.card) # 或 new_friend = msg.card.accept() # 向新的好友发送消息 new_friend.send('哈哈，我自动接受了你的好友请求')

创建群聊

# users 为用户列表（不含自己，至少 2 位），topic 为群名称 new_group = bot.create_group(users, topic='wxpy 交流群')

Bot.create_group()的实现见 wxpy/api/bot.py：建群前会先通过except_self排除机器人自身，再调用core.create_chatroom()，成功后返回新的Group对象。建群后还可配合群对象的方法继续操作：group.add_members(users, use_invitation=False)拉人入群（use_invitation=True时改为发送邀请）、group.remove_members(members)移出成员、group.rename_group(name)修改群名（见 wxpy/api/chats/group.py）。TestBot.test_create_group对建群、改名等流程有完整测试（见 tests/api/test_bot.py）。

其他常用操作

获取用户详细信息

Bot.user_details(user_or_users, chunk_size=50)可获取单个或批量获取多个用户的详细信息（地区、性别、签名等），但不可用于群聊成员。传入列表时按chunk_size（目前为 50）分批请求（见 wxpy/api/bot.py）：

# 获取单个好友的详细信息 details = bot.user_details(my_friend)

上传文件获取 media_id

Bot.upload_file(path)上传文件并返回media_id，可用于重复发送图片、表情、视频和文件，避免每次发送都重复上传。源码会根据扩展名自动判断上传类型：.bmp/.png/.jpeg/.jpg/.gif按图片上传、.mp4按视频上传，其余按普通文件上传（见 wxpy/api/bot.py）：

# 上传一次，获取 media_id media_id = bot.upload_file('logo.png') # 后续发送给多个好友时直接复用 media_id，省略上传过程 friend_a.send_image('logo.png', media_id=media_id) friend_b.send_image('logo.png', media_id=media_id)

该用法在测试TestBot.test_upload_file中被验证（见 tests/api/test_bot.py）。

控制多个微信（多开）

wxpy 天然支持多开：仅需初始化多个Bot对象，即可同时控制多个微信：

bot1 = Bot(cache_path='bot1.pkl') bot2 = Bot(cache_path='bot2.pkl') # 分别操作两个机器人 bot1.file_helper.send('来自 bot1') bot2.file_helper.send('来自 bot2')

每个Bot实例都独立持有自己的itchat.Core()（见 wxpy/api/bot.py），因此消息监听、聊天对象与缓存互不干扰。多开场景下尤其建议为每个机器人指定独立的cache_path与enable_puid路径，便于各自持久化登录状态与 puid 映射（注意 puid 映射数据不可跨机器人混用）。

总结

Bot对象是 wxpy 一切能力的起点，其核心价值在于：

• 初始化即登录：通过cache_path、console_qr与各类回调参数，覆盖图形环境、纯命令行环境与长期运行场景；
• 对象化聊天管理：self、file_helper、friends()、groups()、mps()、chats()一应俱全，配合Chats合集的搜索与统计能力，可灵活定位任意聊天对象；
• puid 稳定 ID：enable_puid()提供的 puid 解决了原生 ID 不稳定、不可持久化的问题；
• 社交操作闭环：加好友、接受好友请求、关注公众号、建群、拉人、移人、改群名，配合消息注册机制可实现全自动的账号运营；
• 多开支持：多个Bot实例互不干扰，可同时管理多个微信账号。

建议在小号上运行机器人（详见 index 文档中的风险提示），并关注 Web 微信的接口频率限制，避免触发风控。下一阶段可继续阅读 chats 文档 了解各聊天对象的具体方法与群成员管理，以及 messages 文档 掌握消息注册与自动回复机制。

• 后端
• 即时通讯