grammY 教學：打造強大又靈活的 Telegram 機器人新利器

什麼是 Grammy？

grammY - The Telegram Bot Framework (grammyjs)

grammY 是一個現代化的 Telegram 機器人開發框架，專為提升開發效率與程式碼可維護性而設計。 它基於 Telegram 官方 Bot API 打造，提供了一層直覺且高效的開發介面，讓開發者無需直接處理底層的 HTTP 請求或複雜的更新處理機制。

grammY 支援 TypeScript 和 JavaScript，並可在 Node.js、Deno，甚至瀏覽器中運行，適用於各種開發環境。 透過簡潔的 API 設計，grammY 讓開發者能夠快速建構功能豐富的 Telegram 機器人，從小型通知服務到大型交互式應用皆適用。

若你曾經直接操作 Telegram Bot API，就會體會 grammY 所帶來的抽象化好處：它簡化了 webhook 管理、訊息處理與錯誤處理， 讓開發者能專注於功能設計，而非底層通訊細節。

https://assets.calpa.me/普通和理所當然是什麼呢.avif

如果你想看一個實際應用 grammY 框架開發的真實案例，可以參考我之前分享的 MyGO!!!!! Telegram 機器人開發實錄 —— 結合 Cloudflare Workers 和 Hono，打造高速且具互動性的動漫圖片搜索機器人！

為什麼選擇 Grammy？

grammY 之所以成為眾多開發者首選，主要源於以下四大優勢：

1. 簡潔直覺的 API 設計：讓機器人開發快速上手，降低學習曲線
2. 卓越的 TypeScript 支援：提升開發效率與專案可維護性
3. 同步更新 Telegram Bot API：確保支援最新平台功能
4. 靈活的中間件架構：提供高彈性且模組化的程式組織方式

接下來，我們將逐一深入探討這些特點。

簡單易用的 API

grammY 的核心優勢之一是其簡潔的 API 設計。它使得創建 Telegram 機器人變得異常簡單：

// 建立一個回覆任意訊息的基本機器人
import { Bot } from "grammy";

const bot = new Bot(""); // 在引號中放入你的機器人令牌 (https://t.me/BotFather)

// 回覆任何消息
bot.on("message", (ctx) => ctx.reply("你好！"));

bot.start();

這種簡潔性使得 grammY 成為初學者和經驗豐富的開發者的理想選擇。

卓越的 TypeScript 支持

TypeScript (Microsoft)

作為一個從零開始使用 TypeScript 構建的框架，grammY 提供了出色的類型安全和推斷功能。這對於大型專案尤為重要，可以顯著提高開發速度並減少錯誤。

與 Telegraf 等其他框架相比，grammY 的類型系統更加直觀且易於使用。當你編寫代碼時，grammY 能夠提供更好的編輯器支持和自動完成功能。

始終保持最新狀態

grammY 始終與最新版本的 Telegram Bot API 保持同步。這確保你可以立即使用 Telegram 平台提供的最新功能，而不必等待框架更新。

靈活的中間件架構

grammY 採用靈活的中間件架構，允許開發者輕鬆組織代碼和處理各種類型的更新：

// 使用會話中間件
bot.use(session());

// 處理命令
bot.command("start", (ctx) => ctx.reply("已啟動！"));
bot.command("help", (ctx) => ctx.reply("幫助文本"));

// 處理文本消息
bot.on(":text", (ctx) => ctx.reply("收到文本！"));

// 處理照片
bot.on(":photo", (ctx) => ctx.reply("收到照片！"));

這種架構使代碼組織更加清晰，並且可以根據需要進行擴展。

豐富的插件生態系統

想要擴充你的機器人功能？grammY 擁有完善的官方與社群插件，讓你快速實現各種需求！

官方插件總覽

grammY 團隊與社群提供了豐富的官方插件，涵蓋資料管理、國際化、多語系、錯誤處理等各種開發需求。以下整理官方分類與常見插件，方便選擇合適的擴展功能：

Built-in 內建插件

• Sessions and Storing Data：提供 session 管理與資料存儲能力，輕鬆保存用戶狀態。
• Inline and Custom Keyboards：簡單生成各式回覆鍵盤與內聯鍵盤。
• Media Groups：支援管理 Telegram 的多媒體訊息群組（Media Groups）。
• Inline Queries：快速處理內聯查詢 (Inline Mode) 的回應。

Official 官方插件

• Conversations (@grammyjs/conversations)：建構多步驟、可中斷恢復的對話流程。
• Interactive Menus (@grammyjs/menu)：定義動態可互動的選單，輕鬆管理內聯鍵盤結構。
• Stateless Question (@grammyjs/stateless-question)：以輕量方式提問並處理回覆，無需持久 session。
• Concurrency (@grammyjs/runner)：提升大規模機器人的併發處理能力。
• Hydration (@grammyjs/hydrate)：自動豐富 Context，讓訊息與回覆 API 更直覺易用。
• Retry API Requests (@grammyjs/auto-retry)：自動重新嘗試失敗的 API 請求，提高穩定性。
• Flood Control (@grammyjs/transformer-throttler)：控制傳送頻率，避免因超過速率限制而被封鎖。
• Rate Limit Users (@grammyjs/ratelimiter)：限制單一用戶的請求頻率，防止濫用。
• Files (@grammyjs/files)：簡化檔案上傳與管理功能。
• Internationalization (@grammyjs/i18n)：輕量級國際化支援，讓機器人多語系切換更方便。
• Internationalization (fluent) (@grammyjs/fluent)：整合 Mozilla Fluent 系統的強大國際化支援。
• Router (@grammyjs/router)：根據不同條件（命令、狀態）分派處理邏輯，適合大型專案架構。
• Emoji (@grammyjs/emoji)：輕鬆插入、處理 Telegram 特有 emoji 表情符號。
• Parse Mode (@grammyjs/parse-mode)：簡化文字格式處理（HTML、Markdown 解析設定）。
• Chat Members (@grammyjs/chat-members)：操作、管理聊天群組成員資訊與權限。
• Commands (@grammyjs/commands)：統一管理 bot 指令註冊與說明，提升指令易用性。

✨ 更多插件資訊與完整 API 文件，可參考官方網站：grammy.dev/plugins

這些插件模組化、設計簡潔，讓你可以依需求靈活組合，快速打造出功能強大且維護性高的 Telegram 機器人應用。

對話管理能力

grammY 的對話插件（conversations）允許開發者創建複雜的交互式對話，而無需使用大量的配置對象。這使得代碼更加可讀和易於維護：

// 使用對話插件創建交互式對話
async function orderPizza(conversation, ctx) {
  await ctx.reply("您想要什麼尺寸的披薩？");
  const size = await conversation.form.select(["小", "中", "大"]);

  await ctx.reply("您想要哪種配料？");
  const toppings = await conversation.form.select(
    ["起司", "蘑菇", "火腿", "鳳梨"],
    {
      multiselect: true,
    }
  );

  await ctx.reply(`您已訂購${size}號披薩，配料：${toppings.join("、")}`);
}

這種方式使開發者能夠創建更加自然和流暢的用戶體驗。

與其他框架的比較

與 Telegraf 的比較

Telegraf 是另一個流行的 Telegram 機器人框架，但 grammY 在多個方面提供了顯著優勢：

1. API 更新：grammY 始終支持最新版本的 Bot API，而 Telegraf 經常落後幾個版本
2. 文檔質量：grammY 擁有更完整、更易於理解的文檔
3. TypeScript 支持：grammY 的 TypeScript 類型更加直觀，能更好地跟隨代碼邏輯
4. 內聯提示：grammY 集成了來自官方 Bot API 參考的內聯提示，在編寫代碼時提供幫助

性能比較

在性能方面，grammY 被設計為輕量級且高效，使其適合需要快速響應時間的機器人。其架構最小化了開銷，允許高效處理 Telegram 更新。

對於大規模使用，grammY 提供了專門的工具如 runner 插件，用於處理高負載場景。

部署選項

Cloudflare (Cloudflare)

grammY 機器人可以輕鬆部署到各種平台。現代部署推薦使用 Cloudflare Workers，能充分發揮 grammY 輕量、高效的特性。以下是部署到 Cloudflare 的基本流程：

1. 安裝 Wrangler CLI：

npm install -g wrangler

2. 初始化專案並選擇適合的模板（建議使用 TypeScript 專案）：

wrangler init my-bot
cd my-bot

3. 設定 wrangler.toml，並將 Telegram Bot Token 設為環境變數。

name = "my-bot"
main = "src/index.ts" # 如果是 TypeScript 專案
compatibility_date = "2025-04-28"

使用 wrangler secret put BOT_TOKEN 上傳 Telegram Bot Token 會更加安全

4. 撰寫機器人邏輯，確保使用 Cloudflare 相容的 API，例如透過 fetch 處理 Telegram webhook 請求。

import { Bot, webhookCallback } from "grammy";
import { Hono } from "hono"; // 可選，使用 Hono 管理 routing

// 讀取環境變數
const bot = new Bot(BOT_TOKEN);

// 定義機器人邏輯
bot.command("start", (ctx) =>
  ctx.reply("🤖 歡迎來到我的 Cloudflare Workers 機器人！")
);
bot.on("message:text", (ctx) => ctx.reply(`你說了：${ctx.message.text}`));

// 使用 Hono 框架處理 Webhook 請求
const app = new Hono();

// 設置 webhook 處理路徑
app.post("/webhook", async (c) => {
  const handler = webhookCallback(bot, "cloudflare-mod");
  return await handler(c.req.raw);
});

export default app;

如果不想用 Hono，只用原生 Fetch API，也可以這樣簡寫：

import { Bot, webhookCallback } from "grammy";

const bot = new Bot(BOT_TOKEN);

bot.command("start", (ctx) => ctx.reply("🤖 歡迎使用 Workers Bot！"));

const handle = webhookCallback(bot, "cloudflare-mod");

export default {
  async fetch(request: Request): Promise<Response> {
    if (
      request.method === "POST" &&
      new URL(request.url).pathname === "/webhook"
    ) {
      return handle(request);
    }
    return new Response("OK", { status: 200 });
  },
};

5. 部署到 Cloudflare：

wrangler deploy

部署完成後，會給你一個網址，例如：

https://my-bot.<your-subdomain>.workers.dev/webhook

6. 設定 Telegram Webhook

最後，使用下面的指令把你的 bot 接到 Workers 的 webhook：

curl "https://api.telegram.org/bot<你的BOT_TOKEN>/setWebhook?url=https://my-bot.<your-subdomain>.workers.dev/webhook

記得把 <你的BOT_TOKEN> 和 <your-subdomain> 換成自己的。

Cloudflare Workers 支援高併發、低延遲回應，非常適合 Telegram 機器人需要快速處理訊息的場景。

記得在 Telegram 上設定你的 Webhook URL 指向 Cloudflare Workers 部署的網址。

Workers 有執行時間限制（一般 10 秒），建議只做快速回應，若有長時間處理需求，可以搭配 Durable Objects 或外部後端服務。

社區和生態系統

grammY 擁有一個不斷成長的社區和豐富的生態系統：

1. 優秀的文檔：詳細的指南、教程和 API 參考
2. 社區支持：友好的 Telegram 社區聊天群組，歡迎新成員和問題討論
3. 豐富的示例：包含各種用例的示例機器人
4. 與其他工具的集成：與數據庫和 Web 框架的良好集成

結論

https://assets.calpa.me/感謝您讓我占用的寶貴時間.avif

Grammy 是一個強大、現代且易於使用的 Telegram 機器人框架，適合各種規模的項目。其卓越的 TypeScript 支持、豐富的插件生態系統和全面的文檔使其成為開發 Telegram 機器人的理想選擇。

對於喜歡使用 TypeScript 進行開發的全棧工程師來說，Grammy 提供了熟悉的開發體驗和出色的工具支持，使機器人開發過程更加愉快和高效。無論是簡單的通知機器人還是複雜的交互式應用，Grammy 都能幫助你快速實現目標。

如果你正在尋找一個現代、可靠且功能豐富的 Telegram 機器人框架，Grammy 絕對值得一試。它不僅簡化了機器人開發流程，還提供了擴展性和性能，使其成為長期項目的理想選擇。