前言

這是一篇 Python Discord Bot 實作筆記，會教學如何建構一個結構清晰、可維護性高的 Discord Bot。從基礎的 Bot 創建流程，到合理的檔案架構規劃，接著進入環境設置與 discord.py 模組的詳細介紹，最後則會學習如何透過 Cog 架構 來模組化指令，使 Bot 的擴展與維護更加便捷。

• 一、Discord Bot 創建：
• 二、檔案架構：
• 三、基礎環境設置：
• 四、Discord.py模組：
• 五、Discord Bot Cog 架構：

一、Discord Bot 創建

首先，如果您還沒有 Discord Bot，則需要在 Discord 開發者入口網站 中建立一個新的應用程式：

1. 建立應用程式

   • 點擊以下連結： 「Create App」，輸入您的 Bot 名稱，然後按下 「Create」（建立）。

2. 啟用 Bot 並取得 Token

   • 進入剛剛創建的應用程式頁面，點擊左側的 「Bot」 分頁。
   • 按下 「Add Bot」 按鈕，確認新增 Bot。
   • 在 「TOKEN」 區塊中點擊 「Reset Token」，並複製這組 Token（請妥善保存，避免洩漏）。

3. 設定 Bot 權限

   • 在 Bot 設定頁面，找到 「Privileged Gateway Intents」（特權閘道意圖），根據需求開啟 「PRESENCE INTENT」（狀態意圖）與 「SERVER MEMBERS INTENT」（伺服器成員意圖），這些設定可讓您的 Bot 監聽成員加入、離開等事件。
   • 設定 「PUBLIC BOT」（公開 Bot）與 「REQUIRES OAUTH2 CODE GRANT」（OAuth2 授權碼要求）。通常，建議將後者關閉，避免影響 Bot 登入流程。

4. 邀請 Bot 加入伺服器

   • 進入 「OAuth2」 分頁，在 「SCOPES」 中選擇 「bot」，然後在 「BOT PERMISSIONS」（Bot 權限）區域勾選您需要的權限（不知道該選哪些的話，直接勾選 Administrator 給最高權限）。
   • 複製最下面的 「Generated URL」，貼到瀏覽器並選擇要將 Bot 加入的 Discord 伺服器。

5. 成功加入伺服器後，執行以下操作以確保 Bot 順利運行：

   1. 調整 Bot 身分組順位

      • 進入 Discord 伺服器的 「伺服器設定」 → 「角色 (Roles)」。
      • 將 Bot 所屬的角色拖曳到最上方（至少高於 Bot 需要管理的身分組），確保它有足夠的管理權限。

   2. 啟用 Bot 的應用程式指令 (Slash Commands) 權限

      • 在 「伺服器設定」 → 「整合 (Integrations)」 → 「應用程式指令」，確認 Bot 具有適當的指令權限。
      • 若 Bot 需要全域指令權限，請確保 Use Application Commands 權限已啟用。

   3. 確認 Bot 具備必要的文字與語音頻道權限

      • 在 Bot 需要運行的文字頻道，確保它擁有 發送訊息、讀取訊息歷史、嵌入連結、附加檔案 等權限。
      • 若 Bot 需加入語音頻道，確保它擁有 連接、說話、使用語音偵測 的權限。

這樣， Bot 就完成了邀請與基礎設置！

二、檔案架構：

Python-Discord-Bot-Template/
├── cogs/
├── database/
├── venv/
├── .dockerignore
├── .env.example
├── .gitignore
├── Dockerfile
├── LICENSE.md
├── README.md
├── bot.py
├── docker-compose.yml
└── requirements.txt

1. cogs/

• 用途：儲存所有以 Cog 類別實作的指令模組與事件處理邏輯。
• 說明：Cog 是 Discord.py 的模組化單元，適用於指令（Commands）與事件（Events）的分工與組織管理。每一個 .py 檔案通常代表一個功能區塊（如：管理模組、遊戲模組、音樂模組等）。

2. database/

• 用途：與資料庫有關的所有檔案皆集中於此。
• 說明：可包含資料表定義（Schema）、資料初始化腳本、SQL 檔案，或 SQLite 等本地資料庫。若您使用外部資料庫（如 PostgreSQL），也建議將連線與模型邏輯集中於此資料夾內。

3. venv/

• 用途：儲存虛擬環境的執行檔與依賴套件。
• 說明：使用 Python venv 模組建立的虛擬環境，可有效隔離專案相依套件，避免版本衝突。此資料夾不應提交至 Git，請確保已列入 .gitignore。

4. .dockerignore

• 用途：定義在建構 Docker 映像檔時要排除的檔案與資料夾。
• 說明：類似 .gitignore，可加速建置流程並減少不必要的內容進入映像檔。

5. .env.example

• 用途：環境變數的範本設定檔。
• 說明：開發者應將此檔複製為 .env，並填入實際的 Token、資料庫連線字串等敏感資訊。方便不同開發者在本機環境進行一致的設定。

6. .gitignore

• 用途：列出 Git 在提交時應忽略的檔案與資料夾。
• 說明：常見項目包含 venv/、.env、快取檔（如 .pyc）等，避免洩漏機密或提交不必要的檔案。

7. Dockerfile

• 用途：定義如何建構 Bot 的 Docker 映像。
• 說明：指定作業系統環境、依賴套件安裝方式、啟動指令等，方便進行容器化部署。

8. LICENSE.md

• 用途：說明本專案的授權條款。
• 說明：預設為 Apache 2.0 授權，允許他人修改、商用，但需保留原始授權與貢獻者資訊。

9. README.md

• 用途：本專案的說明文件。
• 說明：包含專案簡介、安裝步驟、使用方式、貢獻指引等，是協助其他開發者理解與使用專案的第一入口。

10. bot.py

• 用途：Bot 的主要啟動入口。
• 說明：負責初始化 Discord Bot 實例、讀取設定、載入所有 Cog 模組，並啟動與 Discord 的連線。

11. docker-compose.yml

• 用途：定義多個服務的部署配置。
• 說明：若專案需要搭配資料庫（如 PostgreSQL）、快取（如 Redis）等，透過此檔案即可一次性啟動所有容器服務。

12. requirements.txt

• 用途：列出所有 Python 相依套件及其版本。
• 說明：執行 pip install -r requirements.txt 即可安裝所有套件，確保團隊成員或部署環境一致。

三、基礎環境設置

以下的環境配置是為了增加維護性、可擴充性及安全性，也利於後續於伺服器端上的部屬：

(1) 使用虛擬環境（Virtual Environment）

建議使用 Python 的虛擬環境管理專案依賴，以避免套件版本衝突並確保部署一致性：

python -m venv venv
source venv/bin/activate        # macOS / Linux
venv\Scripts\activate           # Windows
pip install -r requirements.txt

(2) 設定環境變數

建立 .env 設定檔，並放置機密資訊（如 Discord Token）：

cp .env.example .env
# 請在 .env 檔案中填入 DISCORD_TOKEN 等必要變數

可搭配 python-dotenv 模組，自 .env 自動載入環境變數至程式中。

(3) bot.py 主程式邏輯說明

主執行程式 in bot.py：

import os
import asyncio
import discord
from discord.ext import commands

intents = discord.Intents.all()
bot = commands.Bot(command_prefix="!", intents=intents)

# 當機器人完成啟動時
@bot.event
async def on_ready():
    print(f"目前登入身份 --> {bot.user}")

# 載入指令程式檔案
@bot.command()
async def load(ctx, extension):
    await bot.load_extension(f"cogs.{extension}")
    await ctx.send(f"Loaded {extension} done.")

# 卸載指令檔案
@bot.command()
async def unload(ctx, extension):
    await bot.unload_extension(f"cogs.{extension}")
    await ctx.send(f"UnLoaded {extension} done.")

# 重新載入程式檔案
@bot.command()
async def reload(ctx, extension):
    await bot.reload_extension(f"cogs.{extension}")
    await ctx.send(f"ReLoaded {extension} done.")

# 一開始bot開機需載入全部程式檔案
async def load_extensions():
    for filename in os.listdir("./cogs"):
        if filename.endswith(".py"):
            await bot.load_extension(f"cogs.{filename[:-3]}")

async def main():
    async with bot:
        await load_extensions()
        await bot.start(os.getenv("DISCORD_TOKEN"))

# 確定執行此py檔才會執行
if __name__ == "__main__":
    asyncio.run(main())

• intents 設定：discord.Intents.all() 啟用所有事件監聽能力，適合開發階段進行全功能測試。
• command_prefix：Bot 接收指令的前綴符號為 !。。
• 模組管理：load、unload 和 reload 指令可動態管理 cogs/ 中的模組，不須重新啟動 Bot 即可進行更新，有利於開發與除錯。