Next.js GitHub Actions ワークフローテンプレート
最終更新
これは npm を使う Next.js アプリ向けの、そのまま動作する .github/workflows/ci.yml です。npm のダウンロードと .next/cache のビルドキャッシュを保存したうえで、lint、型チェック、テスト、本番ビルドを実行します。スクリプト名は package.json に合わせて編集してください。
ワークフロー
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
concurrency:
group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
ci:
runs-on: ubuntu-latest
timeout-minutes: 20
env:
NEXT_TELEMETRY_DISABLED: "1"
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Cache Next.js build cache
uses: actions/cache@v4
with:
path: .next/cache
key: nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx', '!node_modules/**', '!.next/**') }}
restore-keys: |
nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
nextjs-${{ runner.os }}-
- run: npm ci
- run: npm run lint
- run: npx tsc --noEmit
- run: npm test --if-present
- run: npm run build
分かりにくい部分の役割
cache: npmは npm のダウンロードフォルダーをキャッシュします。キーはロックファイルに基づきます。詳しくは npm のキャッシュ をご覧ください。.next/cacheのステップは、多くのテンプレートで抜けがちな重要な部分です。Next.js はここにコンパイル済みの出力と画像最適化の結果を保存します。キャッシュを復元しないと、毎回のビルドがゼロから始まり、Next.js がその旨の警告を表示します。キーはロックファイルのハッシュとソースファイルのハッシュを組み合わせるため、コードを変更すると新しいエントリが作成されます。一方restore-keysは、差分ビルドのために直前の古いエントリへフォールバックします。npx tsc --noEmitは、ファイルを書き出さずに型チェックを行います。next buildも型チェックを行いますが、先に実行すると失敗がより早く、わかりやすく検出されます。NEXT_TELEMETRY_DISABLEDは、CI で匿名のテレメトリを無効にします。concurrencyは、同じプルリクエストに対する古い実行をキャンセルします。main のブランチの実行はキャンセルされません。timeout-minutesは、停止したビルドの実行時間に上限を設けます。
バリエーション
ビルド時の環境変数
NEXT_PUBLIC_ で始まる変数はビルド時にインライン化されます。ビルドステップの env: で渡し、本物のシークレットはクライアントのバンドルに含めないようにしてください。
PlaywrightによるエンドツーエンドテストI
npx playwright install --with-deps chromium と npx playwright test を追加してください。matrix で分割する方法は テストのシャーディング と 遅い Playwright テスト をご覧ください。
Turborepo によるモノレポ
リモートビルドキャッシュを使うには、TURBO_TOKEN と TURBO_TEAM を設定したうえで npx turbo run lint test build を実行します。詳細は リモートビルドキャッシュ と Nx と Turborepo の CI をご覧ください。
デプロイジョブ
needs: ci と if: github.ref == 'refs/heads/main' を指定した 2 つ目のジョブを追加してください。Vercel をお使いの場合は、このジョブを省略して Vercel の Git 連携によるデプロイを利用できます。
macOS
Web アプリではほとんど必要ありません。Linux のままにしてください。
より高速なマシンで実行する
Next.js のビルドは、SWC と型チェックが複数のコアを使うため CPU 負荷が高くなります。次の 1 行を変更してください:
runs-on: [self-hosted, Linux, compiler-ci]
この変更により、ジョブは compiler.dev の 8 vCPU マシンで実行され、失敗時には現在のランナーにフォールバックします。すべての調整項目は GitHub Actions で Next.js を高速化する をご覧ください。
よくある質問
Next.js のビルドでキャッシュがないという警告が出るのはなぜですか?
.next/cache フォルダーが空だったためです。上記のキャッシュステップを追加すると、次回以降にキャッシュが復元された実行で警告は表示されなくなります。
Next.js では node_modules もキャッシュすべきですか?
いいえ。npm のダウンロードをキャッシュし、npm ci に node_modules を再構築させてください。
pnpm や Yarn を使えますか?
はい。cache: とインストールコマンドを変更し、キーに含まれるロックファイル名も更新してください。詳しくは pnpm のキャッシュ をご覧ください。
CI には Docker が必要ですか?
いいえ。ジョブ内でビルドしてください。コンテナをデプロイする場合にのみ Docker を使用してください。詳しくは Docker レイヤーキャッシュ をご覧ください。
関連記事
- GitHub ActionsでNext.jsを高速化するGitHub ActionsでNext.jsのビルドを高速化します。.next/cacheの保存、パッケージマネージャーのキャッシュ、lintとテストのジョブ分割、Playwrightのシャーディングを解説します。動作するYAML付きです。
- .NET GitHub Actions ワークフローテンプレートNuGet のキャッシュ、リストア、ビルド、テストの手順と SQL Server サービスの選択肢、同時実行制御と権限設定を備えた、.NET 向けの GitHub Actions CI をコピーしてすぐ使えます。
- Django GitHub Actions ワークフローテンプレートPostgres サービスコンテナー、pip キャッシュ、マイグレーションの確認とテストを備え、同時実行制御と権限設定も含む、Django 向けの GitHub Actions CI をコピーしてすぐ使えます。
- DockerビルドのGitHub ActionsワークフローテンプレートBuildx、GitHubのキャッシュレイヤー、mainへのプッシュ時のGHCRへのプッシュを使ってDockerイメージをビルドする、最小限の権限で動作するGitHub Actionsワークフローのコピー&ペースト用サンプルです。