實作文章
Cloudflare Pages 部署錯誤點排查？5 個高頻問題（含 ENOENT）即查即修
部署失敗唔可怕，可怕係唔知由邊度查。
呢篇用你喺 Cloudflare 畫面會見到咩嚟講，整合最常見嘅 5 個錯誤，等你可以用最短時間定位問題。
唔使熟晒指令：你只要識得睇部署紀錄（Deployment log）入面嘅紅色錯誤，同對照下面嘅「畫面設定」就得。
先講結論：90% 都係「三個設定」
喺 Cloudflare Pages 專案入面，每次部署前請確認：
| 設定項目（英文介面） | Astro 一般填咩 | 填錯會點 |
|---|---|---|
| Root directory（專案路徑） | 若 Astro 喺子資料夾，填該資料夾名；若在 repo 根目錄就留空 | 搵唔到 package.json，出現 ENOENT |
| Build command（建置指令） | npm run build | 建置一開始就失敗 |
| Output directory（輸出資料夾） | dist | 建置成功但網站係空白或部署失敗 |
下面逐個錯誤對症下藥。
錯誤 1：搵唔到 package.json（ENOENT）
你會見到咩
部署紀錄出現類似字句：
npm error enoentCould not read package.json
白話：Cloudflare 去錯咗資料夾搵檔案，好似入錯房。
最常見原因
Root directory（專案路徑）填錯。
例如你個 GitHub repo 入面，真正嘅 Astro 專案喺 strong-nebula 子資料夾，但 Cloudflare 仍以 repo 最外層做建置。
點改（跟畫面做）
- 打開 Cloudflare → Workers & Pages → 揀你個專案
- 入 Settings → Build（或 Build configuration）
- 搵 Root directory / Path
- 改成 Astro 專案實際所在嘅資料夾名（只有一層就填嗰個名；若在根目錄就留空）
- 儲存後，按 Retry deployment 再部署一次
點樣確認填啱： 喺 GitHub 網頁打開 repo，睇 package.json 同 astro.config 喺邊一層；Cloudflare 就要指向同一層。
錯誤 2：建置指令一開始就失敗
你會見到咩
紀錄顯示 npm run build（或類似）未跑完就 fail。
常見原因
- 專案根本未設定「建置」步驟
- 本機用 npm、雲端用 yarn（或相反），鎖定檔不一致
點改
- 喺 GitHub 打開你 repo 嘅
package.json - 確認入面有
"build": "astro build"（或你專案實際用緊嘅建置指令） - Cloudflare Build command 填
npm run build（若你全程用 npm） - 本機先成功建置一次：喺 Cursor 開專案，用內建終端或請 Cursor 幫你執行「建置專案」；本機過到、雲端先至值得再查設定
錯誤 3：輸出資料夾填錯
你會見到咩
建置顯示成功，但部署階段話搵唔到輸出，或者上線後係空白頁。
原因
Astro 預設會把建置好嘅靜態檔案放入 dist 資料夾；若 Cloudflare Output directory 填咗其他名，就會對唔上。
點改
- Output directory 填
dist（多數 Astro 專案都係） - 改完再部署一次
錯誤 4：某篇文章令全站建置失敗
你會見到咩
紀錄提到某篇 .md / .mdx，話欄位缺失、類型錯、或日期格式唔啱。
原因
你哋網站對「文章頂部設定」有最低要求（例如一定要有 title、description、pubDate），有一篇漏咗就會拖死成個部署。
點改
打開紀錄指名嗰篇文章，確認最頂 --- 區塊至少有：
---
title: 文章標題
description: 一句話描述
pubDate: 2026-04-22
---日期建議用 YYYY-MM-DD。改好 → 上傳到 GitHub → 等 Cloudflare 自動再部署。
想減少呢類錯，可以跟《非工程背景點管理 Astro 文章》入面嘅發佈前檢查清單。
錯誤 5：部署成功，但網址唔係你想要嘅網域
你會見到咩
網站喺 xxxx.pages.dev 或 *.workers.dev 開到，但唔係你自己買嘅網域。
原因
呢個多數唔算失敗：Cloudflare 會先俾一個測試網址；你未綁 Custom domain（自訂網域），或者 DNS 仍在傳播中。
點改
- 專案 Settings → Domains → Add custom domain
- 按 Cloudflare 指示喺網域註冊商改 DNS
- 等數分鐘到數小時（視乎 DNS 傳播）
詳細步驟可跟《Cloudflare Pages 綁自訂網域清單》。
實用排查順序（由快到慢）
跟住呢個次序，可以避免一開始就糾結 DNS：
- 專案路徑（Root directory）
- 建置指令（Build command）
- 輸出資料夾（Output directory）
- 文章頂部設定有冇漏欄位
- 最後先處理自訂網域 / DNS
記住：本機建置成功 + 雲端失敗 = 九成係 Cloudflare 設定，唔係 Astro 壞咗。
咩嘢情況下建議搵人睇一次？
下面呢篇係通用教學；如果你符合其中一兩項，用 30 分鐘診斷對一次現況，通常會快過自己試錯堆砌設定。
- 你跟過文內步驟，仍然困喺同一個錯誤迴圈，而且已經用咗預期以外嘅時間（例如超過一個工作天）。
- 牽涉多個帳戶、DNS、寄信驗證（SPF／DKIM）或幾個服務交界，你想一次過排好優先次序同風險。
- 你想將做法接到實際業務流程（表單、名單、漏斗），而唔止係跟住教學跑通 demo。
結語
Cloudflare Pages 本身已經好穩定；
大部分失敗都係設定層面，而唔係平台壞。
你只要有一套固定排查流程，下次 deploy 出問題都可以幾分鐘內搞掂。
常見搜尋問法
- ENOENT
package.json點解最常見？
大多數都係專案路徑設錯，Cloudflare 喺錯資料夾跑建置。 - 本機可 build，但雲端 fail，代表乜？
通常係部署設定問題（路徑 / 建置指令 / 輸出資料夾），唔係 Astro 本身壞。 - 部署成功但唔係自訂網域，是否失敗？
唔係；測試網址係正常步驟，綁網域同等 DNS 傳播就會切到正式網域。 - 點降低之後再中伏機率？
把上面三個設定做成 checklist，每次部署照單核對。
下一步
同類上線排查可對照 MVP 上線與部署案例，想睇更多工具／內容站落地可瀏覽 案例目錄。
常見問題 FAQ
ENOENT package.json 幾乎都係乜原因？
大多數情況係「專案資料夾路徑」設錯，Cloudflare 喺錯位置執行建置。
點樣最快確認係設定問題而唔係平台問題？
先喺本機用 Cursor 或編輯器預覽成功建置一次；本機正常而雲端失敗，通常就係 Cloudflare 部署設定問題。
每次部署前最少要檢查咩？
檢查三樣：建置指令、輸出資料夾、專案路徑。呢三樣啱咗，成功率會高好多。
About me
你好，我係阿丸。呢度以數位主權為核心，分享點樣用 AI 幫手整網頁、建立吸客贈品頁、整理內容同上線作品， 目標係幫你用更短時間把內容同網站做成可帶走、可維護嘅自有資產。
我會持續更新可跟做嘅教學、踩坑記錄同流程模板，等你唔使被平台黑盒綁死，亦唔使再由零重複試錯。
同時呢度會多寫一人公司最常遇到嘅訂閱制現實：工具加價、用量隱形成本、平台綁定風險， 同埋點樣用可執行嘅做法，將名單、主站同漏斗慢慢揸返喺自己手度。
你會見到嘅內容包括：支出檢視框架、用量上限與警報、搬遷前準備同主權策略；目標唔係一夜換晒工具， 而係先止血，再建立長期可維護嘅自有資產。
想先攞可跟做模板同檢查清單？
先由免費吸客贈品包開始，將文章做法變成你可即用嘅落地清單，再按需要對照服務範圍安排下一步。
想睇合作模式同交付範圍，可先睇服務與合作方式。