コンテンツへスキップ

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 レイヤーキャッシュ をご覧ください。