Next.js 가이드 정리: CI Build Caching

1. 개요

Next.js는 빌드 속도를 향상하기 위해 .next/cache 디렉터리에 빌드 캐시를 저장합니다.
CI 환경에서 이 캐시를 제대로 활용하려면, 워크플로우 단계에서 .next/cache를 저장하고 복원하도록 설정해야 합니다.

  • 캐시를 올바르게 설정하지 않으면, CI 로그에서 No Cache Detected와 같은 메시지가 나타날 수 있습니다.
  • 각 CI 서비스마다 캐시를 설정하는 방식이 다르므로, 서비스별 예제 설정을 참고해야 합니다.

2. Vercel

  • Vercel에서 Next.js를 사용하는 경우, 빌드 캐시는 자동으로 설정됩니다.
  • 별도의 작업이 필요하지 않습니다.
  • Turborepo를 함께 사용하는 경우, Vercel 문서에서 추가 설정 방법을 확인할 수 있습니다.

3. CircleCI

.circleci/config.yml에서 save_cache 단계에 .next/cache를 포함해야 합니다.

핵심 포인트:

  • paths 항목에
    • ./node_modules
    • ./.next/cache 를 함께 지정
  • key는 yarn.lock 또는 package-lock.json의 checksum 등을 조합하여 구성

결과적으로, 의존성과 Next.js 캐시를 함께 저장하여 빌드를 빠르게 할 수 있습니다.

4. Travis CI

.travis.yml 파일의 cache.directories 배열에 .next/cache를 추가합니다.

예시 구조(요약):

cache:
  directories:
    - $HOME/.cache/yarn
    - node_modules
    - .next/cache
  • 의존성(node_modules)와 Next.js 빌드 캐시를 모두 저장하여, 이후 빌드 속도를 향상시킵니다.

5. GitLab CI

.gitlab-ci.yml에서 cache 설정에 .next/cache를 포함합니다.

핵심 내용:

  • cache.key에 브랜치 이름 또는 커밋 기반 키 사용 (예: ${CI_COMMIT_REF_SLUG})
  • paths에
    • node_modules/
    • .next/cache/ 를 포함

이를 통해, 동일 브랜치/키 기준으로 Next.js 빌드 캐시를 재사용할 수 있습니다.

6. Netlify CI

Netlify에서는 Netlify Plugin을 사용하여 Next.js 캐시를 관리할 수 있습니다.

  • @netlify/plugin-nextjs 플러그인을 사용하면,
    • Next.js 빌드 및 캐시 관리가 자동으로 처리됩니다.
  • Netlify의 Plugin 시스템에서 해당 플러그인을 활성화하면 됩니다.

7. AWS CodeBuild

buildspec.yml 파일의 cache.paths 항목에 .next/cache를 추가합니다.

핵심 포인트:

  • node_modules/**/* : 패키지 설치 시간 단축
  • .next/cache/**/* : Next.js 빌드 재사용

예시(요약):

cache:
  paths:
    - 'node_modules/**/*'
    - '.next/cache/**/*'

8. GitHub Actions

GitHub Actions에서는 actions/cache를 사용하여 .next/cache를 저장합니다.

핵심 개념:

  • path 항목에
    • ~/.npm
    • ${{ github.workspace }}/.next/cache
  • key는 OS, 패키지 락 파일, 소스 파일(예: .js/.ts) 해시를 조합하여 생성
  • restore-keys로 패키지 락 파일 해시만 포함하는 키를 지정하여, 소스 변경 시에도 기존 캐시 일부를 재사용

요약 예시:

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.[jt]s', '**/*.[jt]sx') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

실제 설정 시에는 프로젝트 구조 및 사용하는 패키지 매니저에 맞게 경로와 key를 조정해야 합니다.

9. Bitbucket Pipelines

bitbucket-pipelines.yml에서 상위 레벨에 캐시 정의를 추가합니다.

  1. definitions.caches에서 nextcache: .next/cache와 같이 캐시 이름과 경로를 지정
  2. 빌드 단계의 caches 섹션에서
    • node
    • nextcache 를 함께 참조

이렇게 하면, 의존성과 Next.js 캐시를 모두 저장할 수 있습니다.

10. Heroku

Heroku에서는 Custom Cache 기능을 사용해 .next/cache를 캐시에 포함시킬 수 있습니다.

  • package.json의 최상위에 "cacheDirectories": [".next/cache"]를 추가
  • Heroku는 이 값을 참고하여 지정된 디렉터리를 캐시합니다.

요약:

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

11. Azure Pipelines

Azure Pipelines의 Cache@2 작업을 이용하여 .next/cache를 저장합니다.

핵심 사항:

  • key는 OS, 락 파일 등으로 구성
  • path에 $(System.DefaultWorkingDirectory)/.next/cache를 지정
  • next build를 실행하기 전에 캐시 복원 작업을 배치

예시(요약):

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

12. Jenkins (Pipeline)

Jenkins에서는 Job Cacher 플러그인을 사용하여 .next/cache를 관리할 수 있습니다.

일반적인 패턴:

  1. node_modules에 대한 캐시
  2. .next/cache에 대한 캐시

Jenkinsfile 예시 아이디어(요약):

stage('Restore npm packages') {
  steps {
    // package-lock.json을 기준으로 node_modules 캐시
    cache(caches: [
      arbitraryFileCache(
        path: 'node_modules',
        includes: '**/*',
        cacheValidityDecidingFile: 'package-lock.json'
      )
    ]) {
      sh 'npm install'
    }
  }
}

stage('Build') {
  steps {
    // GIT_COMMIT 등을 기준으로 .next/cache 캐시
    cache(caches: [
      arbitraryFileCache(
        path: '.next/cache',
        includes: '**/*',
        cacheValidityDecidingFile: 'next-lock.cache'
      )
    ]) {
      sh 'npm run build'
    }
  }
}
  • node_modules와 .next/cache를 각각 캐시하여 설치 및 빌드 시간을 모두 줄이는 전략입니다.

13. 요약 및 활용 팁

  • Next.js는 .next/cache에 빌드 관련 캐시를 저장합니다.
  • CI 환경에서 이 디렉터리를 적절히 저장/복원하면 빌드 속도를 크게 향상시킬 수 있습니다.
  • 구현 시 유의할 점:
    • 캐시 키는 보통 OS + 패키지 락 파일 + 소스 코드 해시 등을 조합하여 생성
    • node_modules와 .next/cache 둘 다 캐시하면 가장 큰 효과
    • 캐시가 깨졌거나 문제가 생긴 경우, 키를 변경하여 새로운 캐시를 생성할 수 있음
  • 각 CI 벤더의 문서를 참고하여, 위 예제를 실제 프로젝트에 맞게 커스터마이징하는 것이 중요합니다.