如何設定持續整合 (CI) 建置快取

為了提升建置效能，Next.js 會將快取儲存在 .next/cache 中，這些快取可在不同建置之間共享。

要在持續整合 (CI) 環境中利用此快取，您需要設定 CI 工作流程，以正確地在不同建置之間保留快取。

如果您的 CI 未設定為在不同建置之間保留 .next/cache，您可能會看到未偵測到快取 (No Cache Detected) 錯誤。

以下是常見 CI 供應商的快取設定範例：

Vercel

Next.js 快取會自動為您設定。您無需進行任何操作。如果您在 Vercel 上使用 Turborepo，請在此了解更多。

CircleCI

在 .circleci/config.yml 中編輯您的 save_cache 步驟，加入 .next/cache：

steps:
  - save_cache:
      key: dependency-cache-{{ checksum "yarn.lock" }}
      paths:
        - ./node_modules
        - ./.next/cache

如果您沒有 save_cache 鍵，請遵循 CircleCI 的設定建置快取文件。

Travis CI

在您的 .travis.yml 中加入或合併以下內容：

cache:
  directories:
    - $HOME/.cache/yarn
    - node_modules
    - .next/cache

GitLab CI

在您的 .gitlab-ci.yml 中加入或合併以下內容：

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .next/cache/

Netlify CI

使用 Netlify Plugins 搭配 @netlify/plugin-nextjs。

AWS CodeBuild

在您的 buildspec.yml 中加入（或合併）以下內容：

cache:
  paths:
    - 'node_modules/**/*' # 快取 `node_modules` 以加速 `yarn` 或 `npm i`
    - '.next/cache/**/*' # 快取 Next.js 以加速應用程式重建

GitHub Actions

使用 GitHub 的 actions/cache，在您的工作流程檔案中加入以下步驟：

uses: actions/cache@v4
with:
  # 關於使用 `yarn`、`bun` 或其他套件管理器的快取設定，請參閱 https://github.com/actions/cache/blob/main/examples.md，或您可以使用 actions/setup-node 進行快取 https://github.com/actions/setup-node
  path: |
    ~/.npm
    ${{ github.workspace }}/.next/cache
  # 當套件或原始碼變更時，產生新的快取。
  key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
  # 如果原始碼變更但套件未變更，則從先前的快取重建。
  restore-keys: |
    ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

Bitbucket Pipelines

在您的 bitbucket-pipelines.yml 的頂層（與 pipelines 同層級）中加入或合併以下內容：

definitions:
  caches:
    nextcache: .next/cache

然後在管線 step 的 caches 區塊中引用它：

- step:
    name: your_step_name
    caches:
      - node
      - nextcache

Heroku

使用 Heroku 的自訂快取，在您的頂層 package.json 中加入 cacheDirectories 陣列：

"cacheDirectories": [".next/cache"]

Azure Pipelines

使用 Azure Pipelines 的快取任務 (Cache task)，在您的管線 yaml 檔案中，於執行 next build 的任務之前加入以下任務：

- task: Cache@2
  displayName: '快取 .next/cache'
  inputs:
    key: next | $(Agent.OS) | yarn.lock
    path: '$(System.DefaultWorkingDirectory)/.next/cache'

Jenkins (Pipeline)

使用 Jenkins 的 Job Cacher 外掛，在您的 Jenkinsfile 中通常執行 next build 或 npm install 的地方加入以下建置步驟：

stage("Restore npm packages") {
    steps {
        // 根據 GIT_COMMIT 雜湊值將鎖定檔案寫入快取
        writeFile file: "next-lock.cache", text: "$GIT_COMMIT"

        cache(caches: [
            arbitraryFileCache(
                path: "node_modules",
                includes: "**/*",
                cacheValidityDecidingFile: "package-lock.json"
            )
        ]) {
            sh "npm install"
        }
    }
}
stage("Build") {
    steps {
        // 根據 GIT_COMMIT 雜湊值將鎖定檔案寫入快取
        writeFile file: "next-lock.cache", text: "$GIT_COMMIT"

        cache(caches: [
            arbitraryFileCache(
                path: ".next/cache",
                includes: "**/*",
                cacheValidityDecidingFile: "next-lock.cache"
            )
        ]) {
            // 即 `next build`
            sh "npm run build"
        }
    }
}

如何設定持續整合 (CI) 建置快取

On this page