Astro 新文章 Telegram 推播:用 GitHub Actions 定時發到中英文頻道

摘要

把新文章發到 Telegram 頻道後,已經在用 Telegram 的讀者不需要留下電子郵件,就能收到每篇新文章的貼文。靜態網站沒有伺服器可以在發文時順便通知讀者,但只要用 GitHub Actions 定時讀取正式站的 RSS,和上一次的已發清單比對,就能自動發出新文章。中英文各自讀自己的 RSS、記自己的清單並發到自己的頻道,過幾天才合併上線或排程上線的文章也不會漏發或重發。

文章目錄

Telegram 頻道是讀者訂閱新文章的一種方式:已經在用 Telegram 的讀者加入頻道後,每次有新文章,就會收到一則附封面圖的貼文,不需要留下電子郵件。但 Astro 這類靜態網站的部署只會把檔案放上主機,文章上線後,沒有程式會去通知讀者。

只要讓 GitHub Actions 每天定時讀取正式站的 RSS,把還沒發過的文章送到頻道,再把已發的網址記下來,每篇新文章就會自動發出一次。網站有中英文版時,兩種語言各自讀自己的 RSS、記自己的清單,再發到各自的頻道。

本站在 2026 年 11 月拿掉 Web Push 的新文章通知後,改用這套設計推播新文章。中文文章發到 @vervecode,英文文章發到 @vervecode_en。每則貼文由封面圖、標題、摘要與文章連結組成,例如〈Unity 7 升級準備〉在中文頻道的貼文:

VerveCode 偵錯桐人頻道的貼文,上方是 Unity 7 Upgrade 的封面圖,下方是粗體的中文標題、摘要與「閱讀全文」連結

同一篇文章在英文頻道的貼文,標題、摘要與連結文字都換成英文:

VerveCode 偵錯桐人 (EN) 頻道的貼文,封面圖相同,下方是英文標題、摘要與「Read the full article」連結

設計

這套推播依照下面幾條規則設計:

  • 每天固定兩次,在台灣時間 11:07 與 20:07 檢查有沒有新文章。從文章上線到發出貼文,最久大約要等 15 小時。
  • 以正式站的 RSS 為準,RSS 裡出現了、清單上還沒有的文章才算新文章。
  • 每篇文章只發一次。發送中途失敗時,已發出的文章不會重發,沒發出的下一次再發。
  • 第一次執行時不發任何文章,避免把網站上所有舊文一次推出去。
  • 中文與英文各用一個公開頻道,讀者只訂閱自己讀的語言。
  • 已發清單不 commit 回 repo,也不需要另外架設伺服器或資料庫。

流程

GitHub Actions 的排程觸發後,中文與英文在同一個 job 裡依序各跑一次,各自讀取 RSS、比對並發文,最後一起存回清單:

流程圖:排程每天兩次觸發,先取回上一次的已發清單,中文與英文依序各自讀取正式站 RSS、和自己的清單比對、把新文章發到自己的頻道,最後存回兩份清單,失敗時開 issue流程圖:排程每天兩次觸發,先取回上一次的已發清單,中文與英文依序各自讀取正式站 RSS、和自己的清單比對、把新文章發到自己的頻道,最後存回兩份清單,失敗時開 issue

圖上是發到正式頻道的流程。發到測試頻道或用 dry run 執行時,不會取回也不會存回清單。

整個 job 只用 Node.js 內建的 fetch 與檔案讀寫,不需要安裝 npm 套件,本站每次執行大約 20 到 30 秒。

判斷新文章

判斷新文章的依據是正式站的 RSS,因為 RSS 是讀者實際看得到的結果。文章過了幾天才合併上線,或用排程在指定時間上線,只要出現在 RSS 裡,下一次執行就會發出去,還沒上線的草稿也不會發出。RSS 要列出所有文章,至少要多於兩次執行之間發佈的篇數,否則超出的文章不會出現在 RSS 裡,也就不會發出,本站的 RSS 列出全部 78 篇。

比對的對象是上一次執行留下的已發清單,清單裡存的是已經發過的文章網址。腳本讀到 RSS 後,依清單的狀態決定要發哪些文章:

情況 處理方式
有已發清單 RSS 裡不在清單上的文章就是新文章,從舊到新發出
沒有清單(第一次執行,或清單已過期) 把 RSS 現有的文章全部記為已發,不發文。手動指定 since 時,改發那天以後的文章
RSS 出現不屬於該語言的網址 直接中止,一則都不發

比對的核心只有幾行。announced 是用清單的 urls 陣列建立的 Set,沒有清單時是 null,pubDate 則是轉成 Date 的發佈時間。沒有清單時函式會回傳空陣列,呼叫端再把 RSS 的文章全部寫進清單:

1function pickNew(items, announced) {
2  if (!announced) return [];
3  return items
4    .filter((item) => !announced.has(item.link))
5    .sort((a, b) => a.pubDate - b.pubDate);
6}

只記上一篇文章的網址或時間也能判斷新文章,但一次上線兩篇時,順序和時間只要有一篇對不上就會漏發。記下所有發過的網址後,比對時就不用管文章是什麼時候、以什麼順序上線。

腳本從 RSS 的每一篇文章讀取 title、link、description 與 pubDate,清單檔只存一個 urls 陣列。每送出一則貼文,腳本就會把那篇文章的網址寫回清單,因此發送中途失敗時,已送出的文章不會在下一次重發。

語言檢查是為了避免設定接錯。英文 RSS 的網址都在 /en/ 底下,中文 RSS 的網址都不在。因此如果 workflow 把中文 RSS 接到英文頻道,第一篇文章就無法通過檢查,整批文章都會停止發送,英文頻道的訂閱者也不會收到中文貼文。

保存已發清單

已發清單存成 GitHub Actions 的 artifact,不 commit 回 repo。這樣 workflow 只需要讀取 repo 的權限,main 上也不會出現機器人產生的 commit。

每次執行開始時取回最新一份 artifact,結束時把更新後的清單上傳成新的 artifact,保留 90 天。中文與英文的清單是同一個 artifact 裡的兩個檔案,所以兩個語言在同一個 job 裡依序執行,不會同時寫入。只推播其中一種語言時,另一種語言的清單會原樣存回。

取回清單時,先用 GitHub 的 API 找出最新一份還沒過期的 artifact,再下載那次執行的檔案。這一步的 env 要把 GH_REPO 設成 ${{ github.repository }}、GH_TOKEN 設成 ${{ github.token }}:

1run_id=$(gh api "repos/$GH_REPO/actions/artifacts?name=telegram-announced&per_page=100" \
2  --jq '[.artifacts[] | select(.expired | not)] | sort_by(.created_at) | last | .workflow_run.id // empty')
3if [ -n "$run_id" ]; then
4  gh run download "$run_id" --name telegram-announced --dir state
5fi

取回失敗時兩個語言都不發文,也不上傳清單。如果這時照樣上傳,空的清單會蓋掉上一份,下一次執行就會當成第一次,把那段期間的新文章全部記為已發而不發出。

超過 90 天沒有執行時清單會過期,下一次執行就等於第一次執行。公開 repo 連續 60 天沒有任何活動時,GitHub 也會停用排程,這時要到 Actions 頁面重新啟用。

決定貼文格式

每篇文章用 Bot API 的 sendPhoto 發一則圖片貼文,圖片是文章頁 og:image 的封面,說明文字依序是粗體標題、摘要與文章連結:

1{
2  "chat_id": "@vervecode",
3  "photo": "https://vervecode.dev/workflow/astro-telegram-announce/thumbnail.png",
4  "caption": "<b>標題</b>\n\n摘要\n\n<a href=\"https://vervecode.dev/workflow/astro-telegram-announce/\">閱讀全文</a>",
5  "parse_mode": "HTML",
6  "disable_notification": false
7}

如果改用 sendMessage 發文字訊息,Telegram 會自動在訊息下方附上連結預覽卡,但預覽卡會把標題和摘要再顯示一次。發圖片貼文時,標題與摘要只會出現一次。

說明文字有幾個限制要處理:

  • 說明文字上限 1024 字,Telegram 計算時不含 HTML 標籤。
  • RSS 的摘要是 HTML,本站的摘要只會用到 <code>,因此保留 <code>、其他標籤都拿掉,<、> 與 & 要轉成 HTML 實體。
  • 讀不到 og:image、說明文字太長,或 Telegram 抓不到圖片回傳 400 時,改發附預覽卡的文字訊息,文章仍然會發出去。

一次有多篇新文章時,從舊到新每篇各發一則,每則間隔 3 秒。Telegram 的 Bot FAQ 建議同一個對話每秒不超過 1 則、群組每分鐘不超過 20 則,間隔 3 秒兩者都不會超過。仍然收到 429 時,如果回應裡的 retry_after 在 60 秒以內,就等待後重送一次。

除了最後發出的最新文章,前面的貼文都會加上 disable_notification。Telegram 的靜音是「有通知、沒有通知聲」,訂閱者的通知欄與未讀數仍然會出現這些貼文,只是一次上線三篇時只會響一次通知聲。

中英文分兩個頻道

中文與英文的讀者各自只想收到自己語言的文章,但 Bot API 發訊息時沒有語言參數,因此本站用頻道區分語言,中英文各開一個公開頻道,由同一個 Bot 發文:

項目 中文 英文
RSS /index.xml /en/index.xml
已發清單 announced.json announced-en.json
頻道 @vervecode @vervecode_en

貼文最後的連結文字,中文寫「閱讀全文」,英文寫「Read the full article」。兩邊的文章網址不同,第一次執行、補發與重送都要各自判斷,因此兩份清單分開記錄。英文版晚一天上線時,英文頻道會在下一次執行時才發文,中文頻道不受影響。

英文頁沿用中文縮圖時,英文頻道的貼文會出現中文標題,因此縮圖上有中文字的文章,本站會在英文版另外指定英文封面,og:image 也會跟著換成英文封面。

實作要點

建立 Bot 與頻道

Bot 與頻道都在 Telegram 裡建立:

  1. 對 @BotFather 傳送 /newbot,依序輸入 Bot 的顯示名稱與以 bot 結尾的使用者名稱,完成後 BotFather 會回傳一組 Token。
  2. 建立中文與英文兩個公開頻道,各設定一個使用者名稱,例如本站的 vervecode 與 vervecode_en。
  3. 再建立一個私人頻道當測試頻道,兩個語言共用。
  4. 在三個頻道的管理員設定加入 Bot,權限只開啟「Manage messages」底下的「Post messages」。

BotFather 最後一則回覆裡的 Token 是發文用的憑證,拿到 Token 的人都能用這個 Bot 發文,所以截圖或分享畫面時要遮住。截圖裡的 Bot 名稱是建立時的名稱,之後才改名並設定頭像,所以和下一張截圖不同:

和 BotFather 的對話:傳送 /newbot 後依序輸入顯示名稱 VerveCode.Dev Alert 與使用者名稱 vervecode_bot,最後一則回覆附上已遮住的 Token

Bot 的管理員權限只需要發文,「Manage messages」底下只勾選「Post messages」,其他權限都關閉:

頻道的 Admin rights 視窗,Manage messages 只勾選 Post messages,Change channel info、Add members 等其他權限都是關閉的

設定 repo 的 secret 與 variable

BotFather 回傳的 Token 存成 repository secret TELEGRAM_BOT_TOKEN。發文時還要用 chat_id 指定頻道,Bot API 的 chat_id 接受公開頻道的 @使用者名稱,因此兩個公開頻道不用另外查數字 ID。私人的測試頻道沒有使用者名稱,要用數字 ID。Bot 成為頻道管理員後,在測試頻道發一則訊息,再呼叫 Bot API 的 getUpdates,回應裡 channel_post.chat.id 的值就是這個 ID。

三個頻道的名稱不是機密,存成 repository variable:

名稱 本站的值
TELEGRAM_CHAT_ID @vervecode
TELEGRAM_EN_CHAT_ID @vervecode_en
TELEGRAM_TEST_CHAT_ID -100 開頭的測試頻道 ID

撰寫 workflow

workflow 用 schedule 與 workflow_dispatch 兩種觸發方式。GitHub 的 cron 用 UTC,台灣時間的 11:07 與 20:07 寫成 7 3,12 * * *。GitHub 在整點前後的排程比較擁擠,可能延遲幾分鐘到幾十分鐘,因此分鐘數避開整點。即使如此,本站排在 03:07 與 12:07(UTC)的執行,實際大多在 10 分鐘後才開始。

權限只開啟需要的三項:

權限 用途
contents: read checkout 推播腳本
actions: read 查詢與下載上一次的 artifact
issues: write 失敗時開 issue 或留言

job 依序執行這幾個步驟:

步驟 執行時機
checkout 推播腳本 每次都執行,用 sparse-checkout 只取腳本的資料夾
設定 Node.js 每次都執行,本站用 Node.js 26,內建 fetch
取回已發清單 只有發到正式頻道時
中文:比對並發文 沒有指定只推英文時
英文:比對並發文 前面沒有被取消、取回清單沒有失敗,而且沒有指定只推中文時
存回已發清單 取回清單成功又不是 dry run 時,即使前一步失敗也照樣上傳
失敗時開 issue 發到正式頻道失敗時,已有同名的 open issue 就改成留言

GitHub Actions 預設在前一步失敗時跳過後面的步驟,因此英文那一步的條件寫成 !cancelled(),中文失敗時英文仍然會執行。存回清單的步驟則寫成 always(),即使發送中途失敗,已寫進清單的網址也會上傳保存。任一步失敗時,整個 job 都會算失敗,並觸發開 issue 的步驟。

兩次執行同時寫入清單時,後上傳的那份會蓋掉先上傳的。concurrency 設成同一組,並把 cancel-in-progress 設成 false 後,排程和手動執行就不會同時執行,手動執行也不會取消正在發文的排程。

手動執行 workflow

正式頻道沒有測試模式,發出去的就是正式貼文,所以修改訊息格式或腳本後,先發到測試頻道確認。手動執行的參數如下:

參數 用途
target test 發到測試頻道,production 發到正式頻道
lang all、zh 或 en,只推其中一種語言時使用
dry_run 只把這次要發的文章寫進執行紀錄的 summary,不發文也不更新清單
test_count 發到測試頻道時要發最新幾篇,1 到 10 篇
since 日期寫成 YYYY-MM-DD,以台灣時間計算。只在沒有清單時生效,會把那天以後的文章當成新文章發出

發到測試頻道時不讀寫已發清單,直接發最新幾篇,因此測試不會影響正式頻道的判斷。要確認多篇時只有最新一篇有通知聲,可以用 GitHub CLI 發最新 3 篇到測試頻道:

1gh workflow run telegram-announce.yml -f target=test -f lang=en -f test_count=3

要看兩個正式頻道下一次會發哪些文章,用 dry_run:

1gh workflow run telegram-announce.yml -f target=production -f dry_run=true

不論是排程還是手動執行,執行紀錄的 summary 都會分中文與英文列出頻道、RSS 的文章數、已發清單的篇數與這次送出的篇數。下圖是一次沒有新文章的排程執行,兩個語言都是 78 篇已發、0 篇要發:

GitHub Actions 執行紀錄的 announce summary,中文與英文各一段,列出正式頻道、RSS 文章 78 篇、已發清單 78 篇、要發的文章 0 篇

排程只會執行預設分支上的 workflow。手動執行時,預設分支上也要有這個 workflow 檔,但可以用 --ref 指定開發分支,例如本站的 --ref draft,執行那個分支上修改過的 workflow 與腳本。這時同時指定 -f target=test,測試中的版本就只會發到測試頻道,不會發到正式頻道。

處理推播失敗

執行失敗時,workflow 會開一個「Telegram 新文章推播失敗」的 issue,原因寫在執行紀錄的 summary 與 log。常見的錯誤如下:

錯誤 原因
403 Forbidden Bot 不在頻道裡,或沒有發文權限
400 Bad Request: chat not found 頻道的 variable 寫錯
RSS 裡有其他語言的網址 RSS 網址或語言設定接錯
429 Too Many Requests 發送太快。retry_after 在 60 秒以內時,腳本會等待後重送一次。重送仍然失敗,或需要等待超過 60 秒時,這次發送就會失敗

總結

靜態網站推播新文章到 Telegram 時,只要以正式站的 RSS 為準,和存在 artifact 裡的已發清單比對,每篇文章就只會發出一次。中文與英文各自讀取 RSS、記錄清單,再發到各自的頻道。

此設計方案的優缺點統整如下:

  • 優點:推播只依賴正式站的 RSS,不論網站用什麼框架、部署在哪裡,只要有列出所有文章的 RSS,就能套用同一套做法。
  • 優點:中英文的清單與頻道分開,一邊設定錯誤或發送失敗時,另一邊仍然照常發文。
  • 缺點:貼文只在排程執行時發出,因此不適合需要文章一上線就通知讀者的網站。
  • 缺點:已發清單只保留 90 天,排程停止超過這段時間後,恢復時要手動補發中間的文章。
  • 可改善:在部署完成時觸發推播,就能縮短文章上線到發文的等待時間。

延伸閱讀

Ted Liou

Ted Liou

現役軟體工程師,分享 Unity 與 AI 的技術開發經驗。

留言