캐싱
Turborepo는 캐싱을 사용하여 빌드 속도를 높이고, 동일한 작업을 두 번 수행하지 않도록 보장합니다. 작업이 캐시 가능한 경우, Turborepo는 작업이 처음 실행되었을 때의 지문을 사용하여 캐시에서 작업 결과를 복원합니다.
Turborepo의 캐싱은 로컬에서 작업할 때 상당한 시간을 절약해주며, Remote Caching을 활성화하면 전체 팀과 CI에서 캐시를 공유하여 훨씬 더 강력해집니다.
이 페이지에서는 다음을 배웁니다:
- 첫 번째 Turborepo 캐시 히트를 달성하는 방법
- Remote Caching을 활성화하는 방법
- Turborepo가 해시의 입력 및 출력으로 사용하는 것
- 캐싱 문제를 해결하는 방법
Good to know:
Turborepo는 작업이 결정적이라고 가정합니다. 작업이 Turborepo가 인식하는 입력 세트가 주어졌을 때 다른 출력을 생성할 수 있다면, 캐싱이 예상대로 작동하지 않을 수 있습니다.
첫 번째 Turborepo 캐시 히트
세 단계로 Turborepo의 캐싱 동작을 시도해볼 수 있습니다:
첫 번째 빌드 실행
turbo를 전역으로 설치한 경우 저장소에서 turbo build를 실행합니다.
또는 패키지 관리자를 사용하여 package.json의 build 스크립트를 실행할 수 있습니다.
이 결과로 캐시 미스가 발생합니다. 이 저장소에서 이 입력 세트로 turbo를 실행한 적이 없기 때문입니다. 입력은 로컬 파일 시스템 캐시 또는 Remote Cache에서 확인할 해시로 변환됩니다.
입력의 지문이 이미 캐시에 있기 때문에 애플리케이션을 다시 빌드할 이유가 없습니다. 이전 빌드의 결과를 캐시에서 복원하여 리소스와 시간을 절약할 수 있습니다.
Remote Caching
Turborepo는 작업 결과를 머신의 .turbo/cache 디렉토리에 저장합니다. 그러나 이 캐시를 팀원 및 CI와 공유하여 전체 조직의 속도를 더욱 높일 수 있습니다.
Remote Caching과 그 이점에 대해 자세히 알아보려면 Remote Caching 페이지를 방문하세요.
Remote Cache 활성화
먼저 Remote Cache 제공자로 인증합니다:
그런 다음 머신의 저장소를 Remote Cache에 연결합니다:
이제 작업을 실행하면 Turborepo가 자동으로 작업의 출력을 Remote Cache로 전송합니다. Remote Cache에 인증된 다른 머신에서 동일한 작업을 실행하면 처음 작업을 실행할 때 캐시를 히트합니다.
CI 머신을 Remote Cache에 연결하는 방법에 대한 정보는 CI 구성 가이드를 방문하세요.
기본적으로 Turborepo는 제로 구성으로 Vercel Remote Cache를 사용합니다. 다른 Remote Cache를 사용하려면 Remote Caching API 문서를 방문하세요.
무엇이 캐시되나요?
Turborepo는 두 가지 유형의 출력을 캐시합니다: 작업 출력과 로그입니다.
작업 출력
Turborepo는 turbo.json의 outputs 키에 정의된 작업의 파일 출력을 캐시합니다. 캐시 히트가 발생하면 Turborepo는 캐시에서 파일을 복원합니다.
outputs 키는 선택 사항입니다. 이 경우 Turborepo가 어떻게 동작하는지는 API 참조를 참조하세요.
파일 출력 제공
작업에 대한 파일 출력을 선언하지 않으면 Turborepo는 해당 출력을 캐시하지 않습니다. 일부 작업(예: linter)에는 괜찮을 수 있지만, 많은 작업은 캐시하고 싶은 파일을 생성합니다.
캐시를 히트할 때 파일을 사용할 수 없다는 오류가 발생하는 경우 작업에 대한 출력을 정의했는지 확인하세요.
로그
Turborepo는 항상 작업의 터미널 출력을 캡처하여 작업이 처음 실행되었을 때의 로그를 터미널에 복원합니다.
재생된 로그의 세부 수준은 --output-logs 플래그 또는 outputLogs 구성 옵션을 사용하여 구성할 수 있습니다.
작업 입력
입력은 Turborepo에 의해 해시되어 작업 실행에 대한 "지문"을 생성합니다. "지문"이 일치하면 작업 실행이 캐시를 히트합니다.
내부적으로 Turborepo는 전역 해시와 작업 해시의 두 가지 해시를 생성합니다. 해시 중 하나라도 변경되면 작업이 캐시를 미스합니다.
전역 해시 입력
| 입력 | 예시 |
|---|---|
루트 turbo.json 및 패키지 turbo.json의해결된 작업 정의 | 루트 turbo.json 또는 패키지 구성에서 outputs 변경 |
| Workspace 루트에 영향을 미치는 Lockfile 변경 | 루트 package.json의 종속성 업데이트는 모든 작업이 캐시를 미스하게 함 |
globalDependencies 파일 내용 | globalDependencies에 나열된 ./.env 변경은 모든 작업이 캐시를 미스하게 함 |
globalEnv에 나열된 변수의 값 | globalEnv에 나열된 GITHUB_TOKEN 값 변경 |
| 작업 런타임에 영향을 미치는 플래그 값 | --cache-dir, --framework-inference 또는 --env-mode와 같은 동작 변경 플래그 사용 |
| 임의 패스스루 인수 | turbo build -- --arg=value는 turbo build 또는 turbo build -- --arg=diff와 비교하여 캐시를 미스함 |
패키지 해시 입력
| 입력 | 예시 |
|---|---|
| 패키지 구성 변경 | 패키지의 turbo.json 변경 |
| 패키지에 영향을 미치는 Lockfile 변경 | 패키지의 package.json에서 종속성 업데이트 |
패키지의 package.json 변경 | 패키지의 package.json에서 name 필드 업데이트 |
| 소스 제어의 파일 변경 | src/index.ts에 새 코드 작성 |
문제 해결
Dry run 사용
Turborepo에는 실제로 실행하지 않고 작업을 실행하면 어떤 일이 발생하는지 확인할 수 있는 --dry 플래그가 있습니다. 이는 어떤 작업을 실행하고 있는지 확실하지 않을 때 캐싱 문제를 디버깅하는 데 유용할 수 있습니다.
자세한 내용은 --dry API 참조를 방문하세요.
Run Summary 사용
Turborepo에는 작업의 모든 입력, 출력 등에 대한 개요를 얻는 데 사용할 수 있는 --summarize 플래그가 있습니다. 두 요약을 비교하면 두 작업의 해시가 다른 이유를 알 수 있습니다. 이는 다음과 같은 경우에 유용할 수 있습니다:
- 입력 디버깅: Turborepo의 작업에는 많은 입력이 있습니다. 작업이 캐시를 히트할 것으로 예상했는데 미스하는 경우 Run Summary를 사용하여 예상하지 못한 입력이 다른지 확인할 수 있습니다.
- 출력 디버깅: 캐시 히트가 예상한 파일을 복원하지 않는 경우 Run Summary는 캐시에서 복원되는 출력을 이해하는 데 도움이 될 수 있습니다.
Summary 뷰어
Turborepo 네이티브 Run Summary UI 뷰어는 없지만, Run Summary를 웹 뷰로 보고 싶다면 커뮤니티에서 만든 https://turbo.nullvoxpopuli.com을 사용하는 것을 권장합니다.
캐싱 끄기
때때로 작업의 출력을 캐시에 쓰지 않을 수 있습니다. 이는 "cache": false를 사용하여 작업에 대해 영구적으로 설정하거나 the --cache <options> 플래그를 사용하여 전체 실행에 대해 설정할 수 있습니다.
캐시 덮어쓰기
캐시된 작업을 강제로 다시 실행하려면 --force 플래그를 사용합니다. 이는 캐시 읽기를 비활성화하며 쓰기는 비활성화하지 않습니다.
작업 캐싱이 작업 실행보다 느림
캐싱이 캐싱하지 않는 것보다 느린 시나리오를 만드는 것이 가능합니다. 이러한 경우는 드물지만 몇 가지 예는 다음과 같습니다:
- 매우 빠르게 실행되는 작업: 작업이 Remote Cache로의 네트워크 왕복보다 빠르게 실행되는 경우 작업을 캐시하지 않는 것을 고려해야 합니다.
- 출력 자산이 엄청나게 큰 작업: 업로드 또는 다운로드하는 데 걸리는 시간이 재생성하는 데 걸리는 시간을 초과하는 것처럼 완전한 Docker 컨테이너와 같이 너무 큰 아티팩트를 만드는 것이 가능합니다. 이러한 경우 작업을 캐시하지 않는 것을 고려해야 합니다.
- 자체 캐싱이 있는 스크립트: 일부 작업에는 자체 내부 캐싱 동작이 있습니다. 이러한 경우 Turborepo의 캐시와 애플리케이션 캐시가 함께 작동하도록 구성이 빠르게 복잡해질 수 있습니다.
이러한 상황은 드물지만 특정 위치에서 캐싱을 비활성화하는 것이 성능 이점을 제공하는지 확인하기 위해 프로젝트의 동작을 테스트해야 합니다.
다음 단계
이제 Turborepo의 캐싱이 저장소를 어떻게 더 빠르게 만드는지 보았으므로 Turborepo에서 애플리케이션과 라이브러리를 개발하는 방법을 살펴보겠습니다.