Cloudflare Pages 的 Astro 檔案數超過怎麼辦？先分清 Pages 與 Workers

先量 dist/，不要只數 Markdown#

在與部署相同的 Node、套件和 build command 下執行：

1
pnpm build
2
find dist -type f | wc -l
3
du -sh dist
4
find dist -type f -size +25M -print

第一個數字是要和平台檔案數比較的起點。du -sh 只能看總磁碟大小，不能代替檔案數限制；最後一個指令則找出可能超過單檔限制的資產。要特別注意 sitemap、分頁、圖片轉檔、source map 和每一篇預先產生的 HTML，因為它們都會成為 dist/ 的檔案。

Pages、付費 Pages 與 Workers Static Assets 怎麼選#

如果只是把大批內容預先渲染成 HTML，先問「是否真的每頁都要在 build time 產生」。改變生成策略可能降低檔案數，但也可能把成本與故障點移到 Worker runtime；這不是單純的部署設定替換。

純靜態 Astro 不必先加 Cloudflare adapter#

Cloudflare 的 Astro 文件把兩種輸出分得很清楚：純預先產生的 Astro site 可以直接把 dist/ 當 static assets 提供，不必安裝 @astrojs/cloudflare；需要 on-demand rendering 或 Cloudflare bindings 時，才使用 adapter 和 Worker script。

若選擇 Workers Static Assets，設定可以是這樣：

1
{
2
  "name": "my-astro-site",
3
  "compatibility_date": "2026-08-18",
4
  "assets": {
5
    "directory": "./dist",
6
    "not_found_handling": "404-page"
7
  }
8
}

assets.directory 必須指向實際的 Astro build output。not_found_handling 也要按路由需求選擇；靜態內容網站不應為了「看起來像成功」就任意使用 SPA fallback，否則遺失的頁面可能被回傳成首頁。

如果網站本來就需要 sessions 或 Cloudflare bindings，請把它當成另一種輸出模型來驗證。Cloudflare 的 adapter 預設會把 Astro 設成 output: 'server'，頁面轉由 Worker 在 request time 處理；這和把 dist/ 上傳成靜態檔案不是同一條部署路徑。

從 Pages 搬到 Workers 時要換設定層#

Pages 的 build output 設定與 Workers Static Assets 的設定名稱不同。Pages 可能使用：

1
{
2
  "name": "my-pages-project",
3
  "pages_build_output_dir": "./dist"
4
}

搬到 Worker 專案後，要改成 assets.directory，並用 wrangler deploy 走新的部署流程。切換前依序確認：

1. 記下原本 Pages 的 build command、output directory 和自訂 domain。
2. 在本機執行 pnpm build，確認 dist/ 目錄與實際部署一致。
3. 只在改用 Workers Static Assets 時，把 pages_build_output_dir 換成 assets.directory。
4. 為 preview 使用明確的 compatibility date，並檢查 404、redirect、HTML、CSS 和圖片路徑。
5. 先部署非正式環境，確認代表性網址後再切換 domain。

如果問題是單一 .astro/data-store.json 或其他生成資料過大，可以參考 Astro Content Collection 用 collectionStorage 分塊儲存。那能處理特定輸出檔過大的問題，但不會改變 Cloudflare 的總檔案數上限；若問題是 deploy 後多出不需要的 SESSION binding，則看 Astro Cloudflare 的 session: false 邊界。

把「檔案限制」和「SSR 需求」分開判斷#

這次錯誤如果只是 20,000 個檔案，第一個修正方向是量測和控制生成輸出；如果網站需要登入、個人化頁面、KV、D1、R2 或 AI binding，則要重新評估 runtime。不要因為 static upload 失敗，就直接把所有頁面改成 on-demand rendering，也不要因為想保留靜態部署，就把必要的 server logic 硬塞進 build time。

判斷順序可以固定成：數檔案 → 查單檔大小 → 判斷是否純靜態 → 再選 Pages 或 Workers 的輸出模型。 這樣平台選擇是由實際需求驅動，而不是被第一個錯誤訊息牽著走。

常見問題#