discord.py による Discord Bot 開発

discord.py は、Python で Discord Bot を作るための代表的なライブラリです。Bot の接続、イベント受信、コマンド処理、UI部品の操作などを Python の非同期処理として扱えます。

古い記事のコードをそのままコピーすると、現在の Intent、Interaction、非同期処理の前提と合わないことがあります。この記事では、環境、Portal、最小起動、機能分割、運用準備の順に整理します。

開発環境を用意する

Python と仮想環境

まず Python のバージョン、仮想環境、依存関係の管理方法を決めます。手元の環境に直接ライブラリを入れるより、プロジェクトごとに仮想環境を作る方が、後から壊れたときに切り分けやすくなります。

一般的な流れは、プロジェクト用フォルダを作り、venv で仮想環境を用意し、pip で discord.py をインストールする形です。実際のコマンドや対応バージョンは、discord.py の Installing と Quickstart、Python ドキュメントを合わせて見ます。

確認ポイント

• python --version で利用する Python を把握した
• プロジェクト専用の仮想環境を用意した
• pip freeze や lockfile で依存関係を再現できる
• ファイル名を discord.py にしてライブラリ名と衝突させていない

Developer Portal と Token

discord.py のコードを書くだけでは Bot は動きません。先に Developer Portal で Application と Bot を用意し、Bot Token を発行し、必要な Intent や導入URLを整えます。Portal の全体像はDiscord Developer Portal 解説で扱っています。

Token は、DISCORD_TOKEN のような環境変数で渡すのが基本です。コード内に文字列として埋め込むと、リポジトリ、ログ、スクリーンショットから漏れる危険があります。漏えいした可能性がある場合は Token を再生成します。

⚠️ Bot Token は Bot の操作権限に直結します。公開リポジトリ、質問文、スクリーンショット、チャットログへ載せないでください。

小さく起動する

最小構成から始める

最初の目標は、Bot をサーバーに導入し、起動ログでログインできたことを確かめるところまでです。ここでコマンド、DB、外部API、画像生成などを同時に入れると、どこで失敗したのか分かりにくくなります。

discord.py 2.x の公式ドキュメントには、Client、commands extension、tasks、Interaction 関連の説明があります。まず Quickstart の最小構成を読み、目的に合わせて commands.Bot や app_commands へ進むのが安全です。

Intent とイベント

Bot がメッセージ、メンバー参加、リアクションなどのイベントを受け取るには、Portal 側とコード側の Intent が関わります。メッセージ本文やメンバー情報は、必要性を説明できる場合だけ有効にします。

イベントが来ないときは、コードだけでなく Portal 側、導入先サーバー、チャンネル権限、Bot の再起動を分けて点検します。詰まった場合はdiscord.py のトラブルシューティングで、Intent、cache、Cog、View の問題を切り分けます。

コマンドと機能を作る

スラッシュコマンドを中心に考える

現在のBotでは、入力補完や権限設定を扱いやすいスラッシュコマンドを中心に設計する場面が多くあります。prefix command は学習しやすい一方で、メッセージ本文の読み取りや Intent の影響を受けやすい点があります。

コマンド設計では、最初に「誰が、どのチャンネルで、何を実行できるか」を決めます。管理用コマンドは実行者の権限を見て、失敗時は利用者向けの短い返信と管理者向けログを分けます。Interaction の応答で詰まる場合はコマンド・Interaction の逆引きが役立ちます。

Cog とファイル分割

機能が増えたら、すべてを1ファイルに詰め込まず、役割ごとに分けます。discord.py では Cog や extension を利用して、コマンド、イベント、管理機能、定期処理などを整理できます。

分割するときは、読み込み順、設定値の渡し方、例外時のログを決めておきます。ファイルを分けること自体が目的ではなく、起動時にどの機能が読み込まれたか分かる状態にすることが重要です。

確認ポイント

• コマンドの利用者と実行場所を決めた
• 失敗時の返信と管理者向けログを分けた
• 機能ごとに読み込み単位を整理した
• 古いサンプルコードを、利用中の discord.py 2.x の説明と照らし合わせた

運用前に見ること

ローカルで動いた Bot でも、ホスティング先では環境変数、起動コマンド、Python バージョン、ログの見え方が変わります。デプロイ前に、起動方法と復旧方法を運用メモに残します。

公開サーバーへ入れる前に、テストサーバーで権限、Intent、コマンド応答、エラー時の挙動を見ます。運用に入る場合は、Bot 運用前チェックとホスティングのトラブルシューティングもあわせて確認しておきます。

確認ポイント

• Token と設定値を環境変数で渡している
• 起動ログとエラーログを読める
• テストサーバーで権限とIntentを試した
• Bot が落ちたときの再起動・通知・復旧手順を決めた