Skip to main content

持续集成 (CI) 构建缓存

为了提高构建性能，Next.js 将缓存保存到 .next/cache，以便在构建之间共享。

¥To improve build performance, Next.js saves a cache to .next/cache that is shared between builds.

要在持续集成 (CI) 环境中利用此缓存，你的 CI 工作流程需要配置为在构建之间正确保留缓存。

¥To take advantage of this cache in Continuous Integration (CI) environments, your CI workflow will need to be configured to correctly persist the cache between builds.

如果你的 CI 未配置为在构建之间保留 .next/cache，你可能会看到 未检测到缓存 错误。

¥If your CI is not configured to persist .next/cache between builds, you may see a No Cache Detected error.

以下是常见 CI 提供商的一些缓存配置示例：

¥Here are some example cache configurations for common CI providers:

Vercel​

Next.js 缓存会自动为你配置。你无需执行任何操作。如果你在 Vercel 上使用 Turborepo，请使用 在此了解更多信息。

¥Next.js caching is automatically configured for you. There's no action required on your part. If you are using Turborepo on Vercel, learn more here.

CircleCI​

编辑 .circleci/config.yml 中的 save_cache 步骤以包含 .next/cache：

¥Edit your save_cache step in .circleci/config.yml to include .next/cache:

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

如果你没有 save_cache 密钥，请按照 CircleCI 的 有关设置构建缓存的文档 进行操作。

¥If you do not have a save_cache key, please follow CircleCI's documentation on setting up build caching.

Travis CI​

将以下内容添加或合并到你的 .travis.yml 中：

¥Add or merge the following into your .travis.yml:

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

GitLab 持续集成​

¥GitLab CI

将以下内容添加或合并到你的 .gitlab-ci.yml 中：

¥Add or merge the following into your .gitlab-ci.yml:

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

Netlify CI​

将 Netlify 插件 与 @netlify/plugin-nextjs 一起使用。

¥Use Netlify Plugins with @netlify/plugin-nextjs.

AWS 代码构建​

¥AWS CodeBuild

将以下内容添加（或合并）到你的 buildspec.yml 中：

¥Add (or merge in) the following to your buildspec.yml:

cache:
  paths:
    - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i`
    - '.next/cache/**/*' # Cache Next.js for faster application rebuilds

GitHub Actions​

使用 GitHub 的 actions/cache，在工作流程文件中添加以下步骤：

¥Using GitHub's actions/cache, add the following step in your workflow file:

uses: actions/cache@v4
with:
  # See here for caching with `yarn` https://github.com/actions/cache/blob/main/examples.md#node---yarn or you can leverage caching with actions/setup-node https://github.com/actions/setup-node
  path: |
    ~/.npm
    ${{ github.workspace }}/.next/cache
  # Generate a new cache whenever packages or source files change.
  key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
  # If source files changed but packages didn't, rebuild from a prior cache.
  restore-keys: |
    ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

Bitbucket 管道​

¥Bitbucket Pipelines

将以下内容添加或合并到顶层的 bitbucket-pipelines.yml 中（与 pipelines 同一级别）：

¥Add or merge the following into your bitbucket-pipelines.yml at the top level (same level as pipelines):

definitions:
  caches:
    nextcache: .next/cache

然后在管道的 step 的 caches 部分中引用它：

¥Then reference it in the caches section of your pipeline's step:

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

Heroku​

使用 Heroku 的 自定义缓存，在顶层 package.json 中添加 cacheDirectories 数组：

¥Using Heroku's custom cache, add a cacheDirectories array in your top-level package.json:

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

Azure 管道​

¥Azure Pipelines

使用 Azure Pipelines 的 缓存任务，将以下任务添加到管道 yaml 文件中执行 next build 的任务之前的某个位置：

¥Using Azure Pipelines' Cache task, add the following task to your pipeline yaml file somewhere prior to the task that executes next build:

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

Jenkins（管道）​

¥Jenkins (Pipeline)

使用 Jenkins 的 作业缓存器 插件，将以下构建步骤添加到你通常运行 next build 或 npm install 的 Jenkinsfile 中：

¥Using Jenkins' Job Cacher plugin, add the following build step to your Jenkinsfile where you would normally run next build or npm install:

stage("Restore npm packages") {
    steps {
        // Writes lock-file to cache based on the GIT_COMMIT hash
        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 {
        // Writes lock-file to cache based on the GIT_COMMIT hash
        writeFile file: "next-lock.cache", text: "$GIT_COMMIT"

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