가이드: CI Build Caching

가이드: CI Build Caching | Next.js

출처 URL: https://nextjs.org/docs/pages/guides/ci-build-caching

Pages RouterGuidesCI Build Caching

CI 빌드 캐싱 구성 방법

마지막 업데이트 2026년 2월 20일

빌드 성능을 개선하기 위해 Next.js는 빌드 간에 공유되는 캐시를 .next/cache에 저장합니다.

이 캐시를 CI(Continuous Integration) 환경에서 활용하려면, 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/plugin-nextjs를 포함한 Netlify Plugins를 사용하세요.

AWS CodeBuild

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를 사용해 워크플로 파일에 다음 단계를 추가하세요:

    uses: actions/cache@v4
    with:
      # See here for caching with `yarn`, `bun` or other package managers https://github.com/actions/cache/blob/main/examples.md 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 Pipelines

bitbucket-pipelines.yml의 최상위(pipelines와 동일한 수준)에 다음을 추가하거나 병합하세요:

    definitions:
      caches:
        nextcache: .next/cache

그런 다음 파이프라인 step의 caches 섹션에서 이를 참조하세요:

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

Heroku

Heroku의 custom cache를 사용해 최상위 package.json에 cacheDirectories 배열을 추가하세요:

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

Azure Pipelines

Azure Pipelines의 Cache 작업을 사용해 next build를 실행하는 작업 이전에 다음 작업을 파이프라인 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 위치에 다음 빌드 단계를 추가하세요:

    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"
            }
        }
    }

이 내용이 도움이 되었나요?