Astro Content Collection 太大怎麼辦？用 collectionStorage 分塊儲存

先分清楚是哪一種「太大」#

Content Collection 的資料、建置記憶體和部署資產是三個不同邊界，不應用同一個設定處理：

先在建置後查看實際輸出，不要看到文章數變多就直接加實驗旗標：

1
du -h .astro/data-store.json 2>/dev/null || true
2
find .astro/data-store -maxdepth 1 -type f -print 2>/dev/null

如果專案使用 Content Loader，base 和 pattern 仍然決定哪些資料會進 collection；可以先參考 Astro Content Loader 的 glob() 設定，不要把儲存分塊誤當成輸入範圍設定。

用最小設定切換成 chunked#

在 astro.config.mjs 加入：

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  experimental: {
5
    collectionStorage: 'chunked',
6
  },
7
});

Astro 官方文件將預設值列為 single-file，也就是把資料寫在 .astro/data-store.json；chunked 則會寫入 .astro/data-store/。目前文件列出的分塊行為是：當目前 chunk 大於 20 MB 時建立下一個檔案。這是 Astro 的生成邏輯，不等於你的部署平台一定允許 20 MB 單檔，因此仍要用實際 host 限制反推設定。

這項設定從 [email protected] 開始提供，而且仍標示為 experimental。若專案還在 Astro 5 或 6，不要只把設定貼進去期待舊版能理解；先依 Astro 7 升級清單 完成版本與 adapter 檢查，再在獨立變更中驗證 collection。

平台有更小限制時指定 chunkSize#

若部署平台的個別資產上限低於預設分塊大小，可以使用 object form。chunkSize 的單位是 bytes，下面示範約 1 MiB：

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  experimental: {
5
    collectionStorage: {
6
      type: 'chunked',
7
      chunkSize: 1024 * 1024,
8
    },
9
  },
10
});

不要把數字剛好設在平台上限。壓縮方式、metadata 和未來內容成長都可能讓部署行為和本機檔案大小不同；應保留可解釋的安全餘裕。另一方面，chunkSize 太小會產生更多檔案，增加部署與讀取的管理成本，所以只在平台有明確限制時才調小。

建置後驗證 adapter 真的帶上所有 chunk#

改設定後，至少做一次乾淨建置並檢查輸出：

1
rm -rf .astro
2
pnpm exec astro build
3
find .astro/data-store -maxdepth 1 -type f -print
4
du -h .astro/data-store/*

接著在預覽或 staging 驗證：

1. .astro/data-store/ 是否真的有多個檔案。
2. 沒有任何 chunk 超過 hosting 平台的個別檔案限制。
3. 使用 adapter 的部署產物仍包含所有 data store 檔案。
4. 會呼叫 getCollection() 或 getEntry() 的頁面仍能正常產生。
5. 從乾淨 checkout 重跑時，結果與本機相同。

「本機 build 成功」只證明 Astro 能產生檔案，不能證明 adapter 或部署工具會把新資料夾完整上傳。若頁面在部署後仍缺資料，應獨立檢查 adapter 的 packaging，不要回頭把問題歸因於 collection schema。

這個設定不會解決哪些問題#

collectionStorage 只改變資料寫入方式，以下情況仍要走自己的排查路徑：

• loader 一次讀取太多遠端資料，造成記憶體或網路問題。
• schema 欄位不符合，導致 build 在資料驗證階段停止。
• 頁面 HTML、圖片或 client bundle 本身超過平台限制。
• adapter 沒有把 .astro/data-store/ 視為需要部署的輸出。
• content entry ID、路由或 render 流程本身錯誤。

如果實際問題是「大型 collection 讓 build 記憶體升高」，先量測 loader 與渲染流程；切成多個 data store 檔案不會自動讓解析 Markdown 或產生 HTML 變便宜。

回滾方式與判斷結論#

要回到單檔儲存，可以移除實驗設定，或明確寫回：

1
export default defineConfig({
2
  experimental: {
3
    collectionStorage: 'single-file',
4
  },
5
});

實務上的判斷順序是：單一 data store 檔案超限才用 chunked；平台有更小的個別檔案上限才設定 chunkSize；部署後缺資料則檢查 adapter 產物。這樣能把 storage layout、內容載入與部署封裝三件事分開驗證。

常見問題#