Gradle 빌드가 갑자기 느려졌을 때 가장 먼저 보는 곳

 

gradle clean을 치면 빌드가 빨라진다고 생각하신다면, 사실 그 습관이 다음 빌드를 가장 느리게 만들고 있는 거예요.

 

clean을 실행하면 증분 빌드(Incremental Build) 캐시가 통째로 날아가거든요. 그다음 빌드는 모든 파일을 처음부터 다시 컴파일해야 합니다. 어제 3초였던 빌드가 오늘 45초로 튄다면, 무턱대고 clean을 치기 전에 진짜 원인부터 짚어야 해요.

 

증분 빌드 상태 꼬임이 빌드 느려짐의 첫 번째 원인

빌드가 갑자기 느려졌을 때 제일 먼저 해볼 수 있는 건 프로젝트 로컬 캐시를 초기화하는 것입니다. 저장된 캐시가 손상되면 gradle은 모든 task를 처음부터 다시 실행하게 되거든요. 평소보다 빌드 시간이 2~5배 늘어나는 경우가 생겨요.

 

해결 순서는 이렇습니다.

1. 프로젝트 최상단의 .gradle 폴더(숨김 폴더)를 삭제합니다. 사용자 홈 디렉토리의 글로벌 캐시(~/.gradle/caches)를 통째로 날리면 다운받아둔 라이브러리 파일까지 모두 지워져서 다음 빌드 때 인터넷에서 전부 새로 다운받느라 엄청난 시간이 걸리거든요. 

2. gradle build를 실행합니다. clean 없이요. 캐시만 새로 쌓으면 되는 상황이라 clean은 이 단계에서 필요하지 않습니다.

3. 그래도 느리다면 gradle build --profile로 task별 소요 시간을 확인합니다. 이건 뒤에서 자세히 설명할게요.

 

캐시 손상은 git 브랜치를 자주 오가거나 의존성 버전을 급하게 올렸을 때 특히 자주 생기더라구요.

 

Gradle 데몬 메모리 누수와 gradle clean의 진짜 차이

 

gradle은 빌드 속도를 높이기 위해 백그라운드에 데몬(daemon) 프로세스를 띄워 둡니다. 처음엔 빠른데, 며칠 동안 계속 돌리다 보면 JVM 메모리가 쌓이면서 GC(가비지 컬렉션) 오버헤드가 늘어나거든요. 어느 순간부터 아무 이유 없이 빌드가 조금씩 느려지는 느낌이 드는 게 바로 이 때문일 때가 많습니다.

 

이때 많이들 gradle clean을 치는데, 이건 잘못된 처방이에요. clean은 build/ 폴더 안의 결과물만 지울 뿐, 데몬 자체는 건드리지 않거든요. 오히려 증분 캐시까지 날려버려서 다음 빌드가 훨씬 더 오래 걸리는 상황을 만들기도 합니다.

 

빌드가 이유 없이 느려졌을 때는 gradle clean보다 아래 명령어를 먼저 쳐야 합니다. 떠 있는 데몬을 모두 종료하면 다음 빌드에서 새 데몬이 깔끔하게 올라오거든요.

 

# 현재 실행 중인 데몬 상태 확인
gradle --status

# 실행 중인 모든 데몬 강제 종료
gradle --stop

 

데몬 메모리 한도를 직접 잡아두려면 gradle.properties에 이렇게 추가하시면 됩니다.

 

org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m

 

-Xmx2g는 JVM 최대 힙 메모리를 2GB로 제한하는 설정이에요. 2GB가 어느 정도냐면, 보통 멀티 모듈 안드로이드(Android) 프로젝트 혹은 스프링(Spring) 프로젝트 한 번 컴파일하는 데 1.5GB 정도가 잡히는 편이라 2GB면 여유가 좀 있는 수준이거든요. 프로젝트 규모에 따라 1g~4g 사이에서 조절하면 됩니다.

 

의존성 해석 병목이 전체 빌드 시간의 30~50%를 잡아먹는 이유

코드를 전혀 건드리지 않았는데 빌드가 느린 경우, 의존성 해석 단계를 의심해 볼 필요가 있어요. gradle은 라이브러리를 가져올 때 그 라이브러리가 또 어떤 라이브러리를 쓰는지를 전부 추적하거든요. 이걸 트랜지티브 의존성(Transitive Dependency)이라고 부르는데, 의존성이 복잡한 프로젝트에서는 이 추적 과정이 전체 빌드 시간의 30~50%를 차지하기도 한다는 얘기입니다.

 

네트워크 상태가 나쁜 날엔 메이븐 센트럴(Maven Central) 연결 자체가 1~3분씩 지연될 수 있어요. 이게 gradle 자체 문제처럼 느껴져서 의외로 놓치기 쉬운 부분이거든요.

 

gradle.properties에 아래 두 줄을 추가하면 로컬 빌드 캐시와 병렬 처리를 동시에 켤 수 있습니다.

 

org.gradle.parallel=true
org.gradle.caching=true

 

병렬 처리를 쉽게 설명하자면, 멀티 모듈 프로젝트에서 서로 의존하지 않는 모듈들을 동시에 컴파일하는 방식이에요. 모듈이 많을수록 효과가 크고, 빌드 시간이 10~40% 줄어들기도 합니다. 단일 모듈 프로젝트라면 체감 차이가 크지 않은 편이구요.

 

gradle --profile로 Gradle 빌드 병목 정확히 찾기

 

원인을 추측하는 것보다 측정하는 게 확실히 빠릅니다. gradle build --profile을 실행하면 빌드가 완료된 후 build/reports/profile/ 폴더에 HTML 리포트가 생성됩니다. 브라우저로 열면 각 task별 실행 시간이 한눈에 보이거든요.

 

저는 이 리포트를 처음 열었을 때 솔직히 좀 놀랐네요. 의존성 해석 단계 하나에서 전체 빌드 시간의 40% 이상이 나오더라구요. 코드만 열심히 보고 있었는데 진짜 병목은 엉뚱한 곳에 있었던 셈이에요.

 

개인적으로는 --profile보다 --scan 옵션이 더 직관적이라고 봅니다. gradle build --scan을 실행하면 gradle 공식 스캔 서버에 결과가 업로드되면서 훨씬 풍부한 시각화를 제공하거든요. 다만 빌드 결과가 외부로 나간다는 점은 팀 정책에 따라 미리 확인이 필요한 부분이에요.

 

팀원은 빠른데 나만 Gradle 빌드가 느린 원인: 로컬 캐시 불일치

팀 전체가 아니라 나 혼자만 빌드가 느리다면, 로컬 캐시 불일치 문제인 경우가 꽤 있거든요. git 브랜치를 전환한 직후나 의존성 버전 충돌이 생겼을 때 캐시 유효성이 깨지면서 이런 증상이 나타나는 편입니다.

 

이럴 때 확인 순서입니다.

1. gradle --stop으로 실행 중인 데몬을 모두 종료합니다.

2. 프로젝트 내 .gradle 폴더를 삭제하고 재빌드합니다.

3. 그래도 팀원과 차이가 난다면 JDK 버전 또는 gradle 버전이 서로 다른지 확인해야 합니다. CI(Jenkins, GitHub Actions 등) 환경과 로컬 환경의 버전이 미묘하게 달라서 생기는 경우가 생각보다 자주 있더라구요.

 

한 가지 더, CI에서는 매 빌드마다 클린 상태로 돌리기 때문에 로컬 캐시 최적화가 CI에는 그대로 통하지 않습니다. 로컬 개선과 CI 개선은 서로 다른 방향(예: CI용 원격 빌드 캐시 도입 등)으로 접근해야 합니다.

 

마치며: Gradle 빌드 진단 3단계 루틴

 

빌드 속도 문제는 원인만 찾으면 대부분 10분 안에 해결할 수 있는 것이 대부분입니다. 추측으로 clean을 남발할수록 다음 빌드가 더 길어지는 악순환에 빠질 수 있으니 주의해야겠습니다.

 

순서는 단순합니다.

1. gradle --stop으로 데몬 정리

2. 프로젝트 내 .gradle 삭제 후 재빌드

3. gradle build --profile로 병목 확인

 

이 세 단계를 손에 익혀두시라고 꼭 말씀드리고 싶네요. clean부터 누르던 습관을 측정 한 번으로 바꾸시면, 빌드 시간을 체감 절반 이하로 줄이는 일이 결코 어렵지 않습니다.