🪶
Maven 치트시트

Maven Wrapper(mvnw) 명령어, pom.xml 구조, 라이프사이클, 의존성 스코프, 플러그인 및 멀티 모듈 레퍼런스
#maven#mvn#pom#build#java#spring#dependencies#lifecycle#plugins최종 업데이트: 2026-09-26
Maven 치트시트 핵심 명령어 및 실전 가이드

Maven Wrapper(mvnw) 명령어, pom.xml 구조, 라이프사이클, 의존성 스코프, 플러그인 및 멀티 모듈 레퍼런스
## 1. Maven Wrapper (mvnw) & 핵심 CLI 명령어
```bash
# 1. 빌드 및 패키징
./mvnw clean compile            # target/ 디렉토리 정리 후 소스 코드 컴파일
./mvnw clean package            # 컴파일 + 테스트 수행 후 JAR/WAR 생성
./mvnw clean install            # 패키징 후 로컬 저장소(~/.m2/repository)에 배포

# 2. 테스트 스킵 옵션 (차이점 주의!)
./mvnw clean package -DskipTests               # 테스트 컴파일은 수행하되 실행만 건너뜀 (권장)
./mvnw clean package -Dmaven.test.skip=true     # 테스트 컴파일 및 실행을 모두 건너뜀

# 3. 디버그 및 강제 업데이트
./mvnw clean package -U         # 원격 저장소의 SNAPSHOT 및 의존성 캐시 강제 갱신
./mvnw clean package -X         # 상세 디버그 로그 출력 (원인 분석 시)
./mvnw clean package -e         # 에러 발생 시 전체 스택트레이스 출력

# 4. 멀티스레드 병렬 빌드 (속도 최적화)
./mvnw clean package -T 4       # 4개 스레드로 병렬 빌드
./mvnw clean package -T 1C      # CPU 코어당 1개 스레드로 자동 할당

# 5. Spring Boot 로컬 실행
./mvnw spring-boot:run                         # 스프링 부트 앱 즉시 실행
./mvnw spring-boot:run -Dspring-boot.run.profiles=local  # 프로파일 지정 실행
```

## 2. 기본 빌드 라이프사이클 (Build Lifecycle)
```text
[Maven 3대 표준 라이프사이클]
1. clean   : 이전 빌드 산출물(target/) 제거
2. default : 소스 배포 및 패키징 (핵심)
3. site    : 프로젝트 문서 및 사이트 생성

[default 라이프사이클 주요 페이즈(Phase) 순서]
validate   → 프로젝트 상태 및 필수 정보 검증
compile    → 소스 코드 컴파일 (src/main/java → target/classes)
test       → 단위 테스트 실행 (테스트 실패 시 빌드 중단)
package    → 컴파일된 코드를 JAR/WAR 등 배포 포맷으로 압축
verify     → 통합 테스트 결과 검증
install    → 빌드된 패키지를 로컬 저장소(~/.m2)에 등록
deploy     → 원격 레포지토리(Nexus, Artifactory)에 최종 배포
```

## 3. pom.xml 기본 골격 & 표준 디렉토리
```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <!-- 1. 프로젝트 좌표 (GAV) -->
  <groupId>com.example</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>jar</packaging> <!-- jar, war, pom -->

  <!-- 2. 공통 프로퍼티 (Java 버전, 인코딩) -->
  <properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
</project>
```
```text
[Maven 표준 디렉토리 구조]
src/main/java        → 프로덕션 Java 소스 코드
src/main/resources   → 설정 파일 (application.yml 등) 및 정적 리소스
src/test/java        → 단위/통합 테스트 코드
src/test/resources   → 테스트용 설정 파일
target/              → 컴파일 산출물 및 최종 JAR/WAR 파일 생성 경로
pom.xml              → 프로젝트 객체 모델(POM) 설정 파일
```

## 4. 의존성 스코프 (Dependency Scopes)
```xml
<dependencies>
  <!-- 1. compile (기본값): 모든 클래스패스(컴파일, 실행, 테스트)에 포함, 전이 의존성 전파 -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <!-- 2. provided: 컴파일/테스트에만 필요, 런타임에는 컨테이너/JDK가 제공 (JAR 패키징 제외) -->
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <scope>provided</scope>
  </dependency>

  <!-- 3. runtime: 컴파일에는 불필요, 런타임 및 테스트 실행 시에만 필요 -->
  <dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
  </dependency>

  <!-- 4. test: 테스트 컴파일 및 실행에만 필요, 최종 배포 산출물에서 제외 -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>

  <!-- 5. import: dependencyManagement 안에서 BOM(Bill of Materials) 가져올 때만 사용 -->
</dependencies>
```

## 5. 의존성 관리 & 충돌 해결 (Tree & Exclusions)
```bash
# 1. 의존성 트리 출력 (버전 충돌 및 전이 의존성 확인)
./mvnw dependency:tree

# 2. 특정 라이브러리 검색 필터
./mvnw dependency:tree -Dincludes=org.slf4j:*

# 3. 사용되지 않거나 누락된 의존성 정적 분석
./mvnw dependency:analyze
```
```xml
<!-- 의존성 제외 (Exclusion): 중복되거나 충돌하는 전이 의존성 차단 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId> <!-- 내장 톰캣 제외 (Undertow 등 교체 시) -->
    </exclusion>
  </exclusions>
</dependency>

<!-- dependencyManagement: 하위 모듈/의존성의 버전 중앙 집중 관리 (BOM 패턴) -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2023.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```

## 6. 주요 플러그인 설정 (Plugins)
```xml
<build>
  <plugins>
    <!-- 1. Java 컴파일러 & Annotation Processor(Lombok/MapStruct) -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.11.0</version>
      <configuration>
        <source>17</source>
        <target>17</target>
        <annotationProcessorPaths>
          <path>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>

    <!-- 2. 단위 테스트 (단일 테스트: ./mvnw test -Dtest=UserServiceTest) -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.2.5</version>
    </plugin>

    <!-- 3. Spring Boot 실행 가능한 Fat JAR 패키징 -->
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>
```

## 7. 멀티 모듈 프로젝트 (Multi-Module)
```xml
<!-- [Root pom.xml] -->
<groupId>com.example</groupId>
<artifactId>root-project</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging> <!-- 루트는 반드시 pom 패키징 -->

<modules>
  <module>core-module</module>
  <module>api-module</module>
</modules>

<!-- [Child api-module/pom.xml] -->
<parent>
  <groupId>com.example</groupId>
  <artifactId>root-project</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <relativePath>../pom.xml</relativePath>
</parent>

<artifactId>api-module</artifactId>
<dependencies>
  <!-- 같은 프로젝트 내 다른 형제 모듈 참조 -->
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>core-module</artifactId>
    <version>${project.version}</version>
  </dependency>
</dependencies>
```
```bash
# 멀티 모듈 빌드 꿀팁
./mvnw clean package -pl api-module -am   # api-module과 필요한 상위 의존 모듈만 골라서 빌드
./mvnw clean package -pl core-module     # core-module 하나만 단독 빌드
```

## 8. 빌드 프로파일 & 환경 분리 (Profiles)
```xml
<profiles>
  <!-- 로컬 개발 환경 프로파일 -->
  <profile>
    <id>local</id>
    <activation>
      <activeByDefault>true</activeByDefault> <!-- 기본 활성화 -->
    </activation>
    <properties>
      <env>local</env>
    </properties>
  </profile>

  <!-- 운영 환경 프로파일 -->
  <profile>
    <id>prod</id>
    <properties>
      <env>prod</env>
    </properties>
  </profile>
</profiles>
```
```bash
# 특정 프로파일을 활성화하여 빌드
./mvnw clean package -P prod
./mvnw clean package -P local,metrics    # 쉼표로 다중 프로파일 적용
```

## 9. 리소스 필터링 (Resource Filtering)
```xml
<!-- application.yml 내 @env@ 또는 ${env} 변수 치환 활성화 -->
<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering> <!-- 프로퍼티 값 자동 치환 -->
      <includes>
        <include>**/*.properties</include>
        <include>**/*.yml</include>
        <include>**/*.xml</include>
      </includes>
    </resource>
  </resources>
</build>
```
```yaml
# src/main/resources/application.yml 예시
spring:
  profiles:
    active: @env@ # Maven 빌드 시 프로파일 변수로 치환됨
```

## 10. 실무 트러블슈팅 & 꿀팁 (Tips & Troubleshooting)
```bash
# 1. Maven Wrapper 생성 또는 버전 업그레이드
mvn wrapper:wrapper -Dmaven=3.9.6

# 2. 로컬 캐시(~/.m2/repository) 꼬임 해결
# 빌드 실패나 corrupted jar 발생 시 해당 라이브러리 폴더 삭제 후 -U 옵션으로 재다운로드
rm -rf ~/.m2/repository/com/example/corrupted-lib/
./mvnw clean package -U

# 3. 단일 테스트 클래스 또는 특정 메서드만 실행
./mvnw test -Dtest=OrderServiceTest
./mvnw test -Dtest=OrderServiceTest#testCreateOrder

# 4. 배포 및 원격 저장소 등록 (pom.xml 내 distributionManagement 설정 필요)
./mvnw clean deploy

# 5. 오프라인 모드 빌드 (외부 네트워크 호출 차단)
./mvnw clean package -o
```
💬
Maven 치트시트

의견 및 질문

댓글 수정

댓글 삭제
