前阵子有人问我Discord机器人到底难不难做我说你把它想成是在聊天室里养了一只电子宠物就行。它平时挂在服务器里你它或者打一条命令它就开始干活。用Python实现这件事核心逻辑其实很朴素写一个常驻运行的程序连上Discord的消息网关收到事件就回响应的内容。这篇文章我会把整条链路从原理到部署拆开讲适合刚入门Python、想在Discord服务器里加点自动化功能的朋友也特别适合那种已经照着教程把机器人跑起来了、但一换场景就抓瞎的读者。放心不是那种复制一段代码就完事的教程我会把每一步为什么这么做也讲明白。1. 先把运转原理讲透机器人不是“跑在云端”而是一个常驻脚本很多初学者对“机器人”三个字有误解以为它是个云服务或者某种托管平台上的东西。其实Discord机器人本质上就是你本地或服务器上运行的一个Python脚本它做的事情只有两件保持长连接响应事件。1.1 开发者后台的“应用”到底是什么Discord机器人不是从代码里变出来的你要先去discord.com/developers/applications这个后台创建一个Application。这个“应用”相当于机器人的身份档案Bot按钮则是在这个档案里添加一个机器人角色。创建完之后系统会给你一串Token这一串字符串就是机器人身份的钥匙。这里有个关键认知Token不等同于你的Discord账号密码它是机器人的独立凭证。你的账号像一个员工可以在多个服务器里手动操作机器人像一台自助终端机拿着Token就能以机器人的名义收发消息。所以Token一旦泄露别人就可以完全操控你的机器人在你管理的服务器里发言、踢人权限取决于你给机器人分配了什么。这一点后面专门说。创建应用的步骤非常简单登录开发者后台点New Application起一个名字然后左侧菜单找到Bot点Add Bot。到这一步你已经拥有了一个“机器人户口”但还缺一个关键的东西——邀请它进入服务器。1.2 事件驱动手机挂机等电话理解事件驱动模型机器人代码就通了一半。Discord机器人不是每隔几秒去服务器上问“有没有新消息”那样既慢又浪费资源。它用的是一种叫WebSocket的长连接你的脚本主动连上Discord的网关Gateway然后挂着不动一旦服务器里有动静有人发消息、有人加入频道、有人戳了一下机器人Discord就把这个事件推送到你的连接上。你可以把这种模式理解成手机挂机等电话。手机屏幕亮着但你不需要一直拨号来电的时候自然会响你只需要在铃声响起时决定接不接、怎么说。代码里的on_message、on_ready这些函数就是你的“来电处理逻辑”。你预先告诉机器人当这个事件发生时执行这段函数。这里有个配套概念叫Intents意图可以理解成“订阅清单”。Discord默认不会把所有事件都推给你你必须先声明自己需要哪些类型的数据。只做文本聊天就声明message_content意图需要看服务器成员列表就声明members意图。声明得越精确推送的数据越少机器人跑起来越省资源。1.3 为什么选discord.py社区里Python的Discord库有好几个我最早用的是discord.py现在项目里依然用它。理由很实际文档量大踩坑帖多遇到报错基本能搜到答案。而且2.0版本之后原生支持了斜杠命令Slash Command不需要再做额外的命令解析。相比之下discord.js是Node生态的老大如果你熟悉JavaScript选它也没毛病。Pycord和disnake是discord.py停更期间社区分叉出去的版本功能更激进但生态和教程数量还是不如discord.py本身。对新手来说我的建议是别纠结直接用discord.py。等你看懂了它的设计模式换别的库也就是一两天的功夫结构都是相通的。2. 开发环境与Token安全这两块配置做不好后面全白搭代码可以慢慢写但环境配置这一步如果偷懒后面会反复被坑。尤其是Token的处理方式几乎是每个新手都交过学费的地方。2.1 Python版本与虚拟环境依赖隔离discord.py 2.x要求Python 3.8及以上我建议直接用3.10或者3.11新语法支持好各种库的兼容性也稳。Windows下直接去官方网站下载安装包记得安装时勾选“Add Python to PATH”选项这一步漏了后面在命令行敲python会提示找不到命令。依赖环境的部分强烈建议用虚拟环境命令很简单python -m venv venv # Windows激活 venv\Scripts\activate # Linux/macOS激活 source venv/bin/activate激活后命令行前面会出现一个(venv)前缀这时候再安装依赖所有包都会装进这个项目的独立目录不影响系统里其他Python项目。不用虚拟环境的后果通常是某天A项目升级了某个库B项目直接跑不起来排查半天发现是依赖打架。激活之后安装依赖pip install -U discord.py python-dotenvpython-dotenv是用来读取.env配置文件的下面马上说它。2.2 Token安全环境变量与.env文件的正确姿势直接把Token写在.py文件里是新手最容易犯的错我自己也干过。写着写着想把它传到GitHub或者把代码截图发群里Token就泄了。机器人一旦被识别出是“被盗状态”对方可以顺着你的机器人进到所有它所在的服务器后果比想象中严重。正确做法是建一个.env文件放在项目根目录内容这样写DISCORD_BOT_TOKEN你的一长串Token然后在代码里用两行读取import os from dotenv import load_dotenv load_dotenv() TOKEN os.getenv(DISCORD_BOT_TOKEN)同时记得在项目里建一个.gitignore文件把.env写进去.env venv/这样就算哪天你忘了git status也不会显示.env的变化相当于多了一道保险。实测下来这一套流程是最省心的Token和代码彻底分离换个Token只要改一行配置文件不需要动代码。2.3 邀请机器人进入服务器这一步很多人会忘光有Token还不够机器人必须通过OAuth2邀请链接进入你的服务器否则它就算上线了也是个“无家可归”的幽灵账号。去开发者后台的OAuth2 - URL Generator页面勾选bot权限范围然后在下方的Bot Permissions里根据自己的需求勾权限。我一般会勾这几个Send Messages、Read Messages/View Channels、Read Message History、Embed Links也就是能发言、能看频道、能发嵌入消息这是最基础的文本回复能力。如果后面要做更多功能比如管理成员、管理消息再回去重新生成链接这些权限随时可以改。有个细节要注意邀请链接是一次性生成的生成之后URL包含一串特殊的client_id和scope参数任何人拿到这个链接都可以把机器人邀请到他有管理权限的服务器。所以这个链接也别乱发只给自己的服务器用就行。3. 手搓第一个能回话的机器人从事件监听到命令分发环境配好了原理也理解了现在来写代码。这里我给的是能跑的最小完整示例每一行都有用别急着删。3.1 最小可运行代码逐行拆解import discord from discord.ext import commands import os from dotenv import load_dotenv load_dotenv() TOKEN os.getenv(DISCORD_BOT_TOKEN) intents discord.Intents.default() intents.message_content True bot commands.Bot(command_prefix!, intentsintents) bot.event async def on_ready(): print(f机器人已上线{bot.user}) bot.event async def on_message(message): if message.author bot.user: return if message.content.startswith(!hello): await message.channel.send(f你好{message.author.display_name}) await bot.process_commands(message) bot.run(TOKEN)这段代码里有三个地方是新手最容易踩的。第一intents.message_content True。这一行表示你声明要接收消息内容如果漏掉机器人完全收不到别人发了什么。第二if message.author bot.user这是防止机器人回复自己导致死循环。比如你让机器人回复“你好”如果它回复一次那条消息本身也会触发on_message如果没有这个判断它会对着自己的回复一直回下去。第三await bot.process_commands(message)这一行非常关键它负责把消息继续交给命令系统处理。如果你只写了on_message事件、没写process_commands那你下面注册的所有bot.command()命令都不会生效因为它们被事件函数拦截了。这是个极其隐蔽的坑代码不报错就是没反应。3.2 用命令系统代替手写前缀判断上面那段用startswith手写判断消息内容适合演示原理但实际开发中更推荐用命令系统。写法是这样的bot.command() async def ping(ctx): await ctx.send(pong)你在聊天框里输入!ping机器人就会回复pong。这里ctx叫上下文对象它携带了这条命令相关的所有信息谁发的、在哪个频道、在哪个服务器、消息内容是什么。命令函数里所有操作基本都是通过ctx来做的。命令系统还可以自动解析参数比如bot.command() async def echo(ctx, *, content): await ctx.send(content)*表示把用户输入的所有剩余部分当作一个字符串参数。输入!echo 大家好机器人会说“大家好”。如果想带参数类型还可以这样写bot.command() async def roll(ctx, dice: str): try: count, sides map(int, dice.split(d)) except ValueError: await ctx.send(格式不对应该像 2d6 这样) return import random results [random.randint(1, sides) for _ in range(count)] await ctx.send( .join(str(r) for r in results) f {sum(results)})输入!roll 2d6就能模拟掷两个六面骰子。命令系统帮你省掉了手动解析前缀和参数的活代码可读性也好很多这是我实际用下来体会最深的一点。3.3 功能多起来之后用Cogs做模块化命令写到二三十个的时候所有函数堆在main.py里会让文件变得非常庞大。discord.py提供了Cogs机制可以把一组相关的命令打包成一个类单独放在一个文件里。我常用的项目结构是这样的mybot/ ├── main.py ├── cogs/ │ ├── fun.py │ └── admin.pycogs/fun.py大概是这个模板import discord from discord.ext import commands class Fun(commands.Cog): def __init__(self, bot): self.bot bot commands.command() async def ping(self, ctx): await ctx.send(pong) async def setup(bot): await bot.add_cog(Fun(bot))然后在main.py里加载import asyncio from discord.ext import commands bot commands.Bot(command_prefix!, intentsintents) async def load_extensions(): await bot.load_extension(cogs.fun) asyncio.run(load_extensions()) bot.run(TOKEN)这里有个版本陷阱很多老教程里的setup(bot)是不带async的bot.add_cog也不是await调用。但discord.py 2.x开始setup函数必须是异步的不写async会直接报错。我见过太多人因为网上教程版本太老卡在这一步特地说一声。4. 能跑不算完连不上、不回话、一关终端就掉线的实际排查过程机器人跑通只是开始真正的问题是上线之后的各种“玄学”。这一节我把实际排查的顺序完整写出来你照着走就行。4.1 “连不上网关”的排查链路从日志到出站网络症状运行main.py终端里滚动几行日志然后报错常见的有两类aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host discord.com:443 ssl:None或者discord.gateway - ERROR - WebSocket closed with code 1006第一类意思是TCP连接都没建立成功第二类意思是连接建立之后被重置了。排查顺序分三步第一步确认Token是否有效。如果日志里出现401 Unauthorized那就是Token填错了或者Token被重置过。检查.env里的字符串有没有复制完整尤其是最后有没有多余的空格。第二步测试本机到Discord网关的网络连通性。用下面这条命令python -c import socket; ssocket.create_connection((gateway.discord.gg, 443), timeout5); print(connect ok); s.close()如果这条命令在5秒内输出了connect ok说明网络路径是通的问题大概率出在代码或者库版本。如果一直卡住直到超时那就是当前网络环境到Discord的TCP连接被拦截了。这种时候先换个网络环境做对比试验比如手机开热点让电脑连上再测一次如果热点能通、原网络不通基本可以确认是网络策略问题。第三步检查DNS解析和防火墙。用nslookup discord.com看一下域名解析是否正常解析不出来就换公共DNS再试。服务器上如果开了防火墙检查一下出站443端口有没有被规则拦掉。排查完之后还可以给bot.run套一个自动重试的逻辑防止偶发的网络抖动把进程打到退出import time while True: try: bot.run(TOKEN) except KeyboardInterrupt: break except Exception as e: print(f连接异常10秒后重试{e}) time.sleep(10)这里面的KeyboardInterrupt捕获是必须的不然每次按CtrlC退出时又会触发重连逻辑彻底退出都退不掉。4.2 机器人上线了但完全不回话三级权限检查法on_ready正常打印了说明长连接没问题但发消息没人理。这是第二个高频问题而且原因不止一种我总结了一个三级检查法。第一级检查代码里的Intent。确认intents.message_content True这一行存在并且Bot是用intentsintents创建的。少这一行机器人听不见任何消息内容命令自然不触发。第二级检查开发者后台。打开Applications - 你的应用 - Bot页面找到Privileged Gateway Intents一栏确认Message Content Intent开关是打开的。这里有个容易迷惑的点开发者后台和代码里需要同时开启只开一边都不行。第三级检查邀请链接的权限。如果邀请时没有勾选Read Messages/View Channels和Send Messages机器人进服务器后就是个“睁眼瞎”。另外还有一个很阴间的坑在on_message事件里用了同步阻塞操作比如time.sleep(3)。这会卡住整个事件循环导致机器人看起来像假死收到的消息也不处理。正确做法是await asyncio.sleep(3)。症状可能原因验证方法不打印任何消息内容Intent未开启代码里和后台双击确认命令有反应但事件函数不执行漏了process_commands检查事件函数末尾on_ready正常但发消息无反应邀请权限缺失重新生成邀请链接并授权偶发性不理人事件循环被阻塞检查有没有同步sleep或阻塞I/O4.3 一关终端就下线常驻运行的两种方案本地开发可以开着终端跑但机器人要24小时在线必须搞部署。Linux服务器上最稳定的方案是systemd。在/etc/systemd/system/mybot.service里写这样一段[Unit] DescriptionDiscord Bot Afternetwork.target [Service] WorkingDirectory/home/user/mybot ExecStart/home/user/mybot/venv/bin/python main.py Restartalways RestartSec10 [Install] WantedBymulti-user.target注意ExecStart用的是虚拟环境里Python的绝对路径而不是系统全局的python否则会找不到discord.py。Restartalways表示进程无论什么原因退出10秒后都会被自动拉起来这是防止掉线的核心配置。写完执行sudo systemctl daemon-reload sudo systemctl enable --now mybot如果你在Windows服务器或自己的电脑上跑可以用任务计划程序或者用nssm把python main.py包装成Windows服务效果类似。小内存的云主机不想装太多东西用screen -dmS mybot python main.py临时顶着也行但崩溃了不会自动重启只适合过渡期。4.4 Token泄露或误提交急救流程如果你怀疑Token已经泄露比如不小心把.env提交到了GitHub上第一件事不是删文件而是立刻去开发者后台点Reset Token。这一步会让旧Token立即失效攻击者手里的凭证瞬间变废纸。然后重新复制新Token更新.env文件。至于已经提交到GitHub的历史记录就算删除文件也还能从git历史里翻出来所以Token重置是唯一有效的补救手段。以后养成习惯.env永远不进版本控制.gitignore里必须写上。还有一点邀请链接泄露的处理逻辑类似去后台重新生成一个新的邀请链接旧链接会失效。5. 从玩具到工具几个我实测过的扩展方向机器人能回“你好”只是第一步让它干点正事才有意思。这里分享三个我实际用过的扩展方向都是能直接抄的。5.1 对接外部API让机器人成为信息入口机器人最实用的场景是替你查东西。比如让它去请求一个公开API返回随机狗狗图片。关键在于必须用aiohttp而不是requests因为requests是同步阻塞的在异步事件循环里调用它会卡住整个机器人其他用户发消息全部延迟。import aiohttp import discord from discord.ext import commands bot.command() async def dog(ctx): async with aiohttp.ClientSession() as session: async with session.get(https://dog.ceo/api/breeds/image/random) as resp: data await resp.json() await ctx.send(data[message])同样的模式可以扩展到查天气、查汇率、查词典、查服务器状态。aiohttp的ClientSession不要每次命令都创建销毁可以在Bot类里维护一个全局会话性能会好不少。不过代码复杂度也上去了小规模项目先用每次创建的方式等流量大了再优化不迟。5.2 定时推送让机器人主动说话机器人不只能被动应答还能定时主动发消息。比如每天早上9点往指定频道推送天气。这个功能用apscheduler库实现pip install apschedulerfrom apscheduler.schedulers.asyncio import AsyncIOScheduler from datetime import datetime async def send_daily(): channel bot.get_channel(你的频道ID) if channel: await channel.send(f早安现在是 {datetime.now():%H:%M}) scheduler AsyncIOScheduler() scheduler.add_job(send_daily, cron, hour9, minute0) scheduler.start()get_channel需要频道ID在Discord里开启开发者模式后右键频道可以复制ID。这个定时任务在实际部署中要注意时区问题apscheduler默认用服务器本地时区如果你的云主机是UTC时区定时9点会在北京时间的下午5点触发。建议在配置里显式指定时区比如add_job(..., timezoneAsia/Shanghai)。5.3 我踩过几次坑之后总结出的几条经验第一权限永远最小化。机器人只给必须的权限坚决不给Administrator。原因很朴素如果Token泄露Administrator权限等于把整个服务器拱手送人。第二日志要提前加上。项目一开始就配好logging排查问题效率翻倍否则报错信息一闪而过你只能盲猜。import logging logging.basicConfig(levellogging.INFO)第三看到老教程要留个心眼。网上大量discord.py教程还停留在1.x年代setup函数写同步、bot.add_cog不写await这些在2.x版本里全会报错。对照文档时先确认版本号别照搬。第四不要让机器人回复包含自己身份信息的任何内容尤其是Token哪怕是在私聊场景。有些钓鱼软件会诱导机器人把os.getenv(DISCORD_BOT_TOKEN)的结果发出来这类代码不要写。最后再分享一个小习惯我把每个机器人的Token都放到独立的环境变量配置文件里然后准备一个通用的启动脚本不管是本地调试还是丢到服务器上都是一行命令启动。这个自动化流程省了我大量重复劳动。你先从最小的代码跑起来后面自然会慢慢长出适合自己项目的那套模式。
