Hugo 實戰技巧：為什麼設定了「未來日期」文章沒顯示？教你用 GitHub Actions 實現全自動定時發布

最近在撰寫網站文章內容時，我遇到一個有趣的問題。

我在文章的 Front Matter（頂部配置）中，將日期設定為了未來的一天： date: 2026-01-04

我的本意是希望 到了 1 月 4 日那天，這篇文章自動出現在首頁。結果日子到了，我重新整理了無數次網站，文章卻依然處於「隱身」狀態。

這到底是為什麼？難道 Hugo 壞了嗎？

經過一番研究，我發現這其實是靜態網站產生器 (Static Site Generator) 的核心特性決定的。今天就來分享一下原理，以及如何用 GitHub Actions 完美解決這個問題。

1. 原理揭秘：為什麼它不會「自動」顯示？

要理解這個問題，我們必須區分 「動態網站」（如 WordPress）和 「靜態網站」（如 Hugo）。

• WordPress (動態): 當你造訪網頁時，伺服器會即時查詢資料庫。如果它發現有一篇文章的發布時間是「現在」，它就會立刻從資料庫裡撈出來展示給你。
• Hugo (靜態): Hugo 沒有資料庫。當你執行 hugo build 命令時，它就像印刷報紙一樣，把那一瞬間的內容「列印」成 HTML 檔案。

關鍵點來了： 當 Hugo 進行建構（Build）時，它會檢查每篇文章的日期。

• 如果 文章日期 > 當前建構日期，Hugo 會認為這是一篇「未來文章」，預設直接跳過，不產生它的 HTML 檔案。

所以，即使時間到了 2026 年 1 月 4 日，伺服器上存放的依然是 1 月 3 日建構的舊版 HTML。除非你重新執行建構命令，否則那篇文章永遠不存在於伺服器上。

2. 常見的（但不太完美）解決方案

方案 A：手動建構 (最原始)

等到日子到了，打開電腦，手動推送一次程式碼，或者去 Cloudflare 後台點一下「重新部署」。

• 缺點： 耗時費力。萬一你當時在睡覺、在旅遊或者沒網路，文章就發不出來了。

方案 B：強制顯示未來文章 (Build Future)

你可以在 hugo.yaml 中設定 buildFuture: true。

• 缺點： 這會讓文章現在立刻顯示出來，不管日期是不是未來。這適合預覽草稿，但不適合「定時發布」。

3. 終極方案：GitHub Actions 定時自動建構 🤖

我們要實現的是：人可以睡覺，但程式碼必須自動上工。

我們可以利用 GitHub Actions 的排程工作 (Cron Job) 功能，每天早上自動「戳」一下 Cloudflare，告訴它：「嘿，重新建構一下網站，看看有沒有新文章到了發布時間。」

name: Scheduled Build (定時建構)

on:
  schedule:
    # 這裡的語法是 Cron 表達式
    # '0 0 * * *' 代表每天 UTC 時間 00:00 (台灣時間早上 8:00) 自動執行
    - cron: '0 0 * * *'
  # 同時也允許你在 GitHub 網頁上手動點擊按鈕觸發
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Cloudflare Pages Build
        # 使用 curl 命令向 Cloudflare 發送請求
        # 請將下面的 URL 換成你第一步裡取得的真實 URL
        run: curl -X POST "https://api.cloudflare.com/client/v4/pages/webhooks/deploy_hooks/YOUR_HOOK_ID_HERE"

✅ 效果驗收

從現在開始，GitHub 會在每天早上 8 點自動執行這個腳本。

1. 腳本發送信號給 Cloudflare。
2. Cloudflare 重新拉取程式碼並執行 hugo。
3. Hugo 發現：「咦，今天是 1 月 4 日了，那篇設定為 4 日的文章不再是未來文章了！」
4. Hugo 產生該文章的 HTML。
5. 文章自動上線。

這就實現了真正的 「定時發布」（Scheduled Publishing）。現在，你可以一次性寫好一週的文章，設定好不同的日期，然後放心地去度假了！🏖️

延伸閱讀