文章目錄

Telegram 頻道是讀者訂閱新文章的一種方式:已經在用 Telegram 的讀者加入頻道後,每次有新文章,就會收到一則附封面圖的貼文,不需要留下電子郵件。但 Astro 這類靜態網站的部署只會把檔案放上主機,文章上線後,沒有程式會去通知讀者。
只要讓 GitHub Actions 每天定時讀取正式站的 RSS,把還沒發過的文章送到頻道,再把已發的網址記下來,每篇新文章就會自動發出一次。網站有中英文版時,兩種語言各自讀自己的 RSS、記自己的清單,再發到各自的頻道。
本站在 2026 年 11 月拿掉 Web Push 的新文章通知後,改用這套設計推播新文章。中文文章發到 @vervecode,英文文章發到 @vervecode

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

設計
這套推播依照下面幾條規則設計:
- 每天固定兩次,在台灣時間 11:07 與 20:07 檢查有沒有新文章。從文章上線到發出貼文,最久大約要等 15 小時。
- 以正式站的 RSS 為準,RSS 裡出現了、清單上還沒有的文章才算新文章。
- 每篇文章只發一次。發送中途失敗時,已發出的文章不會重發,沒發出的下一次再發。
- 第一次執行時不發任何文章,避免把網站上所有舊文一次推出去。
- 中文與英文各用一個公開頻道,讀者只訂閱自己讀的語言。
- 已發清單不 commit 回 repo,也不需要另外架設伺服器或資料庫。
流程
GitHub Actions 的排程觸發後,中文與英文在同一個 job 裡依序各跑一次,各自讀取 RSS、比對並發文,最後一起存回清單:
圖上是發到正式頻道的流程。發到測試頻道或用 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,pub 則是轉成 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 與 pub,清單檔只存一個 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 設成 ${{ github、GH 設成 ${{ github:
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 的 send 發一則圖片貼文,圖片是文章頁 og: 的封面,說明文字依序是粗體標題、摘要與文章連結:
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}
如果改用 send 發文字訊息,Telegram 會自動在訊息下方附上連結預覽卡,但預覽卡會把標題和摘要再顯示一次。發圖片貼文時,標題與摘要只會出現一次。
說明文字有幾個限制要處理:
- 說明文字上限 1024 字,Telegram 計算時不含 HTML 標籤。
- RSS 的摘要是 HTML,本站的摘要只會用到
<code>,因此保留<code>、其他標籤都拿掉,<、>與&要轉成 HTML 實體。 - 讀不到
og:、說明文字太長,或 Telegram 抓不到圖片回傳 400 時,改發附預覽卡的文字訊息,文章仍然會發出去。image
一次有多篇新文章時,從舊到新每篇各發一則,每則間隔 3 秒。Telegram 的 Bot FAQ 建議同一個對話每秒不超過 1 則、群組每分鐘不超過 20 則,間隔 3 秒兩者都不會超過。仍然收到 429 時,如果回應裡的 retry 在 60 秒以內,就等待後重送一次。
除了最後發出的最新文章,前面的貼文都會加上 disable。Telegram 的靜音是「有通知、沒有通知聲」,訂閱者的通知欄與未讀數仍然會出現這些貼文,只是一次上線三篇時只會響一次通知聲。
中英文分兩個頻道
中文與英文的讀者各自只想收到自己語言的文章,但 Bot API 發訊息時沒有語言參數,因此本站用頻道區分語言,中英文各開一個公開頻道,由同一個 Bot 發文:
| 項目 | 中文 | 英文 |
|---|---|---|
| RSS | /index.xml |
/en/index.xml |
| 已發清單 | announced.json |
announced-en.json |
| 頻道 | @vervecode |
@vervecode_en |
貼文最後的連結文字,中文寫「閱讀全文」,英文寫「Read the full article」。兩邊的文章網址不同,第一次執行、補發與重送都要各自判斷,因此兩份清單分開記錄。英文版晚一天上線時,英文頻道會在下一次執行時才發文,中文頻道不受影響。
英文頁沿用中文縮圖時,英文頻道的貼文會出現中文標題,因此縮圖上有中文字的文章,本站會在英文版另外指定英文封面,og: 也會跟著換成英文封面。
實作要點
建立 Bot 與頻道
Bot 與頻道都在 Telegram 裡建立:
- 對 @BotFather 傳送
/newbot,依序輸入 Bot 的顯示名稱與以bot結尾的使用者名稱,完成後 BotFather 會回傳一組 Token。 - 建立中文與英文兩個公開頻道,各設定一個使用者名稱,例如本站的
vervecode與vervecode。_en - 再建立一個私人頻道當測試頻道,兩個語言共用。
- 在三個頻道的管理員設定加入 Bot,權限只開啟「Manage messages」底下的「Post messages」。
BotFather 最後一則回覆裡的 Token 是發文用的憑證,拿到 Token 的人都能用這個 Bot 發文,所以截圖或分享畫面時要遮住。截圖裡的 Bot 名稱是建立時的名稱,之後才改名並設定頭像,所以和下一張截圖不同:

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

設定 repo 的 secret 與 variable
BotFather 回傳的 Token 存成 repository secret TELEGRAM。發文時還要用 chat 指定頻道,Bot API 的 chat 接受公開頻道的 @使用者名稱,因此兩個公開頻道不用另外查數字 ID。私人的測試頻道沒有使用者名稱,要用數字 ID。Bot 成為頻道管理員後,在測試頻道發一則訊息,再呼叫 Bot API 的 get,回應裡 channel 的值就是這個 ID。
三個頻道的名稱不是機密,存成 repository variable:
| 名稱 | 本站的值 |
|---|---|
TELEGRAM_CHAT_ID |
@vervecode |
TELEGRAM_EN_CHAT_ID |
@vervecode_en |
TELEGRAM_TEST_CHAT_ID |
-100 開頭的測試頻道 ID |
撰寫 workflow
workflow 用 schedule 與 workflow 兩種觸發方式。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:
1gh workflow run telegram-announce.yml -f target=production -f dry_run=true
不論是排程還是手動執行,執行紀錄的 summary 都會分中文與英文列出頻道、RSS 的文章數、已發清單的篇數與這次送出的篇數。下圖是一次沒有新文章的排程執行,兩個語言都是 78 篇已發、0 篇要發:

排程只會執行預設分支上的 workflow。手動執行時,預設分支上也要有這個 workflow 檔,但可以用 --ref 指定開發分支,例如本站的 --ref draft,執行那個分支上修改過的 workflow 與腳本。這時同時指定 -f target=,測試中的版本就只會發到測試頻道,不會發到正式頻道。
處理推播失敗
執行失敗時,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 天,排程停止超過這段時間後,恢復時要手動補發中間的文章。
- 可改善:在部署完成時觸發推播,就能縮短文章上線到發文的等待時間。
