企业官网建设流程全解析

discord.py 入门指南：安装、虚拟环境与事件驱动的第一个 Discord Bot

【免费下载链接】discord.pyAn API wrapper for Discord written in Python.项目地址: https://gitcode.com/gh_mirrors/di/discord.py

本篇指南以 discord.py 官方文档 docs/intro.rst 为核心，系统讲解这个 Python Discord API 封装库的安装流程、虚拟环境配置方式，以及围绕"事件"构建的第一个机器人示例。读完本文，你将掌握从零开始安装 discord.py（含语音支持）、搭建隔离的 Python 虚拟环境、理解 Intents（意图）机制，并亲手运行一个能响应消息事件的 Bot。

discord.py 是什么

discord.py 是一个用 Python 编写的 Discord API 封装库（wrapper），目标是帮助开发者快速创建使用 Discord API 的应用程序。仓库的 README.rst 将其定位为 "A modern, easy to use, feature-rich, and async ready API wrapper for Discord written in Python"，其核心特性包括：

• 使用async/await的现代 Pythonic API；
• 内置完善的速率限制（rate limit）处理；
• 在速度和内存占用上做了优化。

从 pyproject.toml 可以看到，该库的包结构覆盖了discord核心模块、discord.types（类型定义）、discord.ui（交互组件）、discord.webhook（Webhook）、discord.app_commands（斜杠命令）、discord.ext.commands（命令扩展）与discord.ext.tasks（后台任务）等，是一个功能完整的 API 封装。

环境要求（Prerequisites）

按照 docs/intro.rst 的说明，discord.py 要求Python 3.8 或更高版本：

• 不支持 Python 3.7 及更早版本；
• 不支持 Python 2.7 及更低版本。

这一要求同样体现在 pyproject.toml 的requires-python = ">=3.8"声明中，并且 README.rst 也明确写着 "Python 3.8 or higher is required"。因此，动手前请先确认本机 Python 版本：python3 --version。

安装 discord.py

基础安装（PyPI）

最简单的方式是从 PyPI 直接安装。在 Linux/macOS 上执行：

python3 -m pip install -U discord.py

在 Windows 上，官方文档建议使用py启动器命令：

py -3 -m pip install -U discord.py

注意：-U表示升级到最新版本；python3 -m pip（而不是裸pip）能确保 pip 与当前 Python 解释器对应。

安装语音支持（voice extra）

如果你需要让 Bot 播放音频等语音功能，应将discord.py替换为discord.py[voice]：

# Linux/macOS python3 -m pip install -U "discord.py[voice]" # Windows py -3 -m pip install -U discord.py[voice]

语音支持依赖 PyNaCl 等库。查看 pyproject.toml 中[project.optional-dependencies]的voice段可以看到实际声明：

voice = [ "PyNaCl>=1.6.0,<1.7", "davey>=0.1.0" ]

在Linux 环境下，安装语音支持前还需要先安装系统级依赖：

• libffi（部分发行版叫libffi-devel）；
• libnacl；
• python3-dev（Python 头文件）。

对于 Debian 系系统（如 Ubuntu），一条命令即可安装齐全：

apt install libffi-dev libnacl-dev python3-dev

官方文档特别提醒：记得检查你的权限——在多数发行版上apt install需要sudo或以 root 身份执行。

使用虚拟环境（Virtual Environments）

为什么需要虚拟环境？官方文档给出的理由很实际：

• 避免库污染系统级 Python 安装；
• 可以在不同项目中使用不同版本的库；
• 可能没有系统级安装权限（尤其 Linux 上系统 Python 常被外部管理，限制用户装包）。

Python 自 3.3 起在标准库中内置了venv模块，用法如下。

1. 进入项目工作目录并创建虚拟环境：

cd your-bot-source python3 -m venv bot-env

2. 激活虚拟环境：

# Linux/macOS source bot-env/bin/activate # Windows bot-env\Scripts\activate.bat

3. 在虚拟环境内正常使用 pip 安装依赖：

pip install -U discord.py

安装完成后，bot-env中即拥有独立的 discord.py 环境。

注意：官方文档特别提示，用py -3执行的脚本会忽略当前已激活的虚拟环境，因为-3指定的是全局作用域。因此在激活 venv 后，请直接使用pip或python命令，而不要混用py -3。

核心概念：事件（Events）

discord.py 的一切围绕事件（events）展开。官方文档的定义是：事件是你去监听（listen）然后响应（respond）的东西。例如当一条消息发生时，你会收到一个对应的事件，然后可以针对它做出反应。

这一设计在源码中有清晰体现：discord.Client通过覆写on_*系列方法（如on_ready、on_message）来接收网关事件，对应的完整事件列表定义在 docs/api.rst 的 Gateway 章节（如on_ready()、on_message(message)等）。事件驱动的开发模式让你不必关心底层的 WebSocket 连接细节，只需要关心"发生了什么、我要怎么回应"。

事件示例：监听消息

以下是 docs/intro.rst 给出的最小示例（需要开启message_contentintent）：

import discord class MyClient(discord.Client): async def on_ready(self): print(f'Logged on as {self.user}!') async def on_message(self, message): print(f'Message from {message.author}: {message.content}') intents = discord.Intents.default() intents.message_content = True client = MyClient(intents=intents) client.run('my token goes here')

代码中三个关键点：

1. 继承discord.Client并覆写事件方法：on_ready在客户端完成数据准备后触发（此时self.user已可用）；on_message在每条消息到达时触发。
2. Intents（意图）声明：discord.Intents.default()生成默认意图，再手动开启message_content——否则官方文档与源码均指出，message.content在大部分场景下只会返回空字符串。
3. client.run(token)：阻塞式启动方法，负责初始化事件循环、登录并连接 Discord 网关。

关于on_ready的注意事项

查看 docs/api.rst 中对on_ready()的说明，有两个重要细节：

• on_ready不保证是第一个被调用的事件；
• 它不保证只被调用一次——因为库实现了断线重连逻辑，当 RESUME 请求失败时会再次触发on_ready。

所以不要在on_ready里做"只应执行一次"的初始化逻辑（如定时任务注册）。

理解 Intents 与message_content

Intents类定义在 discord/flags.py（注意它并不在discord/intents.py，而是作为 flag 体系的一部分）。其关键工厂方法：

• Intents.all()：开启全部意图；
• Intents.none()：全部关闭；
• Intents.default()：除presences、members、message_content之外全部开启（源码实现即self.presences = False; self.members = False; self.message_content = False）。

message_content意图控制消息内容、附件、嵌入与组件是否在消息中可用。源码 discord/flags.py 明确指出，以下三类消息即使不开启该意图也能拿到内容：客户端自己发送的消息、私聊（DM）消息、@提及了客户端的消息；除此之外的消息，message.content将恒为空字符串，message.attachments等同样受影响（见 discord/message.py 中多处 "IfIntents.message_contentis not enabled this will always be..." 的说明）。

另外，源码还提示：message_content需要在 Discord 开发者门户中显式申请，且超过 100 个服务器的 Bot 需要向 Discord 申请验证。

run()做了什么

client.run()是 discord/client.py 中定义的阻塞方法，它是login+connect两个协程的快捷封装。要点包括：

• 必须是最后一个调用（阻塞直到退出），之后注册的事件不会生效；
• 默认自动重连（reconnect=True）；
• 会为库自动配置日志（默认logging.StreamHandler，默认级别logging.INFO），高级用户可通过log_handler=None关闭，或自定义log_formatter、log_level；
• 想要更精细控制事件循环时，可改用start()或手动await login()+connect()。

进阶：结合discord.ext.commands的 Bot 示例

入门示例使用的是底层discord.Client；若想使用前缀命令体系，可参照 README.rst 与仓库 examples/basic_bot.py 中演示的discord.ext.commands扩展：

import discord from discord.ext import commands intents = discord.Intents.default() intents.message_content = True bot = commands.Bot(command_prefix='>', intents=intents) @bot.command() async def ping(ctx): await ctx.send('pong') bot.run('token')

更完整的 examples/basic_bot.py 还展示了参数类型转换（如add(ctx, left: int, right: int)）、子命令组（cool/cool bot）等实用写法，可以作为入门后继续学习的范例。此外，仓库还提供 examples/advanced_startup.py、examples/background_task.py 等更多示例。

从源码安装开发版（可选）

如需体验最新开发功能，可按 README.rst 从本仓库源码安装：

git clone https://github.com/Rapptz/discord.py cd discord.py python3 -m pip install -U .[voice]

（若仅需基础功能，可将.[voice]换成.。）

常见问题小结

• 消息内容总是空的？检查是否开启intents.message_content = True，并在开发者门户中申请 Message Content Intent。
• on_ready触发多次？这是正常的——库的重连机制可能导致其重复触发，不要在事件里做一次性初始化。
• Windows 上激活了 venv 却仍装到全局？避免使用py -3，改用pip直接操作。
• Linux 装语音报错？先安装libffi-dev libnacl-dev python3-dev，再执行pip install -U "discord.py[voice]"。
• client.run()之后的代码不执行？run()是阻塞调用，务必放在脚本最后。

【免费下载链接】discord.pyAn API wrapper for Discord written in Python.项目地址: https://gitcode.com/gh_mirrors/di/discord.py