NNext.js 中文网 GitHub

如何配置持续集成(CI)构建缓存

了解如何配置 CI 以缓存 Next.js 构建

为提高构建性能,Next.js 会将缓存保存到 .next/cache,并在多次构建之间共享该缓存。

要在持续集成(Continuous Integration,CI)环境中利用此缓存,你的 CI 工作流需要进行配置,以便在多次构建之间正确保留缓存。

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

以下是一些常见 CI 提供程序的缓存配置示例:

Vercel#

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

CircleCI#

编辑 .circleci/config.yml 中的 save_cache 步骤,使其包含 .next/cache:

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

如果你没有 save_cache 键,请遵循 CircleCI 关于设置构建缓存的文档。

Travis CI#

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

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

GitLab CI#

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

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

Netlify CI#

将 Netlify 插件与 @netlify/plugin-nextjs 配合使用。

AWS CodeBuild#

将以下内容添加(或合并)到你的 buildspec.yml 中:

yaml
cache:
  paths:
    - 'node_modules/**/*' # 缓存 `node_modules` 以加快 `yarn` 或 `npm i` 的速度
    - '.next/cache/**/*' # 缓存 Next.js 以加快应用的重新构建速度

GitHub Actions#

使用 GitHub 的 actions/cache,在你的工作流文件中添加以下步骤:

yaml
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 同级):

yaml
definitions:
  caches:
    nextcache: .next/cache

然后在你流水线 step 的 caches 部分引用它:

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

Heroku#

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

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

Azure Pipelines#

使用 Azure Pipelines 的 Cache 任务,在执行 next build 的任务之前的某处,将以下任务添加到你的流水线 yaml 文件中:

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

Jenkins(Pipeline)#

使用 Jenkins 的 Job Cacher 插件,在你通常运行 next build 或 npm install 的位置,将以下构建步骤添加到你的 Jenkinsfile 中:

yaml
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"
        }
    }
}
Next.js 中文网