Astro 部落格文章 404 不是沒部署：GitHub 手動貼文時，frontmatter 寫錯就會消失

今天這篇不是在講大型 AI 系統，也不是在講抽象的網站治理，而是一個非常具體的手動貼文事故。

我們在 printapp.uk 的 GitHub 後台新增一篇文章。

檔案名稱看起來正確。

資料夾位置也正確。

文章內容也已經貼進去。

但是打開預期網址時，瀏覽器卻顯示：

HTTP ERROR 404

網址是對的，文章卻不存在。

這種情況很容易讓人誤判成 Cloudflare Pages 沒部署、GitHub 沒 commit、網址拼錯，或是網站快取還沒更新。

但最後真正的問題不是這些，而是文章最上方的 frontmatter 欄位格式不符合現有網站規則。

也就是說：檔案有在 repo 裡，但 Astro 沒有用正確方式把它變成公開文章。

這個案例很適合記下來，因為小企業自己用 GitHub 管理靜態網站時，這種錯誤非常常見，而且很容易浪費時間。

當時看到的症狀

這次新增的文章預期網址是：

https://printapp.uk/blog/ai-line-customer-service-before-launch-checklist/

但打開後是 404。

接著檢查 /blog/ 列表，發現新文章也沒有出現。

這代表問題不是單純文章頁面連結錯誤，而是網站的文章資料來源沒有正確吃到這篇文章。

如果文章已經成功被 Astro 讀取，通常至少會出現在文章列表裡。就算個別頁面有路由問題，列表也可能看得到標題。

但這次列表和文章頁都沒有。

這時候排查方向就要從「網址是不是打錯」改成「這篇 markdown 有沒有被網站內容系統收進去」。

第一個容易誤判的地方：以為檔案放錯位置

Astro 靜態網站常見的部落格結構，文章通常會放在類似這樣的位置：

src/content/blog/

這次一開始也懷疑是不是檔案放錯地方。

例如放到 repo 根目錄、放到 src/pages、放到錯的資料夾，或檔名副檔名不是 .md。

後來看 GitHub 截圖確認，檔案確實在正確位置：

src/content/blog/ai-line-customer-service-before-launch-checklist.md

所以「放錯資料夾」可以排除。

這一步很重要。

因為如果檔案根本不在 src/content/blog/，那就不用再看 frontmatter、Cloudflare 或路由，先移到正確資料夾即可。

但這次資料夾是對的，所以問題往下一層查。

第二個容易誤判的地方：以為 Cloudflare Pages 還沒部署

GitHub 後台手動 commit 後，Cloudflare Pages 通常會自動 build 與部署。

如果新文章沒出現，很自然會懷疑 Cloudflare 還沒更新。

這個方向也要查，但不能一開始就咬定是 Cloudflare 問題。

比較好的判斷方式是：

第一，看 GitHub 是否真的 commit 到 main branch。

第二，看 Cloudflare Pages 最新 deployment 是 Success 還是 Failed。

第三，看 /blog/ 列表是否有任何新內容。

第四，看既有舊文章是否正常開啟。

如果舊文章正常，新文章沒有，通常代表整個網站不是壞掉，而是新文章沒有被納入內容集合。

這次既有文章可以正常打開，所以網站路由本身沒有全面壞掉。

真正的問題：frontmatter 欄位不符合網站格式

這次關鍵在文章最上方的 --- 區塊。

一開始使用的欄位比較像其他網站常見格式：

pubDate

description

tags

summaryCode

但 printapp.uk 現有文章格式使用的是：

title

date

summary

code

category

Astro 的內容集合通常會依照 schema 或程式碼讀取特定欄位。如果欄位名稱不符合，可能造成 build 失敗，也可能造成文章資料不完整，最後文章沒有正確出現在列表與路由裡。

這種問題最麻煩的地方是：文章內容本身看起來沒有錯。

標題正常。

內文正常。

檔名正常。

路徑正常。

但網站要讀的 metadata 不對。

對一般人來說，就像文件明明存在，系統卻說找不到。

正確的 frontmatter 應該長這樣

後來修正成這種格式後，文章就能正常上線。

開頭應該包含這些欄位：

title: "文章標題"

date: "2026-05-22"

summary: "文章摘要"

code: "AI-LINE-001"

category: "客服與資料流程觀察"

這裡有幾個重點。

date 要用網站既有格式，不要自己改成 pubDate。

summary 要用網站列表會讀的欄位，不要改成 description。

code 要照現有文章使用方式，不要改成 summaryCode。

category 要保留，讓文章能進入正確分類。

這不是哪個格式比較好看的問題，而是目前網站程式已經認哪一組欄位。

在沒有修改 Astro schema 或文章列表程式前，手動貼文就要照現有格式走。

為什麼全選複製也會出錯？

這次還有另一個小坑：使用者不想用滑鼠全選整段文字，因為全選容易選到聊天介面其他內容，或漏掉文章開頭與結尾。

所以後來貼文流程改成每一段都要提供可直接按 Copy 的區塊。

至少要分成四個可複製項目：

檔名。

貼到的 repo 路徑。

完整 markdown 文章。

發布後公開網址。

這個細節看起來很小，但對手動 GitHub 發文很重要。

因為只要檔名少一個字、路徑貼錯、frontmatter 少一個 ---，整篇文章就可能失敗。

小企業自己維護網站時，很多錯誤不是不懂技術，而是複製貼上過程太容易出錯。

所以流程設計要讓人少犯錯，而不是要求人每次都小心到完美。

文章內不要再放三個反引號範例

這次修正版還補了一個新的規則：在提供給人直接複製的文章內容裡，盡量不要再放三個反引號 code fence 範例。

原因是 ChatGPT 回覆本身也使用 code block 給使用者按 Copy。

如果文章內又放一組三個反引號，有時候複製或顯示時會把外層 markdown 區塊提前截斷，導致使用者只貼到半篇文章。

這次原本的文章就發生這種問題。

公開頁面只顯示到「正確的 frontmatter 長什麼樣？」附近，後面內容沒有完整出現。

所以後續在 AI網站 printapp.uk 手動貼文時，若文章要說明程式碼或 frontmatter，會優先使用：

行內程式碼，例如 title、date、summary。

條列文字。

縮排說明。

不要在可複製的整篇文章裡再包一層三個反引號。

這不是 markdown 本身不能用，而是手動貼文流程要避免複製截斷風險。

GitHub 後台手動貼文的穩定流程

這次修正後，可以整理出比較穩的手動貼文流程。

第一，進入 GitHub repo。

第二，打開：

src/content/blog/

第三，新增 .md 檔案。

第四，檔名只用英文小寫、數字與連字號。

第五，文章最上方先貼正確 frontmatter。

第六，確認欄位使用：

title / date / summary / code / category

第七，貼完整內文。

第八，Commit directly to the main branch。

第九，Extended description 可以留空。

第十，等待 Cloudflare Pages 部署完成。

第十一，開公開網址確認文章是否上線。

這套流程不複雜，但欄位格式一定要一致。

如果每次用不同 frontmatter，網站就會變得不穩。

404 排查順序不要亂

遇到新文章 404，可以照這個順序查。

先查網址 slug 是否和檔名一致。

例如檔名：

astro-blog-404-frontmatter-github-cloudflare.md

通常公開網址會是：

/blog/astro-blog-404-frontmatter-github-cloudflare/

再查檔案是否在：

src/content/blog/

再查 frontmatter 是否符合現有文章格式。

再查 GitHub 是否 commit 到 main。

再查 Cloudflare Pages deployment 是否成功。

最後才查 Astro route 或程式碼。

很多人會一開始就跳去查 Cloudflare 或改程式碼，結果問題其實只是 markdown 最上方欄位錯了。

排查順序錯，會讓簡單問題變成大工程。

這次事故留下的流程修正

這次不是只修好一篇文章，而是修掉一個貼文流程缺口。

後續 printapp.uk 手動貼文固定要求：

檔名要給可複製區塊。

路徑要給可複製區塊。

完整文章要給可複製區塊。

發布後網址要給可複製區塊。

frontmatter 固定使用：

title

date

summary

code

category

不再使用：

pubDate

description

tags

summaryCode

除非未來真的修改網站 schema，否則不要臨時換格式。

這樣做的目的不是把流程變得死板，而是降低手動貼文時的錯誤率。

小企業網站維護最怕的是「看起來都有做」

這次 404 很有代表性。

因為每一步看起來都做了。

文章寫了。

檔案建了。

路徑放了。

GitHub commit 了。

網址也照規則打了。

但只要 metadata 格式錯，最後公開網站還是找不到。

這就是小企業自己維護靜態網站時很常遇到的問題：不是沒有做，而是其中一個細節沒有符合系統期待。

所以網站發文流程不能只靠記憶。

要把格式、路徑、欄位、網址、部署確認都固定下來。

尤其當文章開始增加，手動貼文次數變多時，這些小規則會直接影響網站維護成本。

結論：404 不一定是部署失敗，先看文章格式

這次 printapp.uk 的手動貼文 404，最後不是靠大改網站解決，而是把 frontmatter 改回現有格式。

這個案例提醒我：Astro 靜態網站的文章檔案，不是只要 markdown 內容存在就好，還要符合網站讀取內容的規則。

GitHub 後台手動貼文很方便，但前提是格式要穩。

Cloudflare Pages 自動部署很方便，但它不會替你判斷文章欄位是不是你真正想要的格式。

下次如果新增文章後出現 404，我會先查三件事：

檔案位置對不對。

frontmatter 欄位對不對。

Cloudflare deployment 是否成功。

照這個順序查，通常可以比盲目重貼文章、重跑部署、亂改 route 更快找到原因。