Commande globale Discord vs guilde : comparaison complète

L'une des premières décisions déroutantes quand on développe un bot Discord est celle-ci : faut-il enregistrer une commande slash en tant que commande globale Discord ou en tant que commande liée à un serveur précis (guilde) ? Les deux proviennent du même code et se déclenchent de la même façon, mais leurs méthodes d'enregistrement, leurs délais de mise à jour et leurs cas d'usage diffèrent nettement. Dans cet article, je montre les deux approches avec du vrai code discord.js et je clarifie laquelle choisir et quand.

Qu'est-ce qu'une commande globale et une commande de guilde ?

Une commande globale est visible sur tous les serveurs où ton bot a été invité, et même en messages privés (si tu l'autorises). Tu l'enregistres une seule fois et le bot propose la même commande partout. Une commande de guilde n'est visible que sur le serveur précis où tu l'as enregistrée ; en dehors, tout se passe comme si la commande n'existait pas.

Côté API Discord, la distinction vient de deux points de terminaison distincts :

• Globale : PUT /applications/{application.id}/commands
• Guilde : PUT /applications/{application.id}/guilds/{guild.id}/commands

discord.js enveloppe ces points de terminaison avec les helpers Routes.applicationCommands() et Routes.applicationGuildCommands().

La différence la plus importante : le délai de mise à jour

En pratique, ce qui sépare le plus les deux méthodes, c'est quand la commande apparaît dans le client Discord après l'enregistrement :

• Les commandes de guilde se mettent à jour presque instantanément. Elles apparaissent dans le menu slash quelques secondes après l'enregistrement. C'est idéal pour le développement et les tests.
• Les commandes globales se propagent. Discord les met en cache ; un changement atteint généralement tous les clients rapidement, mais dans le pire des cas cela peut prendre jusqu'à une heure. Ajouter une nouvelle commande ou changer sa description peut ne pas apparaître immédiatement.

Cette seule différence guide la plupart des choix d'architecture : en plein développement, tu ne veux pas dépendre du global et attendre des heures en te demandant « pourquoi ça n'apparaît pas ? ».

Enregistrer les commandes avec discord.js (REST)

Les commandes sont généralement enregistrées avec un script deploy-commands.js séparé, que tu lances uniquement quand les commandes changent, pas à chaque démarrage du bot. Voici un exemple qui enregistre sur une guilde (discord.js v14) :

const { REST, Routes, SlashCommandBuilder } = require('discord.js');

const commands = [
  new SlashCommandBuilder()
    .setName('ping')
    .setDescription('Affiche la latence du bot'),
].map(c => c.toJSON());

const rest = new REST({ version: '10' }).setToken(process.env.TOKEN);

(async () => {
  await rest.put(
    Routes.applicationGuildCommands(process.env.CLIENT_ID, process.env.GUILD_ID),
    { body: commands },
  );
  console.log('Commandes de guilde enregistrées.');
})();

Pour rendre le même script global, le seul changement consiste à remplacer la route et à supprimer le GUILD_ID :

await rest.put(
  Routes.applicationCommands(process.env.CLIENT_ID),
  { body: commands },
);

Attention : la méthode put écrase. Le tableau que tu envoies devient l'ensemble complet des commandes pour ce périmètre (global ou cette guilde). Si tu retires une commande du tableau, le prochain put la supprime. Ce comportement est volontaire et offre un enregistrement idempotent.

Laquelle utiliser, et quand ?

En règle générale, je recommande cette approche :

• Utilise des commandes de guilde pendant le développement. Enregistre-les sur ton propre serveur de test ; chaque changement apparaît instantanément et tu n'attends jamais des heures de propagation.
• Utilise des commandes globales en production. Si le bot tourne sur de nombreux serveurs, enregistrer les commandes sur chaque guilde une par une n'a aucun sens ; le global atteint partout en un seul appel.
• Garde les commandes de guilde pour les fonctions propres à un serveur. Les commandes d'administration d'une seule communauté, les commandes d'événements spéciaux et choses similaires ne devraient pas être globales.

Beaucoup de projets sérieux utilisent les deux : les commandes destinées aux utilisateurs en global, et les commandes qui ne tournent que sur le serveur de support/administration en périmètre de guilde.

Erreurs fréquentes

• Commandes en double. Si tu enregistres la même commande à la fois en global et en guilde sur ton serveur de test, tu y verras deux copies. Nettoie l'enregistrement de guilde une fois les tests terminés (un put avec un tableau vide).
• La panique « la commande n'apparaît pas ». Un changement global ne se reflète pas instantanément ; ne le déclare pas « cassé » sans avoir réellement attendu jusqu'à une heure. Pour tester vite, enregistre temporairement sur une guilde.
• Confondre enregistrement et écoute. Enregistrer une commande (REST put) et gérer l'interaction entrante (l'événement interactionCreate) sont deux tâches distinctes. Écoute sans enregistrer : la commande n'apparaît jamais ; enregistre sans écouter : tu obtiens « Cette interaction a échoué » au clic.
• Mauvais CLIENT_ID. C'est l'identifiant de l'application, pas celui du bot (ils coïncident pour la plupart des bots, mais l'ID d'application est le bon conceptuellement).

Questions fréquentes

Une commande globale prend-elle vraiment une heure ?

En général c'est beaucoup plus rapide et le changement apparaît en quelques minutes. Cependant, Discord garantit une limite supérieure d'une heure ; surtout pour les commandes nouvellement ajoutées, le cache peut provoquer un délai. C'est pourquoi il est plus sain d'utiliser des commandes de guilde pour les tests plutôt que de se fier au global.

Puis-je tester une commande sur une guilde d'abord, puis la rendre globale ?

Oui, c'est le flux de travail le plus courant. Tu enregistres sur une guilde pendant le développement, puis tu lances le script global quand c'est prêt. Pense juste à nettoyer l'enregistrement de la guilde de test pour ne pas voir de doublons.

Comment supprimer une commande ?

Envoyer un put avec un tableau vide sur la route concernée supprime toutes les commandes de ce périmètre. Pour supprimer une seule commande, tu peux utiliser rest.delete() avec son ID, ou la retirer du tableau et refaire un put.

Tu veux mettre en place correctement l'architecture des commandes de ton bot Discord ? Je planifie et construis le périmètre global/guilde, les permissions et la stratégie de propagation autour de ton projet. Si tu as un projet de bot, contacte-moi.