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.webhookWebhook、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 [ PyNaCl1.6.0,1.7, davey0.1.0 ]在Linux 环境下安装语音支持前还需要先安装系统级依赖libffi部分发行版叫libffi-devellibnaclpython3-devPython 头文件。对于 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-env2. 激活虚拟环境# Linux/macOS source bot-env/bin/activate # Windows bot-env\Scripts\activate.bat3. 在虚拟环境内正常使用 pip 安装依赖pip install -U discord.py安装完成后bot-env中即拥有独立的 discord.py 环境。注意官方文档特别提示用py -3执行的脚本会忽略当前已激活的虚拟环境因为-3指定的是全局作用域。因此在激活 venv 后请直接使用pip或python命令而不要混用py -3。核心概念事件Eventsdiscord.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_contentintentimport discord class MyClient(discord.Client): async def on_ready(self): print(fLogged on as {self.user}!) async def on_message(self, message): print(fMessage from {message.author}: {message.content}) intents discord.Intents.default() intents.message_content True client MyClient(intentsintents) client.run(my token goes here)代码中三个关键点继承discord.Client并覆写事件方法on_ready在客户端完成数据准备后触发此时self.user已可用on_message在每条消息到达时触发。Intents意图声明discord.Intents.default()生成默认意图再手动开启message_content——否则官方文档与源码均指出message.content在大部分场景下只会返回空字符串。client.run(token)阻塞式启动方法负责初始化事件循环、登录并连接 Discord 网关。关于on_ready的注意事项查看 docs/api.rst 中对on_ready()的说明有两个重要细节on_ready不保证是第一个被调用的事件它不保证只被调用一次——因为库实现了断线重连逻辑当 RESUME 请求失败时会再次触发on_ready。所以不要在on_ready里做只应执行一次的初始化逻辑如定时任务注册。理解 Intents 与message_contentIntents类定义在 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 中定义的阻塞方法它是loginconnect两个协程的快捷封装。要点包括必须是最后一个调用阻塞直到退出之后注册的事件不会生效默认自动重连reconnectTrue会为库自动配置日志默认logging.StreamHandler默认级别logging.INFO高级用户可通过log_handlerNone关闭或自定义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, intentsintents) 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/21 2:41:00 · 阅读 1.2k discord.py 入门指南：安装、虚拟环境与事件驱动的第一个 Discord Bot
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.webhookWebhook、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 [ PyNaCl1.6.0,1.7, davey0.1.0 ]在Linux 环境下安装语音支持前还需要先安装系统级依赖libffi部分发行版叫libffi-devellibnaclpython3-devPython 头文件。对于 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-env2. 激活虚拟环境# Linux/macOS source bot-env/bin/activate # Windows bot-env\Scripts\activate.bat3. 在虚拟环境内正常使用 pip 安装依赖pip install -U discord.py安装完成后bot-env中即拥有独立的 discord.py 环境。注意官方文档特别提示用py -3执行的脚本会忽略当前已激活的虚拟环境因为-3指定的是全局作用域。因此在激活 venv 后请直接使用pip或python命令而不要混用py -3。核心概念事件Eventsdiscord.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_contentintentimport discord class MyClient(discord.Client): async def on_ready(self): print(fLogged on as {self.user}!) async def on_message(self, message): print(fMessage from {message.author}: {message.content}) intents discord.Intents.default() intents.message_content True client MyClient(intentsintents) client.run(my token goes here)代码中三个关键点继承discord.Client并覆写事件方法on_ready在客户端完成数据准备后触发此时self.user已可用on_message在每条消息到达时触发。Intents意图声明discord.Intents.default()生成默认意图再手动开启message_content——否则官方文档与源码均指出message.content在大部分场景下只会返回空字符串。client.run(token)阻塞式启动方法负责初始化事件循环、登录并连接 Discord 网关。关于on_ready的注意事项查看 docs/api.rst 中对on_ready()的说明有两个重要细节on_ready不保证是第一个被调用的事件它不保证只被调用一次——因为库实现了断线重连逻辑当 RESUME 请求失败时会再次触发on_ready。所以不要在on_ready里做只应执行一次的初始化逻辑如定时任务注册。理解 Intents 与message_contentIntents类定义在 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 中定义的阻塞方法它是loginconnect两个协程的快捷封装。要点包括必须是最后一个调用阻塞直到退出之后注册的事件不会生效默认自动重连reconnectTrue会为库自动配置日志默认logging.StreamHandler默认级别logging.INFO高级用户可通过log_handlerNone关闭或自定义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, intentsintents) 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考