빌드 캐시: 이전 결과를 언제 다시 써도 되는가

30초 요약

이 글은 네 문장으로 시작한다.

1. 빌드 캐시는 입력에서 계산한 키와 이전 결과를 연결한다.
2. 키에는 결과에 영향을 주는 모든 작업 정의와 입력이 들어가야 한다.
3. 저장소들을 순서대로 조회해 키가 있으면 선언한 출력을 온전히 복원하고, 모두 없으면 실행한 뒤 허용된 곳에 저장한다.
4. 공유 캐시는 같은 정확성 규칙 위에 누가 결과를 쓸 수 있는가라는 신뢰 문제를 더한다.

한 줄로 기억하면 작업 정의 + 작업이 실제로 읽어 결과를 바꾸는 입력 → 키 → 선언한 이전 출력이다.

캐시는 키에서 결과를 찾는 표다

작업 정의 + 결과를 바꾸는 입력
             ↓ 요약
           캐시 키 ── 저장소들을 순서대로 조회 ── 있음 ──> 선언한 출력 온전히 복원
             │
             └── 모두 없음 ──> 작업 실행 ──> 쓰기 허용 시 결과 저장

작업이 실행 중 실제로 읽어 결과를 바꿀 수 있는 값을 이 글에서는 ‘관찰 입력’이라고 부른다. 파일, 환경 변수와 명령 옵션이 여기에 해당한다. 변환기·컴파일러 구현과 그 버전은 별도의 ‘작업 정의’에 속한다. 캐시는 결과를 올바르게 만드는 장치가 아니라, 같은 결과를 낼 조건을 키가 정확히 표현한다는 전제에서 일을 건너뛰는 장치다.

작업 정의와 관찰 입력이 키를 만든다

Gradle은 구현 코드를 구분할 때 classpath(클래스 경로), 즉 Java·Gradle 코드가 사용할 클래스와 플러그인을 찾는 목록도 본다. 이 제품 항목 자체보다 다음 네 가지 분류를 기억한다.

• 무엇을 하는가 — 작업 구현, 변환기·플러그인과 도구 버전.
• 무엇을 읽는가 — 소스, 설정, 의존 결과와 lockfile.
• 어떻게 실행하는가 — 명령 인자, 대상 플랫폼, 개발·운영 모드와 환경 값.
• 무엇을 복원하는가 — 결과 파일과 복원 대상 경로.

예를 들어 같은 App.tsx라도 운영 모드, 서버 주소를 코드에 넣는 환경 변수, 변환기 버전이나 대상 플랫폼이 결과를 바꾼다면 각각 키의 입력이다. 반대로 작업 성공 여부에만 영향을 주고 결과 바이트에는 영향을 주지 않는 인증 토큰은 실행에 필요할 수 있어도 무조건 결과 키의 입력인 것은 아니다. 비밀값을 키에 넣을 때는 도구가 값을 노출하지 않는지도 확인한다.

약한 키는 정확성을, 넓은 키는 재사용률을 해친다

필요한 입력 누락 → 키가 너무 약함 → 잘못된 결과 재사용 → 정확성 문제
불필요한 입력 포함 → 키가 너무 넓음 → 매번 다시 실행     → 성능 문제

안전성부터 확보한다. 먼저 결과를 바꿀 수 있는 입력을 빠짐없이 포함한 뒤, 실제로 결과와 무관한 입력만 측정과 비교로 줄인다. 적중률을 높이려고 입력을 빼는 것은 최적화가 아니다.

경로도 값의 의미를 구분한다. 소스 파일의 상대 위치가 결과를 바꾸면 키에 필요할 수 있다. 하지만 /Users/a/project와 /builds/b/project라는 작업 폴더의 절대 접두사만 다르고 결과는 같아야 한다면, 그 차이를 정규화해야 다른 컴퓨터에서도 같은 키를 얻을 수 있다. 이를 이동 가능성(relocatability), 즉 다른 작업 폴더에도 결과를 복원할 수 있는 성질이라고 한다.

적중은 실행이 아니라 복원이다

캐시 적중은 이번 실행의 키에 연결된 저장 결과를 찾았다는 뜻이다. 컴파일러나 테스트를 이번 환경에서 다시 실행했다는 뜻이 아니다.

실행: 입력을 읽고 작업해서 결과를 새로 만든다.
적중: 키를 조회하고 이전 결과 파일을 복원한다.

따라서 결과 파일을 선언하지 않은 캐시는 로그만 다시 보여 주고 필요한 파일은 복원하지 못할 수 있다. Turborepo의 현재 문서도 outputs에 파일 결과를 선언하지 않으면 그 파일을 캐시하지 않는다고 설명한다. 입력뿐 아니라 복원해야 할 출력 전체가 계약의 절반이다.

미적중은 실패가 아니다

캐시 적중과 미적중은 조회한 저장소마다 관찰될 수 있다. 로컬 저장소에서 미적중한 뒤 공유 저장소에서 적중하면 작업을 실행하지 않는다. 구성한 모든 저장소에서 같은 키를 찾지 못했을 때 작업을 실행한다. 다음 미적중은 모두 정상일 수 있다.

• 처음 실행해 아직 저장 결과가 없다.
• 결과를 바꾸는 소스·설정·도구가 달라졌다.
• 저장 기간이나 용량 정책에 따라 이전 항목이 삭제됐다.
• 로컬 저장소에는 없고 다음 순서의 공유 저장소에는 있을 수 있다.

반대로 결과가 같아야 하는데 계속 미적중이면 키를 구성한 입력 중 무엇이 매번 달라지는지 본다. 현재 시각, 임시 경로, 무관한 CI 실행 번호나 지나치게 넓은 파일 묶음은 대표적인 후보다. 저장소를 비우는 것은 더 많은 정상 미적중을 만들 뿐 이 계약을 고치지 않는다.

Web과 React에서는 빌드 시 환경 값도 입력이다

예를 들어 React Web 앱이 PUBLIC_SERVER_URL을 JavaScript에 넣는다고 가정한다.

미리보기 빌드: PUBLIC_SERVER_URL=https://preview.example → 키 K
운영 빌드:     PUBLIC_SERVER_URL=https://service.example → 키도 달라야 함

환경 값이 결과에 들어가는데 키가 같다면 운영 빌드가 미리보기 주소를 담은 파일을 복원할 수 있다. 환경 변수를 작업에 전달하는 일과 키에 반영하는 일은 별도 계약일 수 있으므로 현재 도구 설정을 확인한다.

반대로 CI_JOB_ID가 결과에 전혀 영향을 주지 않는데 키에 포함되면 실행마다 미적중이 난다. React라는 프레임워크 이름으로 입력을 정하지 않고 실제로 빌드 작업이 읽어 출력에 반영한 값인가를 묻는다.

React Native에서는 Metro와 Android Gradle 캐시를 나눠 본다

Metro 캐시는 파일별 JavaScript 변환 결과를 재사용한다. Android의 Gradle 계층은 Android Gradle Plugin이 캐시 가능하다고 선언하고 Gradle이 입력·출력을 추적할 수 있는 작업의 결과만 재사용한다. 어떤 작업이 해당하는지는 플러그인과 버전에 따라 다르다. 두 계층은 같은 React Native 앱 빌드에 참여할 수 있어도 키, 작업 단위와 저장 결과가 다르다.

Metro 변환 캐시: 소스 파일 + 변환 설정·구현 + 플랫폼 조건 → 변환 결과
Gradle 작업 캐시: 작업 구현 + 선언 입력·속성             → 선언 출력

resetCache는 현재 Metro가 변환 저장소와 프로젝트 파일 목록·위치를 추적하는 파일 지도 캐시를 시작할 때 초기화하는 진단 옵션이다. 입력 계약을 수정하지 않은 채 매번 초기화하면 느려질 뿐 같은 문제가 다시 생길 수 있다. ‘React Native 문제니까 Metro 캐시 삭제’가 아니라 어느 작업의 어느 키가 틀렸는지 먼저 좁힌다.

로컬과 공유 캐시의 정확성 규칙은 같다

로컬에서만 쓰던 캐시를 공유하려면 추가로 다음을 확인한다.

• 작업 폴더 절대 경로가 달라도 키와 복원 결과가 같아야 한다.
• 운영체제·CPU·도구 차이가 결과를 바꾼다면 키나 공유 범위를 나눠야 한다.
• 네트워크 전송 비용이 작업을 다시 하는 비용보다 작은지 측정해야 한다.
• 저장 기간과 용량 정책은 적중률·비용을 바꾸지만 올바른 입력 계약을 대신하지 않는다.

공유 캐시는 정확성 규칙에 신뢰 경계를 더한다

한 사람의 로컬 오염은 한 컴퓨터에서 끝날 수 있지만 공유 오염은 같은 키를 쓰는 팀 전체에 퍼진다. 안전한 기본 방향은 다음과 같다.

• 결과를 만드는 신뢰한 실행자만 공유 저장소에 쓴다.
• 개발자와 일반 검증 실행자는 필요하면 읽기 전용으로 사용한다.
• 전송한 결과의 내용 식별값과 인증을 확인한다.
• 빌드 중 소스가 바뀌지 않게 하고, 선언하지 않은 호스트 도구 사용을 막는다.
• 오염을 확인하면 쓰기 원인을 먼저 막고 정확한 키 범위나 저장소를 정리한다.

캐시 삭제는 여기서도 마지막 복구 수단이다. 잘못된 입력 선언이나 쓰기 권한을 그대로 두면 다음 실행이 같은 문제 항목을 다시 저장한다.

전체 삭제보다 키의 구성 요소를 비교한다

관찰에 따라 갈림길을 고른다.

바뀐 결과가 나와야 하는데 적중했다

1. 어떤 값이 결과를 바꿔야 했는지 한 가지를 적는다.
2. 그 값이 작업 실행에는 전달됐지만 키에서는 빠졌는지 본다.
3. 캐시 없이 실행한 결과와 복원 결과를 비교한다.
4. 입력 선언을 고치고 같은 변경에서 키가 달라지는지 확인한다.

같은 결과여야 하는데 계속 미적중한다

1. 두 실행의 작업 구현과 명령이 같은지 본다.
2. 개별 입력 파일·속성·환경 값 중 달라진 부분을 찾는다.
3. 그 차이가 실제 출력에 영향을 주는지 검증한다.
4. 무관한 값만 입력에서 제거하거나 경로·내용을 정규화한다.

적중했는데 필요한 파일이 없다

입력 키보다 출력 선언을 본다. 작업이 만든 모든 필요한 파일이 저장 대상으로 선언됐는지, 두 작업이 같은 출력 폴더를 겹쳐 쓰지 않는지 확인한다. 빈 폴더에 복원하는 검증은 누락된 출력을 가장 빠르게 드러낸다.

빌드 캐시와 다른 캐시를 섞지 않는다

이 글의 빌드 캐시는 작업 결과를 재사용한다. 다음은 이름은 같아도 다른 계약이다.

• 패키지 다운로드 캐시: 레지스트리에서 받은 의존 파일을 다시 내려받지 않는다.
• 브라우저·CDN 캐시: 이미 배포한 응답을 사용자에게 다시 전달한다.
• 애플리케이션 데이터 캐시: 서버 응답이나 계산 결과를 실행 중 재사용한다.
• 메모이제이션: 한 프로세스나 함수 호출에서 계산 결과를 재사용한다.

어떤 캐시가 오래된 결과를 만들었는지 모르면 모두 지우게 된다. 누가 키를 계산하고, 무엇을 저장하며, 어디에 복원하는가로 이름을 붙인다.

이 글의 경계

이번 글은 이전 작업 결과를 안전하게 재사용하는 입력·키·출력 계약에 집중했다. 다음 내용은 분리한다.

• 어떤 실패를 어느 검증 계층이 잡는가: 다음 9편 테스트 피라미드
• 캐시를 포함한 검증과 산출물 생성 단계를 어떻게 잇는가: 10편 CI와 CD
• 테스트한 결과와 배포할 결과가 같은가: 11편 동일성과 승격
• 저장·전송 시간과 비용이 실제 이득인가: 20편 프론트엔드 비용 모델

마지막으로 한 줄만 기억한다. 결과에 영향을 주는 모든 작업 정의와 입력이 같을 때만 같은 키로 선언한 이전 출력을 온전히 복원한다.