理解 Discord.py 中的用户状态与事件监听
在 discord 机器人开发中，实时了解服务器成员的状态变化（例如，从在线变为离线，或从离线变为在线）是一项常见的需求。discord.py 提供了相应的事件监听器来处理这类情况。
过去，开发者可能会尝试使用 on_presence_update() 事件来捕获用户的状态变更。然而，这个事件在 Discord.py 的现代版本中已被弃用，并且其功能已被更通用的 on_member_update() 事件所取代。on_member_update() 不仅可以处理成员状态的变更，还可以处理昵称、角色等其他成员属性的更新，因此它是监听用户状态变更的推荐方法。
使用 on_member_update() 监听成员更新
on_member_update() 事件监听器会在服务器中的成员信息发生任何改变时被触发。它接收两个 discord.Member 对象作为参数：
- before: 表示成员更新前的状态。
- after: 表示成员更新后的状态。
通过比较这两个对象中的 status 属性，我们就能准确判断用户状态是否发生了变化。discord.Status 是一个枚举类型，包含 online、offline、idle、dnd（请勿打扰）、invisible（隐身）等值。
以下是一个基本的示例，展示如何检测并打印用户状态的变更：
import discord
# 确保您已启用必要的 Intents
# discord.Intents.members 和 discord.Intents.presences 必须启用
intents = discord.Intents.default()
intents.members = True
intents.presences = True
client = discord.Client(intents=intents)
@client.event
async def on_ready():
print(f'Bot 已登录为 {client.user}')
@client.event
async def on_member_update(before: discord.Member, after: discord.Member):
# 检查成员ID是否匹配特定用户（可选）
# 如果你想监听所有成员的状态，可以移除此条件
# my_member_id = YOUR_TARGET_MEMBER_ID # 替换为你要监听的成员ID
# if after.id != my_member_id:
# return
# 检查状态是否真的发生了变化
if before.status != after.status:
print(f'{after.display_name} 的状态从 {before.status} 变更为 {after.status}')
# client.run('YOUR_BOT_TOKEN') # 替换为您的机器人令牌在上面的代码中，我们首先通过 intents.members = True 和 intents.presences = True 启用了必要的 Intents。然后，在 on_member_update 事件中，我们比较了 before.status 和 after.status。如果它们不相等，就意味着用户状态发生了变化，并打印出相关信息。
实现状态变更通知功能
仅仅打印到控制台通常不足以满足需求。更常见的场景是当用户状态变化时，机器人能够向特定的文本频道发送通知消息。
为了实现这一点，我们需要：
- 获取目标文本频道的对象。
- 构建包含状态变更信息的通知消息。
- 使用频道对象的 send() 方法发送消息。
以下代码扩展了之前的示例，实现了在指定频道发送通知：
import discord
intents = discord.Intents.default()
intents.members = True
intents.presences = True
client = discord.Client(intents=intents)
# 配置您的目标频道ID和要监听的成员ID（可选）
GENERAL_CHANNEL_ID = YOUR_GENERAL_CHANNEL_ID # 替换为您的通用频道ID
TARGET_MEMBER_ID = YOUR_TARGET_MEMBER_ID # 替换为要监听的特定成员ID，如果监听所有成员则可以注释或删除
@client.event
async def on_ready():
print(f'Bot 已登录为 {client.user}')
# 尝试获取通用频道对象，以便在需要时发送消息
global general_channel
general_channel = client.get_channel(GENERAL_CHANNEL_ID)
if general_channel:
print(f'已找到通用频道: {general_channel.name}')
else:
print(f'未能找到 ID 为 {GENERAL_CHANNEL_ID} 的通用频道。请检查ID和机器人权限。')
@client.event
async def on_member_update(before: discord.Member, after: discord.Member):
# 仅当 general_channel 对象可用时才尝试发送消息
if not general_channel:
print("警告：通用频道未找到，无法发送状态变更通知。")
return
# 如果定义了 TARGET_MEMBER_ID，则只监听该成员
if TARGET_MEMBER_ID and after.id != TARGET_MEMBER_ID:
return
# 检查状态是否真的发生了变化
if before.status != after.status:
# 构建通知消息
message = (
f'**用户状态变更通知**\n'
f'成员：{after.mention} (`{after.display_name}`)\n'
f'原状态：`{str(before.status).capitalize()}`\n'
f'新状态：`{str(after.status).capitalize()}`'
)
try:
await general_channel.send(message)
print(f'已在 #{general_channel.name} 发送状态变更通知。')
except discord.Forbidden:
print(f'错误：机器人没有在频道 #{general_channel.name} 发送消息的权限。')
except Exception as e:
print(f'发送消息时发生未知错误: {e}')
# client.run('YOUR_BOT_TOKEN') # 替换为您的机器人令牌在上述代码中：
- 我们定义了 GENERAL_CHANNEL_ID 和可选的 TARGET_MEMBER_ID。
- 在 on_ready() 事件中，我们通过 client.get_channel() 获取了目标频道对象，并将其存储在全局变量 general_channel 中，以便在其他事件中使用。
- 在 on_member_update() 中，我们首先检查 general_channel 是否有效。
- 如果 TARGET_MEMBER_ID 被设置，则只会处理该特定成员的状态变更。
- 当检测到状态变更时，我们构造了一条详细的消息，并通过 await general_channel.send(message) 将其发送出去。
- 添加了简单的 try-except 块来处理机器人没有发送消息权限的情况。
关键配置：Discord Intents
Discord.py 引入了 Intents（意图）机制，以允许机器人声明其需要访问哪些事件和数据。对于监听成员状态变化，以下两个 Intents 是必不可少的：
- discord.Intents.members: 允许机器人接收成员加入/离开、成员更新（包括角色和昵称变化）等事件。on_member_update() 事件的触发就依赖于此。
- discord.Intents.presences: 允许机器人接收成员的存在（presence）信息，包括他们的状态（在线、离线等）和活动。没有这个 Intent，before.status 和 after.status 将始终显示为 offline。
在代码中启用 Intents：
如示例所示，您需要在创建 discord.Client 或 commands.Bot 实例时传递 intents 参数：
intents = discord.Intents.default() # 获取默认Intents intents.members = True # 启用成员Intent intents.presences = True # 启用存在Intent client = discord.Client(intents=intents) # 或者对于命令机器人 # bot = commands.Bot(command_prefix='!', intents=intents)
在 Discord 开发者门户中启用 Intents：
仅仅在代码中设置 Intents 是不够的。您还需要在您的机器人应用程序的 Discord 开发者门户中启用这些特权 Intents：
- 访问 Discord 开发者门户。
- 选择您的机器人应用程序。
- 导航到左侧菜单中的 "Bot" 选项卡。
- 在 "Privileged Gateway Intents" 部分，找到 "PRESENCE INTENT" 和 "SERVER MEMBERS INTENT"，并将它们都打开。
如果未在开发者门户中启用这些 Intents，即使代码中设置了，机器人也无法接收到相应的事件数据。
完整代码示例与最佳实践
这是一个整合了所有功能的完整机器人示例，您可以直接使用并根据需要修改：
import discord
import os # 用于从环境变量获取令牌
# --- 配置部分 ---
# 请替换为您的实际频道ID和（可选的）目标成员ID
GENERAL_CHANNEL_ID = 123456789012345678 # 替换为您的通知频道ID
TARGET_MEMBER_ID = None # 替换为要监听的特定成员ID，例如 987654321098765432
# 如果设置为 None，则监听所有成员的状态变更
# --- Intents 设置 ---
intents = discord.Intents.default()
intents.members = True
intents.presences = True
client = discord.Client(intents=intents)
# 全局变量用于存储频道对象
general_channel = None
@client.event
async def on_ready():
"""机器人启动并连接到 Discord 时触发。"""
print(f'Bot 已登录为 {client.user} (ID: {client.user.id})')
print(f'Discord.py 版本: {discord.__version__}')
# 尝试获取通用频道对象
global general_channel
general_channel = client.get_channel(GENERAL_CHANNEL_ID)
if general_channel:
print(f'已成功获取通知频道: #{general_channel.name} (ID: {general_channel.id})')
else:
print(f'警告：未能找到 ID 为 {GENERAL_CHANNEL_ID} 的通知频道。'
'请检查频道ID是否正确，以及机器人是否在该服务器中且有权限访问该频道。')
@client.event
async def on_member_update(before: discord.Member, after: discord.Member):
"""当服务器成员的任何属性更新时触发。"""
# 如果通知频道未准备好，则不发送通知
if not general_channel:
return
# 如果设置了 TARGET_MEMBER_ID，则只处理该成员的更新
if TARGET_MEMBER_ID and after.id != TARGET_MEMBER_ID:
return
# 检查成员状态是否发生了变化
if before.status != after.status:
# 排除 'offline' 到 'invisible' 或 'invisible' 到 'offline' 的变化
# 因为在 Discord 客户端中，'invisible' 通常等同于 'offline'
if (before.status == discord.Status.offline and after.status == discord.Status.invisible) or \
(before.status == discord.Status.invisible and after.status == discord.Status.offline):
return
print(f'检测到状态变更：{after.display_name} 从 {before.status} 变更为 {after.status}')
# 构建通知消息
message = (
f'? **用户状态变更通知** ?\n'
f'**成员:** {after.mention} (`{after.display_name}`)\n'
f'**原状态:** `{str(before.status).capitalize()}`\n'
f'**新状态:** `{str(after.status).capitalize()}`\n'
f'**时间:** <t:{int(discord.utils.utcnow().timestamp())}:F>' # 显示本地化时间
)
try:
await general_channel.send(message)
print(f'成功在 #{general_channel.name} 发送状态变更通知。')
except discord.Forbidden:
print(f'错误：机器人没有在频道 #{general_channel.name} 发送消息的权限。'
'请检查机器人角色权限。')
except discord.HTTPException as e:
print(f'发送消息时发生 HTTP 错误: {e}')
except Exception as e:
print(f'发送消息时发生未知错误: {e}')
# 从环境变量获取机器人令牌，更安全的方式
BOT_TOKEN = os.getenv('DISCORD_BOT_TOKEN')
if BOT_TOKEN:
client.run(BOT_TOKEN)
else:
print("错误：未找到 DISCORD_BOT_TOKEN 环境变量。"
"请确保已设置此环境变量，或者直接在 client.run() 中提供令牌。")
# 如果您选择直接在代码中提供令牌，请替换 'YOUR_BOT_TOKEN_HERE'
# client.run('YOUR_BOT_TOKEN_HERE')注意事项：
-
机器人权限： 确保您的机器人在 GENERAL_CHANNEL_ID 所属的服务器中拥有以下权限：
- 读取消息/查看频道
- 发送消息
- 嵌入链接 (如果您的消息包含链接或使用嵌入消息)
- 使用外部表情符号 (如果您的消息包含自定义表情符号)
- 频道 ID： GENERAL_CHANNEL_ID 必须是您机器人所在服务器的有效文本频道 ID。您可以通过右键点击 Discord 中的频道并选择“复制 ID”来获取。
- 成员 ID： TARGET_MEMBER_ID 是可选的。如果将其设置为 None，机器人将监听所有成员的状态变更。
- 令牌安全： 强烈建议将机器人令牌存储在环境变量中（如示例所示），而不是直接硬编码在代码中，以防止泄露。
- 过滤隐身状态： Discord 客户端通常会将“隐身”状态显示为“离线”。代码中添加了一个条件来避免在 offline 和 invisible 之间切换时发送重复通知。
- 速率限制： Discord API 有速率限制。对于大型服务器，如果状态变更非常频繁，可能会触发速率限制。在大多数情况下，Discord.py 会自动处理，但如果遇到问题，可能需要更精细的逻辑来合并或延迟通知。
- 错误处理： 示例中包含了基本的 try-except 块来捕获发送消息时可能发生的 discord.Forbidden (权限不足) 和 discord.HTTPException (API 错误)。
总结
通过本教程，您应该已经掌握了使用 Discord.py 监听和响应用户状态变更的关键方法。核心在于：
- 使用 on_member_update() 事件监听器。
- 通过比较 before.status 和 after.status 来检测状态变化。
- 配置并启用 discord.Intents.members 和 discord.Intents.presences。
- 确保机器人在 Discord 开发者门户中也启用了相应的特权 Intents。
- 在代码中正确获取目标频道并发送通知消息。
遵循这些步骤和最佳实践，您的 Discord 机器人将能够可靠地监控服务器成员的活动，并根据需要提供有价值的通知。
