Astro incremental build 怎麼用？用 incrementalBuild 與 cacheKey 減少重建

先確認這個功能適合你的 route#

Incremental static builds 針對的是 prerendered static pages。比較適合的路徑通常有以下特徵：

• getStaticPaths() 會產生很多文章、文件或產品頁。
• 每個 path 都有可以判斷資料是否變動的 digest、版本或時間戳。
• CI 能夠在兩次 build 之間保存 Astro 的 cache directory。
• 團隊願意在 experimental 功能上線前，用輸出差異做回歸。

如果頁面是 SSR、每次 request 都依賴即時資料，或路徑的輸出來源沒有可靠的變更 key，就不要先把它標成「可以安全跳過」。本文的設定範例聚焦靜態內容 route；Astro 7 的整體升級風險可以參考 Astro 7 升級前的 compiler、Vite 與 Markdown 清單。

在 astro.config.mjs 開啟 incrementalBuild#

先確認專案已升到 Astro 7.2 或更新版本，再在 astro.config.mjs 加入旗標：

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

3
export default defineConfig({
4
  experimental: {
5
    incrementalBuild: true,
6
  },
7
});

Astro 官方使用的是 incrementalBuild 單數名稱，不是 incrementalBuilds。如果設定寫錯，請先以安裝版本的 configuration reference 和 build log 為準，不要靠猜測的旗標名稱繼續排查 cache。

開啟旗標本身不會讓每一條 route 都開始重用。下一步必須在 route 的 getStaticPaths() 為每個 path 提供 cacheKey；這個設計讓你可以逐條 route 進入 experimental 行為，而不是一次改變整個網站的失效邏輯。

用 content entry digest 當作 cacheKey#

假設內容集合叫做 posts，而每個頁面只依賴該文章 entry 的內容，可以這樣寫：

1
---
2
import { getCollection } from 'astro:content';
3

4
export async function getStaticPaths() {
5
  const posts = await getCollection('posts');
6

7
  return posts.map((post) => ({
8
    params: { slug: post.id },
9
    props: { post },
10
    cacheKey: post.digest,
11
  }));
12
}
13

14
const { post } = Astro.props;
15
---
16

17
<h1>{post.data.title}</h1>

post.digest 適合「頁面輸出主要由該 entry 內容決定」的情境。它不是一個可以到處複製的固定答案；如果頁面還依賴 locale、分類 metadata、遠端 CMS 欄位或其他 route-specific 輸入，cacheKey 就必須在那些輸入改變時一起改變。

換句話說，cacheKey 要回答的是：「這個 path 的輸出資料是否仍然和上一輪相同？」如果答案不確定，就先讓該 route 每次重建，等資料依賴盤點清楚後再 opt in。

Astro 會同時檢查 module graph 與 cacheKey#

Astro 7.2 的失效判斷有兩層：

兩者都沒有變時，Astro 才會重用上一輪結果。只改了資料 key，仍可能要重建該 path；只改了 layout 或 component，則可能讓整條 route 的頁面重新輸出。這也是為什麼不能把 cacheKey 當成「忽略所有程式碼變更」的開關。

沒有回傳 cacheKey 的 path 會一直渲染。對尚未完成依賴盤點的 route，可以先保留沒有 key 的寫法，讓既有 build 行為不變，再以單一路由逐步驗證。

CI 要保存哪個 cache？#

Astro 官方說明 incremental build 使用 cacheDir，預設位置是 node_modules/.astro/，與 content layer 和 image cache 放在一起。若 CI 每次都從完全乾淨的 workspace 開始，這個功能就沒有上一輪結果可重用。

可以先把 build 分成兩種檢查：

1
# 第一次建立基準
2
time pnpm build
3

4
# 保留同一份工作目錄與 cache 後，再次執行
5
time pnpm build

CI 的 cache key 至少要與 lockfile、Node／Astro 版本和會影響輸出的 build 設定對齊。這是維運上的 cache 管理原則，不是把任何舊 cache 都視為有效；恢復 cache 後仍要檢查產出的 HTML、圖片與 Pagefind 索引。

如果網站還在處理大型 content collection，可以搭配 Astro Content Collection 的 collectionStorage 分塊方式，但兩者解決的階段不同：collectionStorage 影響內容資料的保存與載入，incremental build 則影響 prerendered route 是否需要重新輸出。

用輸出回歸驗證失效範圍#

不要只看第二次 build 變快就宣布設定完成。至少做三組變更：

1. 只改一篇文章內容：確認該篇重新輸出，其他未變 path 沒有被錯誤重用。
2. 改共用 layout 或 component：確認依賴該 module graph 的頁面都有更新。
3. 改 route 依賴的 metadata 或外部資料 key：確認 cacheKey 有同步變動。

每組測試都保留 build command、變更檔案、輸出 HTML 的抽查結果與時間。若你使用圖片最佳化、RSS、sitemap 或 Pagefind，也要抽查這些衍生產物；「頁面沒有重新渲染」不一定代表整個 build pipeline 都不需要驗證。

目前功能仍是 experimental，官方也邀請使用者回報真實網站上的結果。對 production 站點，先選一條可回滾、可比對輸出的內容 route，等失效規則和 CI cache 都通過後再擴大使用。

這個功能真正的重點不是把所有 build 都變成增量，而是讓每個 path 的資料依賴可以被明確描述。 module graph 負責程式碼變更，cacheKey 負責該 path 的資料變更；兩邊都能驗證，才有資格跳過重建。

常見問題#