Windows PowerShell

venv\Scripts\Activate.ps1

Windows 命令提示符

venv\Scripts\activate.bat

Linux 或 macOS

source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install discord.py python-dotenv
python -m pip freeze > requirements.txt
使用 python -m pip，可以降低电脑中存在多个 Python 解释器时把包装到错误环境的概率。安装后运行 python -m pip show discord.py，确认版本和安装位置。服务器部署时使用 python -m pip install -r requirements.txt，不要依赖系统中碰巧存在的全局包。最小项目目录不需要复杂脚手架：discord-bot/
├── bot.py
├── .env
├── .gitignore
└── requirements.txt
新建 bot.py，先实现环境检查、命令同步和 /ping：import os

import discord
from discord import app_commands
from discord.ext import commands
from dotenv import load_dotenv

load_dotenv()

token = os.getenv("DISCORD_TOKEN")
test_guild_id = os.getenv("TEST_GUILD_ID")

if not token:
raise RuntimeError("缺少 DISCORD_TOKEN，请检查环境变量")

intents = discord.Intents.default()

class DiscordBot(commands.Bot):
async def setup_hook(self) -> None:
if test_guild_id:
guild = discord.Object(id=int(test_guild_id))
self.tree.copy_global_to(guild=guild)
synced = await self.tree.sync(guild=guild)
print(f"测试服务器已同步 {len(synced)} 个命令")
else:
synced = await self.tree.sync()
print(f"全局已同步 {len(synced)} 个命令")

bot = DiscordBot(command_prefix="!", intents=intents)

@bot.event
async def on_ready() -> None:
if bot.user is not None:
print(f"已登录：{bot.user}，用户 ID：{bot.user.id}")

@bot.tree.command(name="ping", description="检查机器人是否在线")
async def ping(interaction: discord.Interaction) -> None:
latency_ms = round(bot.latency * 1000)
await interaction.response.send_message(
f"在线，Gateway 延迟约 {latency_ms} 毫秒",
ephemeral=True,
)

bot.run(token)
同步逻辑放在 setup_hook()，而不是 on_ready()。网络短暂中断并恢复时，on_ready() 可能再次触发；如果每次都同步命令，会制造没有必要的 API 请求，也让日志难以判断一次启动究竟同步了几次。测试阶段通过 copy_global_to() 把全局定义复制到指定测试服务器，再执行服务器级同步。验收完成后移除 TEST_GUILD_ID，下次启动会执行全局同步。这里的 TEST_GUILD_ID 必须是服务器 ID，不是频道 ID、用户 ID 或应用 ID，并应按整数或字符串保存，不能转成浮点数。验证 /ping，而不是只看在线状态激活虚拟环境后运行：python bot.py
一次有效验收应同时看到三个结果：终端输出同步数量，随后打印登录账号和用户 ID；Discord 成员列表中机器人转为在线；输入 /ping 时能看到命令描述并收到私密回复。如果只满足其中一两项，说明链路仍未完全打通。/ping 返回的是 Bot 与 Discord Gateway 之间的 WebSocket 延迟，不代表用户设备到机器人业务服务的完整请求耗时。它适合判断连接是否存活，但不能替代数据库、外部 API 或完整命令的性能监控。命令名称应简短、稳定并体现动作，例如 /signup、/score 和 /userinfo。频繁改名不仅影响使用习惯，还可能在客户端缓存或不同同步范围中短暂出现新旧命令并存。发布前应为名称、描述、参数类型和权限要求做一次固定评审。耗时操作必须先确认交互Discord 交互要求应用迅速给出初始响应。数据库查询、调用游戏接口、导出报表或生成图片可能超过 3 秒，这类命令应先执行 defer()，完成任务后再通过 follow-up 返回结果：@bot.tree.command(name="report", description="生成服务器报告")
async def report(interaction: discord.Interaction) -> None:
await interaction.response.defer(ephemeral=True)

result = await build_report(interaction.guild_id)

await interaction.followup.send(result, ephemeral=True)

如果等到耗时工作结束后才首次调用 send_message()，用户可能先看到“应用程序没有响应”，即使服务端最终完成任务。是否调用 defer() 应由预计耗时决定，而不是等发生超时才补救。同步 HTTP 请求、time.sleep()、大文件同步读写和密集计算都会阻塞事件循环。网络调用应使用异步客户端并设置连接、读取超时；等待使用 await asyncio.sleep()；短暂且无法异步化的阻塞函数可以谨慎交给 asyncio.to_thread()。持续数分钟的导出或计算任务不宜留在交互处理函数中，应进入独立任务队列，并先向用户返回任务编号或处理状态。理解测试服同步与全局发布的差别开发阶段优先使用服务器级命令，因为变更通常能更快出现在指定服务器。全局命令面向安装该应用的所有服务器，传播并非即时完成。不要为了让客户端更快刷新而连续重启和反复同步，这会增加排查噪声，也可能触发接口限制。命令不显示时按以下顺序检查：查看启动日志，确认 tree.sync() 返回数量符合预期，并检查是否存在 HTTPException 或 Forbidden。核对测试服务器 ID，确认程序同步范围与当前检查的服务器一致。确认应用安装包含 applications.commands。重新打开命令选择器；必要时重启 Discord 客户端，排除本地显示缓存。检查频道对机器人角色的 View Channel、Send Messages 和 Use Application Commands 权限覆盖。如果刚切换为全局命令，等待平台传播，而不是继续修改已经正确的代码。删除或重命名命令后，也必须对相同范围重新同步。仅删除 Python 函数不会立即清理 Discord 端已经注册的命令。部署日志应明确标注本次执行的是测试服同步还是全局同步，避免实验命令意外发布给全部服务器。用 Cog 按业务职责拆分代码当项目只有一个命令时，单文件最容易理解；当命令逐渐增加，事件、权限、数据库访问和业务规则全部塞进 bot.py 会迅速失控。此时可按领域拆成 cogs/utility.py、cogs/events.py 和 cogs/moderation.py，而不是机械地按文件行数切割。一个基础 Cog 可以写成：import discord
from discord import app_commands
from discord.ext import commands

class UtilityCog(commands.Cog):
def init(self, bot: commands.Bot) -> None:
self.bot = bot

@app_commands.command(name="serverinfo", description="查看当前服务器信息")
async def serverinfo(self, interaction: discord.Interaction) -> None:
    guild = interaction.guild
    if guild is None:
        await interaction.response.send_message(
            "该命令只能在服务器中使用。",
            ephemeral=True,
        )
        return

    await interaction.response.send_message(
        f"服务器：{guild.name}\n成员数：{guild.member_count}",
        ephemeral=True,
    )

async def setup(bot: commands.Bot) -> None:
await bot.add_cog(UtilityCog(bot))
在 setup_hook() 中先执行 await self.load_extension("cogs.utility")，再同步命令，否则扩展中的命令可能不在本次同步集合中。数据库连接池、HTTP 会话和缓存客户端应由 Bot 实例或独立服务层统一创建与关闭，不要让每个 Cog 各自建立一套连接。参数应尽量使用 Discord 提供的类型。频道、成员和角色不要让用户手工输入名称，因为名称可能重复，也可能被随时修改；持久化时应保存 Discord ID。人数要有上下限，备注要限制长度，管理操作应要求明确原因。输入约束越靠近命令入口，业务层遇到的异常状态越少。数据库选择取决于数据寿命和并发只有需要跨重启保留的数据才必须进入数据库。临时冷却计时可以放在内存中；积分、报名、警告记录、服务器配置和任务状态必须持久化。个人项目或单实例小型机器人可从 SQLite 开始，多服务器正式服务通常更适合 PostgreSQL。Redis 适合缓存、限流计数和短期会话，但不应被默认当作主数据库。场景建议方案主要风险本地开发、单实例小型服务SQLite并发写入能力有限，数据库文件需要单独备份正式社群、多服务器服务PostgreSQL需要管理连接池、迁移、账号权限和备份排行榜缓存、验证码、限流Redis必须设置过期时间，关键数据仍需写入主数据库以赛事报名为例，一条记录至少包含 guild_id、event_id、user_id、状态和创建时间，并为 event_id + user_id 建立唯一约束。这样即使同一用户快速点击两次，数据库仍能阻止重复报名。不要把用户名或服务器昵称作为唯一键，因为它们可以改变，也可能重复。时间建议统一存储为 UTC，展示时再转换为服务器或用户时区。积分转账、名额扣减等涉及多步写入的流程必须使用事务。例如转账需要扣减发送者余额、增加接收者余额并记录流水，其中任何一步失败都应整体回滚。不能只在 Python 中“先查余额再写入”，因为两个并发请求可能同时读到旧值并造成超额操作。备份的价值要通过恢复验证。除了按计划复制 SQLite 文件或导出 PostgreSQL，还应定期在隔离环境恢复一次，确认备份完整、数据库版本兼容、迁移顺序正确。未经恢复测试的备份只能说明生成过文件，不能证明数据真的可用。统一处理错误，同时保护日志内容用户不需要看到 Python 堆栈，应得到简短且可执行的提示，例如“你没有执行该操作所需的权限”“机器人无法在该频道发送消息”或“活动已经截止”。详细异常、命令名称、服务器 ID、请求时间和追踪编号记录在服务端，以便定位问题。@bot.tree.error
async def on_app_command_error(
interaction: discord.Interaction,
error: app_commands.AppCommandError,
) -> None:
message = "命令执行失败，请稍后重试。"

if isinstance(error, app_commands.MissingPermissions):
    message = "你没有执行该操作所需的权限。"
elif isinstance(error, app_commands.BotMissingPermissions):
    message = "机器人缺少执行该操作所需的权限。"

if interaction.response.is_done():
    await interaction.followup.send(message, ephemeral=True)
else:
    await interaction.response.send_message(message, ephemeral=True)

错误处理必须区分交互是否已经响应。如果已经调用过 defer() 或首次回复，应使用 follow-up；否则再次调用初始响应会产生新的异常。日志中不得包含 Token、数据库密码、OAuth 密钥及不必要的消息正文。涉及封禁、删除、转账等敏感操作时，应单独记录操作者 ID、目标 ID、服务器 ID、原因和结果，形成可审计记录。通过 systemd 在 Linux 上持续运行开发完成后，可部署到支持常驻进程的 Linux VPS 或托管平台。创建低权限系统用户运行机器人，不要长期使用 root。服务器安装与本地兼容的 Python 版本，拉取代码、创建虚拟环境、安装依赖，然后在命令行手动启动一次，确认环境变量和网络连接正常，再交给 systemd。服务配置可以采用以下结构，用户名和路径必须替换为实际值：[Unit]
Description=Discord Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=discordbot
WorkingDirectory=/opt/discord-bot
EnvironmentFile=/opt/discord-bot/.env
ExecStart=/opt/discord-bot/venv/bin/python /opt/discord-bot/bot.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
重新加载并启动：sudo systemctl daemon-reload
sudo systemctl enable --now discord-bot
sudo systemctl status discord-bot
sudo journalctl -u discord-bot -f
Restart=on-failure 只能在进程异常退出后尝试重启，不能修复错误配置。如果 Token 无效、数据库不可达或代码导入失败，systemd 可能每隔 5 秒重新启动一次。部署后必须观察日志，确认进程不是处于持续失败循环。更新代码这事别急着重启，新增的依赖先装好，接着跑数据库迁移，确认没问题了再把服务重启。涉及表结构变化时应准备可执行的回滚方案。仅运行 Discord Bot 不需要 Nginx。只有应用同时提供 Web 管理后台、OAuth2 回调或 HTTP 健康检查接口时，才需要反向代理和 TLS。没有用途的公开端口只会增加维护成本和攻击面。限流、重试与后台任务的边界discord.py 会处理正常的 Discord API 限流，但业务设计不能因此忽视发送规模。不要一次性向数千名成员逐条私信，也不要在失败后无限重试。批量通知应分批执行，记录每个目标的成功或失败状态，并允许管理员终止任务。成员关闭私信、离开服务器或屏蔽机器人都属于可预期失败，不应被当成系统崩溃。外部 API 请求要设置连接和读取超时，只对临时网络错误或明确可重试的服务端错误进行有限次数重试，并采用逐步延迟。参数错误、权限拒绝和资源不存在通常不应重试。积分、付款、兑换或报名类功能还需要幂等键，防止用户重复提交或客户端重试造成多条业务记录。定时提醒和大型导出任务要保存任务状态。进程重启后，应能判断任务是尚未开始、执行中、已完成还是失败，而不是完全依赖内存中的计时器。多实例部署时还要防止两个进程同时领取同一任务，可使用数据库锁、状态条件更新或专门的任务队列解决。按症状定位常见故障启动提示 Improper token has been passed：确认 DISCORD_TOKEN 是否存在、是否完整，以及当前进程是否读取了预期的环境文件。Token 重置后，旧值立即失效；只更新本地而未更新服务器也会出现同样问题。机器人一直离线：先检查进程状态和启动日志。环境变量未加载、依赖安装到错误解释器、代码导入失败、服务器无法连接 Discord，都会让程序在建立连接前退出。此时无需优先检查频道权限，因为频道权限不会导致整个 Bot 无法登录。机器人在线，但看不到 Slash 命令：检查同步数量、同步范围、测试服务器 ID 和应用安装范围。开发时先用服务器级同步验证；切换全局命令后应为传播预留时间。命令出现，但执行后显示没有响应：检查处理函数是否及时调用 send_message() 或 defer()。随后从日志确认是否卡在同步 HTTP、数据库锁、文件处理或权限错误。客户端提示只能说明交互没有正常完成，不能直接指出根因。只有一个频道不可用：查看该频道的权限覆盖。服务器角色允许发送消息，不代表频道没有显式拒绝。论坛频道、帖子、线程和归档线程还具有各自的可见性和发送条件，应在真实目标类型中逐项测试。普通消息事件没有触发：如果业务确实需要读取正文，代码中要设置 intents.message_content = True，Developer Portal 也要开启 Message Content Intent，两侧缺一不可。如果使用 on_message 并保留传统前缀命令，还需要调用 await bot.process_commands(message)。仅使用 Slash 命令时通常无需开启。管理操作返回 Forbidden：同时检查机器人权限、频道覆盖和角色层级。机器人最高角色必须高于目标对象，且无法管理服务器所有者。不要通过授予 Administrator 绕过调查，因为角色层级问题仍可能存在。机器人跑了一阵突然不响应，我一般先翻最后一条正常日志，再看 CPU、内存和数据库连接用了多少。排查时多盯着这几类问题：同步网络请求把线程卡住了、循环根本没有退出条件、接口没设超时、响应对象用完没关，还有缓存一直涨、始终不清。事件循环阻塞会影响心跳；连接池耗尽则可能让所有新命令停在数据库访问处。上线前的可执行检查清单Token 只存在于受控环境变量或环境文件中，Git 历史、日志和截图不含凭据。核心命令已测试正常输入、无效输入、调用者无权限、机器人无权限和外部服务失败。邀请权限与当前功能一致，没有为了减少排错而授予 Administrator。耗时命令会先 defer()，外部请求有超时，代码中没有阻塞事件循环的同步等待。数据库使用 Discord ID 关联用户、角色、频道和服务器，关键表具备唯一约束。多表写入使用事务，积分、名额和兑换操作考虑了并发与重复提交。日志能定位命令、服务器和发生时间，但不保存 Token、密码和不必要的敏感正文。systemd 或托管平台已配置异常重启，并验证服务器重启后机器人能自动恢复。测试服同步和全局同步范围清晰，发布日志能够确认本次同步目标。备份已经在隔离环境中执行过恢复测试，而不只是确认备份文件存在。批量通知具备分批、停止条件、失败记录和有限重试，不会无限循环发送。依赖可通过 requirements.txt 在干净环境重新安装，部署步骤不依赖个人电脑中的隐含配置。用一个业务闭环检验是否真正可上线第一个可交付版本不应以命令数量衡量，而要看一个场景能否从输入走到审计和恢复。以赛事报名为例：成员提交报名后，机器人检查活动状态和参数；数据库唯一约束拦截重复记录；成功后返回确认信息；管理员能够查询或导出名单；活动开始前由后台任务发送提醒；发送失败被记录并可有限重试；服务重启后报名数据和任务状态仍然存在。这个闭环会同时暴露权限、交互时限、数据库事务、后台任务、日志和部署方面的问题。它稳定后，再扩展积分、队伍匹配、身份验证或自动审核。每增加一种能力，都重新评估 Gateway Intent、Bot 权限、数据保留时间和失败策略，不沿用“先授予最高权限再说”的做法。按这种顺序开发，机器人即使逐步变复杂，仍能保持权限可解释、故障可定位、数据可恢复，并能从测试服务器平稳迁移到正式社群。