Astro 7.2 インクリメンタルビルドをCIで動かすまでに踏んだ3つの落とし穴
Astro 7.2の実験的インクリメンタルビルドをGitHub Actionsで動かす設定と、キャッシュが効かない原因の切り分け方を実体験から解説する
ブログ記事を3つ直しただけのプッシュで、CIが毎回200ページ全部をビルドし直す。Astro 7.2にexperimental incrementalBuildが入ったと聞いて即座に飛びついたが、「フラグを有効にしてプッシュ」だけではCIのビルド時間は1秒も縮まなかった。ローカルでは効いているのに、GitHub Actionsでは毎回フルビルドになる。原因を潰すまでに踏んだ穴を順に書く。
そもそもインクリメンタルビルドは何をスキップするのか
この機能が対象にするのはgetStaticPaths()で生成される静的ページだ。各パスにcacheKeyを返すと、Astroがそのキーとモジュール依存グラフのハッシュを前回ビルドの記録と比較し、両方一致すればHTMLを再生成せずに前回の出力をコピーする。cacheKeyを返さないパスは毎回レンダリングされるので、オプトインは明示的。
Content Collectionsを使っているなら、ローダーが返すentry.digestをそのまま渡せばいい。
---
import { getCollection } from 'astro:content';
export async function getStaticPaths() {
const posts = await getCollection('blog');
return posts.map((post) => ({
params: { slug: post.id },
props: { post },
cacheKey: post.digest,
}));
}
const { post } = Astro.props;
---
設定は1行。
// astro.config.mjs
export default defineConfig({
experimental: {
incrementalBuild: true,
},
});
ローカルで2回ビルドすると、2回目は変更のないページがskippedと表示される。ここまでは順調だった。
落とし穴1: node_modules/.astro/だけ保存しても効かない
CIでキャッシュすべきディレクトリが2つある。キャッシュマニフェストが入るnode_modules/.astro/と、前回のビルド成果物のdist/だ。Astroはビルドのたびに出力ディレクトリを空にしてから、スキップ対象のページをキャッシュから復元する。つまりdist/が消えていてもマニフェストがあれば復元はできるのだが、PR #17084のコメントで指摘されているように、Cloudflare Pagesのようにdist/をワイプする環境では実質的にキャッシュが無効化される場面がある。
GitHub Actionsでの設定はこうなった。
- uses: actions/cache@v4
with:
path: |
node_modules/.astro/
dist/
key: astro-build-${{ hashFiles('src/**', 'astro.config.mjs') }}
restore-keys: |
astro-build-
keyをコミットSHAにすると毎回ユニークになるが、restore-keysのプレフィックスマッチで直近のキャッシュが復元されるので問題ない。ただし自分の場合はsrc/配下のハッシュをキーに含めたほうが、まったく同じソースで再実行したときにキャッシュヒットしてactions/cacheのアップロードが省略されるぶん数十秒速かった。
落とし穴2: 画像を複数インポートしているページでキャッシュが壊れる
フラグを有効にして最初のCIを通したあと、2回目のビルドでもスキップされるページとされないページがあった。ログを見るとdependencyHash changedと出ている。ソースは一切変更していない。
原因は7.2.0のバグで、画像を複数インポートしているページのモジュールハッシュが非決定的になる問題だった。RolldownのemitFileが返すアセットハンドルの順序がビルドごとに変わり、ハッシュの入力が揺れる。Issue #17615で報告され、7.2.1で修正済み。ハッシュの入力をファイルパスベースに変更することで順序依存がなくなった。
教訓: 7.2.0は使わない。最低でも7.2.1、できれば画像関連の修正が追加で入った7.2.2を使う。
落とし穴3: build.concurrencyとの排他
ビルドを速くしたくてこの機能を入れたのに、build.concurrencyを2以上に設定しているとインクリメンタルキャッシュは無効になる。ドキュメントにも明記されているが、小さい字で書いてあるので最初は見落とした。並列ビルドとの併用はまだ対応していない。
もうひとつ、ミドルウェアを編集したあとはキャッシュが自動では無効化されない。ミドルウェアはどのページにも影響しうるが、依存グラフには含まれないためだ。ミドルウェアを変更したらastro build --forceで一度フルビルドを挟む必要がある。自分はGitHub Actionsのワークフローに差分チェックを入れた。
- name: Check middleware changes
id: middleware
run: |
if git diff --name-only HEAD~1 | grep -q 'src/middleware'; then
echo "changed=true" >> "$GITHUB_OUTPUT"
fi
- name: Build
run: npx astro build ${{ steps.middleware.outputs.changed == 'true' && '--force' || '' }}
CIで実際にどれくらい効いたか
自分のブログは約200ページ。記事を1本追加するプッシュの場合、フルビルドで生成フェーズに掛かっていた時間が体感で3〜4割減った。200ページ中199ページがスキップされるのだから9割以上減ってほしいところだが、画像の最適化やサイトマップ生成など生成フェーズ以外の処理は毎回走るのでそんなものらしい。ページ数が数千を超えるドキュメントサイトのほうが恩恵は大きいと思う。
なお、Server Islandsを使っているページでキャッシュを有効にするには、ASTRO_KEY環境変数を固定値に設定してビルド間で揃える必要がある。これもドキュメントに書いてあるが、忘れるとislandの暗号化キーが変わって毎回再生成になる。
設定して終わりではなく、ログを読む習慣
astro buildの出力で各ページがrenderedかskippedかがわかる。CIに入れたあと最初の数回は必ずログを確認して、期待どおりスキップされているか見たほうがいい。スキップされないページがあったらdependencyHash changedかcacheKey changedかで原因の切り分けができる。まだexperimentalなので、次のマイナーバージョンで挙動が変わる可能性も普通にある。
検証環境: Ubuntu 22.04 / Astro 7.2.2 / Node.js 22.x / GitHub Actions ubuntu-latest / 検証日 2026年9月