지금까지는 04편에서 Amplify 콘솔이 자동으로 만든 빌드 설정을 그대로 썼습니다. 이 편에서는 그 설정을 저장소의 amplify.yml 파일로 옮기고, 캐시 경로를 직접 관리합니다. 이 편에서 다루는 캐시는 런타임 응답 캐시(05~13편)와는 다른, 빌드 단계에서만 쓰는 캐시입니다.

이 편에서 만드는 파일

notice-board/
└── amplify.yml    + (저장소에 커밋하는 빌드 설정 파일, cache.paths 포함)

개념 정리

amplify.yml 구조

캐시가 실제로 하는 일

AWS 공식 문서는 캐시 동작을 이렇게 설명합니다. 첫 빌드에서 cache.paths에 적은 경로를 저장해 두고, 다음 빌드부터는 명령을 실행하기 전에 그 경로를 그대로 복원합니다. 즉 캐시는 내용을 검사해서 다시 쓸지 판단하는 것이 아니라, 이전 빌드가 남긴 폴더를 통째로 되돌려 놓는 방식입니다. node_modules를 캐시하면 npm ci가 이미 받아 놓은 패키지를 다시 내려받지 않고 검증만 하고, .next/cache를 캐시하면 next build가 이전 컴파일 결과를 재사용해 바뀌지 않은 부분을 다시 컴파일하지 않습니다.

경로는 프로젝트 루트 기준 상대 경로만 허용됩니다. 절대 경로를 적어도 빌드는 에러 없이 성공하지만, 그 경로는 캐시되지 않습니다.

캐시가 깨지는 흔한 원인

캐시는 내용을 비교하지 않고 폴더를 그대로 복원하므로, package-lock.json이 바뀌어도 Amplify가 자동으로 node_modules 캐시를 비우지 않습니다. 보통은 npm ci가 락 파일과 node_modules의 불일치를 감지해 알아서 다시 설치하므로 문제가 되지 않지만, 이상하게 오래된 의존성이 남아있는 것 같다면 cache.paths에서 해당 경로를 잠시 지우고 한 번 빌드해 캐시를 새로 채운 뒤 다시 넣는 방법으로 해결합니다.

실습

# notice-board/amplify.yml
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
      - .next/cache/**/*

git add amplify.yml
git commit -m "add amplify.yml with build cache paths"
git push

git commit --allow-empty -m "trigger second deploy to compare cache"
git push

직접 해보기

1. cache.paths에서 .next/cache/**/*만 지우고 다시 배포해, node_modules만 캐시했을 때와 두 캐시를 함께 뒀을 때 build 단계 시간 차이를 비교해 보세요.
2. package.json에 의존성을 하나 추가해 재배포하고, npm ci가 캐시된 node_modules를 그대로 쓰지 않고 새 패키지를 반영하는지 확인해 보세요.

자주 하는 실수

확인 문제

참고 자료

• AWS Amplify Docs — Build specification reference(cache.paths 동작 방식) 
• AWS Amplify Docs — Configuring the build settings for an Amplify application 
• Next.js Docs — How to configure CI build caching(AWS CodeBuild 캐시 경로 예시)