[Maven] clean / package / --offline / -U 실무 정리

Maven을 쓰다 보면 아래 명령어들을 습관처럼 사용하게 된다.

 

mvn clean package
mvn clean package -U
mvn clean package --offline

 

그런데 각각의 의미를 정확히 모르고 쓰면 문제가 생긴다.

CI/CD에서 빌드가 실패하거나, 캐시가 꼬이거나, Nexus 이슈로 이어지는 경우가 실제로 있었다.

이번 글은 실제 장애 케이스 기준으로 핵심만 정리한다.

 

1. clean – 빌드 초기화

이전 빌드 결과를 삭제하는 옵션이다.

내부적으로는 target/ 디렉토리를 통째로 지운다.

이게 왜 필요하냐면, 이전 빌드의 잔여물이 남아있으면 클래스 충돌이 발생할 수 있기 때문이다.

실무에서는 CI 빌드에 거의 무조건 포함한다.

mvn clean package

 

 

2. package – 실제 빌드 수행

컴파일 + 테스트 + 패키징을 순서대로 수행하는 옵션이다.

내부 흐름 compile → test → package  순서로 진행된다.

결과물은 target/*.jar 또는 target/*.war 형태로 생성된다.

Spring Boot 프로젝트라면 여기서 실행 가능한 jar가 만들어진다. 테스트도 함께 실행되기 때문에, 건너뛰고 싶다면 아래 옵션을 사용한다.

mvn clean package -DskipTests

 

 

 

3. --offline – 네트워크 차단 모드

remote repository를 아예 사용하지 않는 옵션이다.

로컬 Maven 저장소만 바라보기 때문에, Nexus에도 접근하지 않는다.

그래서 dependency가 로컬에 없으면 무조건 실패한다.

실제 에러 메시지는 아래처럼 뜬다.

Cannot access ... in offline mode

 

dependency를 미리 받아놓지 않으면 바로 터지는 구조다.

이 옵션은 폐쇄망 환경이거나, dependency preload가 이미 완료된 상태일 때만 사용한다.

한마디로 "이미 다 받아놨을 때만 쓰는 옵션"이다.

 

 

 

4. -U – 강제 업데이트

Maven 캐시를 무시하고 remote repository를 강제로 재조회하는 옵션이다.

 

특히 SNAPSHOT 아티팩트에 효과적이다. Maven은 SNAPSHOT을 일정 주기로만 재조회하는데, -U를 붙이면 주기와 관계없이 강제로 최신 버전을 다시 확인한다.

이게 왜 중요하냐면, Maven은 단순 캐시가 아니기 때문이다.

Maven은 "없는 dependency도 캐싱한다".

 

문제 상황을 예로 들면, Nexus 요청이 실패하면 Maven은 "이거 없음"을 기억한다. 그 이후 빌드에서도 계속 실패한다.

이때 실제 로그에서 아래 문구가 뜬다.

 

resolution will not be reattempted

 

 

이 상태가 되면 Nexus가 정상으로 돌아와도 빌드가 계속 실패한다.

이 순간 느끼는 것은 하나다.

Nexus 문제가 아닌데 Maven이 포기해버린 상태라는 것.

 

 

해결 방법은 단순하다.

mvn clean package -U

이 명령어를 실행하면 기존 캐시를 무시하고, Nexus를 다시 조회하며, metadata도 갱신된다.

언제 써야 하는지 정리하면 아래와 같다.

 

상황	사용 여부
최초 빌드	✅
Nexus 장애 이후	✅
캐시가 꼬였을 때	✅
평소 안정적인 빌드	❌

 

 

5. 전체 흐름 정리

Maven의 기본 동작은 로컬 repo를 먼저 확인하고, 있으면 사용, 없으면 Nexus를 조회하는 순서로 진행된다.

 

실무에서 자주 발생하는 문제 흐름은 이렇다.

 

Nexus에 artifact가 없으면 Maven이 "없음"을 캐싱하고, 이후 Nexus가 복구돼도 계속 실패 상태가 유지된다.

해결은 -U 하나로 끝난다.

mvn clean package -U

 

 

6. 실무 기준 추천 전략

CI/CD (TeamCity 기준)

초기 세팅 단계에서는 -U를 포함해서 실행한다.

clean package -U

 

 

안정화 이후에는 불필요한 재조회를 줄이기 위해 -U를 제거한다.

clean package

 

폐쇄망 + Nexus 환경

외부망에서 dependency preload를 먼저 진행하고, Nexus cache를 확보한 뒤, CI는 Nexus만 바라보도록 구성한다. --offline은 그 이후 선택적으로 사용한다.

 

7. 추가 팁: Maven 빌드 실패 = Maven 문제가 아닐 수 있다

빌드가 실패했다고 해서 항상 Maven 문제는 아니다.

아래와 같은 에러가 뜨는 경우가 있다.

Deployment problem: Auth fail

이건 Maven 이슈가 아니다. 배포 인증 문제, 즉 Nexus / WAS / SSH 쪽을 먼저 확인해야 한다.

로그를 꼼꼼히 읽는 것이 디버깅의 시작이다.

 

 

8. 정리

옵션	의미
clean	이전 빌드 결과 삭제
package	컴파일 + 테스트 + 패키징
--offline	로컬 저장소만 사용
-U	캐시 무시 + 강제 재조회

각 옵션은 단순히 명령어가 아니라 Maven의 동작 방식을 이해하고 써야 한다.

특히 -U는 왜 쓰는지 모르고 붙이는 것과 알고 쓰는 것의 차이가 크다.