Como implantar comandos do bot do Discord globalmente vs por servidor com o decorador sync

Desenvolvedores de bots do Discord frequentemente precisam decidir se os comandos de barra devem estar disponíveis em todos os lugares ou apenas em servidores específicos. A abordagem global registra comandos para todos os servidores que possuem o bot, enquanto o método por servidor limita os comandos a uma única guild. O decorador @app_commands.guilds() no discord.py controla esse comportamento. Este artigo explica a diferença entre implantação global e por servidor e como usar o decorador de sincronização corretamente.

Implantação global vs por servidor de comandos em bots do Discord

Os comandos de barra do Discord são registrados através da árvore de comandos do bot. Quando você usa tree.sync(), o bot envia suas definições atuais de comando para a API do Discord. O Discord então armazena esses comandos como comandos globais ou comandos específicos de guild.

Comandos globais são visíveis em todos os servidores que possuem o bot. O Discord os armazena em cache agressivamente, então alterações podem levar até uma hora para aparecer. Esse atraso torna a implantação global inadequada durante o desenvolvimento, quando você precisa testar alterações de comando rapidamente.

Comandos por servidor são registrados apenas em um ID de guild específico. O Discord os atualiza quase instantaneamente — geralmente em alguns segundos. Desenvolvedores usam esse método em um único servidor de teste durante o desenvolvimento e depois mudam para comandos globais quando o bot está pronto para produção.

Como funciona o decorador @app_commands.guilds()

O decorador @app_commands.guilds() aceita um ou mais IDs de guild do Discord. Quando aplicado a um comando, esse comando é registrado apenas nesses servidores. Se você remover o decorador e sincronizar novamente, o comando se torna global. O decorador não afeta a funcionalidade do comando — ele apenas controla onde o Discord armazena a definição do comando.

Você pode misturar comandos globais e por servidor no mesmo bot. Comandos sem o decorador são globais. Comandos com o decorador são limitados às guilds listadas. Isso permite manter alguns comandos privados para teste enquanto outros estão disponíveis publicamente.

Passos para implantar comandos globalmente e por servidor

1. Configure seu projeto de bot
   Crie um arquivo Python e importe discord e app_commands. Inicialize o bot com discord.Client e uma árvore de comandos. Certifique-se de ter um token de bot do Portal do Desenvolvedor do Discord.
2. Defina um comando global sem o decorador
   Use @app_commands.command() para criar um comando de barra. Não adicione @app_commands.guilds(). Exemplo: @app_commands.command(name="hello", description="Diga olá"). Este comando será global após a sincronização.
3. Defina um comando por servidor com o decorador
   Aplique @app_commands.guilds() acima do decorador do comando. Passe o ID da guild como um inteiro. Exemplo: @app_commands.guilds(discord.Object(id=123456789012345678)). Este comando aparecerá apenas nesse servidor.
4. Sincronize a árvore de comandos
   Chame await tree.sync() dentro do evento on_ready ou através de um comando de sincronização dedicado. Para comandos globais, use await tree.sync(). Para comandos por servidor, passe o objeto guild: await tree.sync(guild=discord.Object(id=123456789012345678)).
5. Teste os comandos no Discord
   Digite /hello no servidor de teste. O comando global pode não aparecer por até uma hora. O comando por servidor deve aparecer imediatamente. Se não aparecer, aguarde alguns segundos e tente novamente.
6. Mude de por servidor para global para produção
   Remova o decorador @app_commands.guilds() de todos os comandos. Chame await tree.sync() sem um argumento guild. Os comandos agora serão globais. Observe que a propagação global leva até uma hora.

Erros comuns ao usar o decorador de sincronização

Comandos não aparecem após a sincronização

Se os comandos não aparecerem após a sincronização, verifique o ID da guild. O ID deve ser um inteiro, não uma string. Verifique também se o bot tem o escopo applications.commands habilitado no Portal do Desenvolvedor do Discord. Sem esse escopo, o bot não pode registrar comandos de barra.

Comandos globais ainda visíveis após mudar para por servidor

Se você implantou um comando globalmente anteriormente e depois adiciona um decorador @app_commands.guilds(), a versão global antiga pode permanecer em cache por até uma hora. Para removê-la imediatamente, chame await tree.clear_commands(guild=None) e depois sincronize. Isso exclui todos os comandos globais e permite que a versão por servidor assuma.

A sincronização sobrescreve todos os comandos

Chamar tree.sync() substitui todos os comandos existentes pelas definições atuais. Se você acidentalmente omitir um comando do seu código, a sincronização o excluirá do Discord. Sempre mantenha um backup das definições dos seus comandos ou use um servidor de teste para desenvolvimento.

Item	Implantação Global	Implantação por Servidor
Velocidade de propagação	Até 1 hora	Segundos
Visibilidade	Todos os servidores com o bot	Apenas guilds especificadas
Caso de uso	Lançamento em produção	Desenvolvimento e teste
Decorador necessário	Nenhum	@app_commands.guilds()
Chamada de sincronização	tree.sync()	tree.sync(guild=Object(id))

Use implantação global para bots públicos que precisam de comandos em todos os servidores. Use implantação por servidor durante o desenvolvimento para testar alterações imediatamente. Após o teste, remova o decorador e sincronize globalmente para produção. Sempre sincronize após adicionar ou modificar comandos para garantir que o Discord tenha as definições mais recentes.