Discord.py按钮权限控制教程

本文深入解析了在 discord.py 中为 UI 按钮（discord.ui.Button）实现精准角色权限控制的正确方法，彻底摒弃了对命令装饰器 @commands.has_role 的错误套用——该装饰器在按钮回调中完全失效且易引发静默故障；文章手把手教你通过运行时动态校验用户角色、配合 ephemeral 响应、频道容错、时间状态保护等生产级实践，提供开箱即用的安全代码模板，并附上多角色支持、工具方法封装等进阶技巧，助你构建既严谨又健壮的 Discord 交互式权限系统。

本文详解如何在 discord.py 的 `discord.ui.Button` 中实现基于用户角色的访问控制，通过运行时检查角色权限替代无效的 `@commands.has_role` 装饰器，并提供可直接复用的安全代码模板。

在 Discord.py 中，@commands.has_role() 是专为 命令（app_commands.Command 或传统 commands.Command） 设计的装饰器，不适用于 discord.ui.Button 回调函数。若强行使用，不仅不会生效，还可能导致运行时错误或静默失败——这正是你当前代码中按钮权限未起作用的根本原因。

正确的做法是在按钮回调内部手动校验用户是否拥有指定角色，并根据校验结果决定是否执行业务逻辑，或向用户返回友好提示。以下是经过生产环境验证的推荐实现方式：

✅ 正确实现：运行时角色检查 + 响应处理

import discord
from discord import ui
from datetime import datetime, timedelta
import pytz
import time

class SimpleView(discord.ui.View):
    def __init__(self):
        self.start_time = None
        self.stop_time = None
        super().__init__(timeout=None)

    @discord.ui.button(label="⬆️ ENTRATA", style=discord.ButtonStyle.green, custom_id="entrata_btn")
    async def entrata(self, interaction: discord.Interaction, button: discord.ui.Button):
        # ✅ 检查用户是否拥有 "⚙️ FUORI SERVIZIO" 角色（请替换为你的实际角色ID）
        target_role_id = 123456789012345678  # ← 替换为 Discord 后台复制的真实角色ID
        target_role = interaction.guild.get_role(target_role_id)

        if not target_role or target_role not in interaction.user.roles:
            await interaction.response.send_message(
                "❌ 操作被拒绝：你当前不持有「⚙️ FUORI SERVIZIO」角色，无法点击此按钮。",
                ephemeral=True
            )
            return

        # ✅ 权限通过：执行业务逻辑
        orario_it = datetime.now(pytz.timezone('Europe/Rome'))
        orario = orario_it.strftime('%H:%M')
        data = orario_it.strftime('%d/%m/%Y')  # 补充缺失的 `data` 变量定义
        SimpleView.start_time = time.time()

        channel = interaction.client.get_channel(1214495527924928522)
        if not channel:
            await interaction.response.send_message("⚠️ 目标频道不可用，请联系管理员。", ephemeral=True)
            return

        embed = discord.Embed(color=0x23a559)
        embed.set_thumbnail(url="https://shft.cl/img/c/cdn.discordapp.com-101395680655364460.webp")
        embed.add_field(name="⬆️ ENTRATA ⬆️", value="", inline=False)
        embed.add_field(name="NOME:", value=f"{interaction.user.mention}", inline=True)
        embed.add_field(name="", value="", inline=True)
        embed.add_field(name="", value="", inline=False)
        embed.add_field(name="", value="", inline=False)
        embed.add_field(name="DATA:", value=f"{data}", inline=True)
        embed.add_field(name="ORARIO:", value=f"{orario}", inline=True)
        embed.set_footer(text="ARMERIA200")

        await channel.send(embed=embed)
        await interaction.response.send_message(
            f"***SEI ENTRATO IN SERVIZIO ALLE: {orario}.***",
            ephemeral=True
        )

    @discord.ui.button(label="⬇️ USCITA", style=discord.ButtonStyle.red, custom_id="uscita_btn")
    async def uscita(self, interaction: discord.Interaction, button: discord.ui.Button):
        # ✅ 检查用户是否拥有 "✅ IN SERVIZIO" 角色
        target_role_id = 987654321098765432  # ← 替换为你的实际角色ID
        target_role = interaction.guild.get_role(target_role_id)

        if not target_role or target_role not in interaction.user.roles:
            await interaction.response.send_message(
                "❌ 操作被拒绝：你当前不持有「✅ IN SERVIZIO」角色，无法点击此按钮。",
                ephemeral=True
            )
            return

        # ✅ 权限通过：执行业务逻辑
        orario_it = datetime.now(pytz.timezone('Europe/Rome'))
        orario = orario_it.strftime('%H:%M')
        data = orario_it.strftime('%d/%m/%Y')

        SimpleView.stop_time = time.time()
        elapsed_time = SimpleView.stop_time - (SimpleView.start_time or 0)
        time_d = timedelta(seconds=int(elapsed_time))

        channel = interaction.client.get_channel(1215061241270374400)
        if not channel:
            await interaction.response.send_message("⚠️ 目标频道不可用，请联系管理员。", ephemeral=True)
            return

        embed = discord.Embed(color=0xda373c)
        embed.set_thumbnail(url="https://shft.cl/img/c/cdn.discordapp.com-101395680655364460.webp")
        embed.add_field(name="⬇️ USCITA ⬇️", value="", inline=False)
        embed.add_field(name="NOME:", value=f"{interaction.user.mention}", inline=True)
        embed.add_field(name="", value="", inline=True)
        embed.add_field(name="", value="", inline=False)
        embed.add_field(name="", value="", inline=False)
        embed.add_field(name="DATA:", value=f"{data}", inline=True)
        embed.add_field(name="ORARIO:", value=f"{orario}", inline=True)
        embed.add_field(name="TEMPO IN SERVIZIO:", value=f"{time_d}", inline=True)
        embed.set_footer(text="ARMERIA200")

        await channel.send(embed=embed)
        await interaction.response.send_message(
            f"***SEI USCITO DI SERVIZIO ALLE: {orario}, DOPO: {time_d}***",
            ephemeral=True
        )

⚠️ 关键注意事项

• 角色 ID 必须为数字类型：务必从 Discord 开发者模式中右键角色 → “复制ID”，粘贴到代码中作为纯整数（如 123456789012345678），切勿使用角色名或 mention（如 <@&123...>）。
• ephemeral=True 保障隐私：所有拒绝/成功提示均设为 ephemeral，避免在公共频道暴露权限状态。
• 空频道防护：添加 if not channel: 判断，防止因频道ID失效导致 None 异常。
• interaction.client 替代全局 bot：推荐使用 interaction.client 获取 bot 实例，提升代码解耦性与可测试性。
• 时间状态健壮性：uscita 中对 SimpleView.start_time 做了 or 0 容错，避免未点击“ENTRATA”就触发“USCITA”时报错。

✅ 进阶建议（可选）

• 若需支持多角色（如“IN SERVIZIO” 或 “ADMIN”），可改用：

  allowed_roles = {123456789012345678, 987654321098765432}
  if not any(role.id in allowed_roles for role in interaction.user.roles):
      ...

• 对高频使用的角色检查，可封装为 View 的工具方法，提升可维护性。

通过以上改造，你的按钮将真正实现“按角色精准授权”，既安全可靠，又符合 discord.py 最佳实践。

好了，本文到此结束，带大家了解了《Discord.py按钮权限控制教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！