コンテンツにスキップ

実験的なインクリメンタル静的ビルド

Type: boolean
Default: false

追加： astro@7.2.0

この実験的機能は前回のビルド出力を再利用し、変更されていないページの再レンダリングを省略します。

この機能を有効にすると、ページのデータとそのページが依存するコードの両方が、前回のビルド以降変更されていない場合、AstroはgetStaticPaths() (EN)で生成された静的ページのレンダリングをスキップできます。ページのデータを示すcacheKeyを返すと、Astroはページのモジュール依存関係グラフをハッシュ化し、コードの変更を追跡します。cacheKeyとコードのハッシュが前回のビルドと一致した場合、Astroはページを再レンダリングせず、以前の出力をコピーします。

大規模なサイトでほとんどのページが頻繁に変更されない場合、同じ出力になるページのレンダリングを省略できるため、ビルド時間を大幅に短縮できます。

インクリメンタルビルドを有効にするには、Astroの設定に次のフラグを追加します。

astro.config.mjs
import { defineConfig } from "astro/config";


export default defineConfig({
  experimental: {
    incrementalBuild: true,
  },
});

キャッシュキーを指定する

Section titled “キャッシュキーを指定する”

getStaticPaths()から返されるページのうち、cacheKeyを含むページのみレンダリングをスキップできます。getStaticPaths()を使用しない静的ページを含め、それ以外のすべてのページはビルドごとにレンダリングされます。

cacheKeyは、ページのレンダリングに使用するデータを識別する文字列です。コンテンツのハッシュ、バージョン番号、データソースの更新日時など、ページのコンテンツが変更されるたびに変わる値を選びます。cacheKeyが前回のビルドと異なる場合、Astroはページを再レンダリングし、同じ場合は以前の出力を再利用します。

src/pages/blog/[slug].astro
---
export async function getStaticPaths() {
  const posts = await fetchPosts();


  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
    cacheKey: post.updatedAt,
  }));
}
---

コンテンツコレクション (EN)からページを生成する場合、ローダーは各エントリーにdigest (EN)を提供できます。ローダーは、エントリーのデータが変更されるたびにこの値を更新する必要があります。そのため、digestはcacheKeyとして便利です。

src/pages/docs/[...slug].astro
---
import { getCollection, render } from "astro:content";


export async function getStaticPaths() {
  const entries = await getCollection("docs");


  return entries.map((entry) => ({
    params: { slug: entry.id },
    props: { entry },
    cacheKey: String(entry.digest),
  }));
}


const { entry } = Astro.props;
const { Content } = await render(entry);
---

ページが無効化される仕組み

Section titled “ページが無効化される仕組み”

cacheKeyが一致するページでも、依存するコードが変更されると再レンダリングされます。Astroは、レイアウト、コンポーネント、インポートしたファイルの内容を含む、ページのモジュール依存関係グラフをハッシュ化します。そのため、いずれかを編集すると、それを使用するページが無効化されます。Astroの設定やプロジェクトの依存関係を変更すると、すべてのページの出力に影響する可能性があるため、キャッシュ全体が無効化されます。

ビルド間でgetStaticPaths()から削除されたページは、以前の出力も自動的に削除されます。

ビルド間でキャッシュを保持する

Section titled “ビルド間でキャッシュを保持する”

AstroはインクリメンタルビルドのキャッシュをプロジェクトのcacheDir (EN)に保存します。デフォルトはnode_modules/.astro/です。このディレクトリには、ビルドマニフェストと以前にレンダリングされたページの再利用可能な出力が保存されます。出力ディレクトリは各ビルドの開始時に空にされ、レンダリングをスキップしたページはcacheDirから復元されます。

CI環境でページのレンダリングをスキップするには、astro buildを実行する前にcacheDirを復元する必要があります。ビルド間では、このディレクトリだけをキャッシュして復元してください。それ以外を保持する必要はありません。cacheDirがない場合、Astroはすべてのページを再レンダリングします。

キャッシュを無視してすべてのページを再レンダリングするには、astro build --forceを実行します。この場合も、Astroは次回のビルドに使用する新しいキャッシュを保存します。

制限事項

Section titled “制限事項”

この実験的機能には、現在次の制限事項があります。

  • build.concurrency: build.concurrency (EN)が1より大きい場合、インクリメンタルビルドのキャッシュは無効化されます。Astroは警告を出力し、すべてのページを再レンダリングします。

  • サーバーアイランド: サーバーアイランドをレンダリングするページは、デフォルトでビルドごとに再生成されるキーを使ってpropsを埋め込むため、毎回再レンダリングされます。これらのページをキャッシュしてビルド間で再利用するには、固定のASTRO_KEYを設定します。キーを変更するとページが無効化されるため、埋め込まれたコンテンツは引き続き復号できます。

  • ミドルウェア: ミドルウェアを変更しても、キャッシュされたページは無効化されません。ミドルウェアが事前レンダリングされたページのHTMLを変更する場合は、編集後にastro build --forceを実行してください。

貢献する コミュニティ スポンサー