如何在discord.py中使用@app_commands.describe及添加命令参数

要在discord.py的应用命令中添加参数并显示描述，需要同时做好函数参数声明和描述装饰器绑定，以下是正确的实现方式和常见问题排查：

正确代码示例 #

from discord import app_commands
from discord.ext import commands
import discord

class MyBot(commands.Bot):
    def __init__(self):
        super().__init__(command_prefix="!", intents=discord.Intents.default())

    async def setup_hook(self):
        # 同步命令到Discord，全局命令可能需要几分钟生效，测试可指定guild_id
        await self.tree.sync()

bot = MyBot()

# 定义应用命令，主装饰器设置命令名称和整体描述
@bot.tree.command(name="add", description="计算两个数字的和")
# 给每个参数添加描述，参数名必须和函数内的参数完全一致
@app_commands.describe(num1="第一个要相加的数字", num2="第二个要相加的数字")
async def add(interaction: discord.Interaction, num1: int, num2: int):
    await interaction.response.send_message(f"{num1} + {num2} = {num1 + num2}")

bot.run("你的Bot令牌")

关键注意事项 #

• 参数必须在函数中声明：命令的参数是直接作为函数的参数定义的，比如num1: int，Discord会根据类型自动生成对应的输入组件（数字输入框）
• 描述装饰器参数名要完全匹配：@app_commands.describe中的键名必须和函数参数名完全一致，拼写错误会导致描述无法绑定到参数
• 必须同步命令：修改参数或描述后，一定要执行await self.tree.sync()完成命令同步，全局命令同步可能需要1-5分钟，测试时可以在sync()中传入guild=discord.Object(id=你的服务器ID)，实现服务器内快速同步

常见问题排查 #

• 如果参数没显示：检查函数是否正确声明了参数，以及参数类型是否合法（discord.py支持int、str、bool、discord.Member等多种内置类型）
• 如果描述没显示：核对@app_commands.describe中的参数名和函数参数名是否完全一致，有没有大小写或拼写错误
• 同步后仍不生效：尝试重启Bot并重新同步，或者检查Bot是否有对应的服务器权限（应用命令权限）

内容的提问来源于stack exchange，提问作者parkercoder432