자바 프로젝트 빌드 전 필수! DOS(CMD)에서 “Maven 실행하는 방법”

들어가며

Java 프로젝트를 개발하다 보면 한 번쯤 이런 명령어를 만나게 됩니다.

mvn clean package

처음 보는 사람에게는 별것 아닌 명령어처럼 보이지만, 막상 Windows의 CMD(명령 프롬프트)에서 실행하면 mvn은 내부 또는 외부 명령, 실행할 수 있는 프로그램 또는 배치 파일이 아닙니다. 같은 오류가 발생하는 경우가 있습니다.

특히 Java를 처음 설치한 PC라면 Java는 설치되어 있는데 Maven이 실행되지 않거나, Maven은 설치했는데 JAVA_HOME 때문에 오류가 발생하는 경우도 있습니다.

그렇다면 mvn clean package를 실행하기 전에 무엇을 준비해야 할까요?

오늘은 Windows CMD에서 Maven의 mvn clean package를 정상적으로 실행하기 위해 필요한 기본 작업을 순서대로 정리해 보겠습니다.

1. 먼저 Java가 설치되어 있어야 합니다

Maven은 Java 프로젝트를 빌드하는 도구이기 때문에 먼저 JDK가 준비되어 있어야 합니다.

CMD를 실행한 다음 다음 명령어를 입력해 보세요.

java -version

정상적으로 설치되어 있다면 현재 설치된 Java 버전이 표시됩니다.

예를 들어 다음과 비슷한 결과가 나옵니다.

java version "21.x.x"

또는 사용하는 JDK에 따라 다른 버전이 표시될 수 있습니다.

여기서 중요한 것은 단순히 java 명령어가 실행되는 것뿐만 아니라 JDK가 정상적으로 설치되어 있는지 확인하는 것입니다.

Maven을 이용해 Java 프로젝트를 빌드할 예정이라면 JDK 환경을 제대로 구성해 두는 것이 좋습니다.

2. JAVA_HOME 환경변수를 확인합니다

Maven을 실행할 때 JAVA_HOME 환경변수가 제대로 설정되어 있지 않으면 오류가 발생할 수 있습니다.

CMD에서 다음 명령어를 입력합니다.

echo %JAVA_HOME%

정상적으로 설정되어 있다면 JDK가 설치된 경로가 표시됩니다.

예를 들면 다음과 같은 형태입니다.

C:\Program Files\Java\jdk-21

컴퓨터마다 설치 위치와 JDK 버전은 다를 수 있습니다.

만약 아무것도 표시되지 않거나 잘못된 경로가 나온다면 Windows 환경변수 설정을 확인해야 합니다.

3. Maven이 설치되어 있는지 확인합니다

Java가 정상적으로 실행된다고 해서 Maven까지 설치되어 있는 것은 아닙니다.

이번에는 다음 명령어를 입력합니다.

mvn -version

정상적으로 Maven이 설치되어 있고 PATH까지 설정되어 있다면 Maven 버전과 Java 정보 등이 표시됩니다.

예를 들어 다음과 같은 정보가 나타날 수 있습니다.

Apache Maven 3.x.x
Maven home: ...
Java version: ...
Java home: ...

반대로 다음과 같은 메시지가 나온다면 문제가 있는 것입니다.

'mvn'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램 또는
배치 파일이 아닙니다.

이 경우에는 Maven이 설치되지 않았거나 Maven의 bin 폴더가 PATH에 등록되지 않은 경우를 먼저 확인해야 합니다.

4. Maven을 설치하고 PATH를 설정합니다

Maven을 직접 설치했다면 Windows 환경변수의 Path에 Maven의 bin 폴더를 등록해야 합니다.

예를 들어 Maven을 다음과 같은 위치에 압축 해제했다고 가정해 보겠습니다.

C:\apache-maven-3.x.x

그렇다면 PATH에는 일반적으로 다음과 같은 경로가 들어갑니다.

C:\apache-maven-3.x.x\bin

환경변수를 수정한 뒤에는 기존 CMD 창을 닫고 새로운 CMD 창을 다시 실행하는 것이 좋습니다.

그다음 다시 확인합니다.

mvn -version

Maven 버전이 정상적으로 표시된다면 기본적인 환경 설정은 끝난 것입니다.

5. Maven Wrapper를 사용하는 프로젝트라면 별도 설치가 필요 없을 수도 있습니다

여기서 하나 알아둘 것이 있습니다.

모든 Java 프로젝트가 반드시 PC에 Maven을 직접 설치해야 하는 것은 아닙니다.

프로젝트 폴더에 다음과 같은 파일이 있다면 Maven Wrapper를 사용하는 프로젝트일 가능성이 있습니다.

mvnw
mvnw.cmd

Windows에서는 다음과 같이 실행할 수 있습니다.

mvnw.cmd clean package

또는 CMD에서 상황에 따라 다음과 같이 실행할 수도 있습니다.

mvnw clean package

Maven Wrapper는 프로젝트에서 지정한 Maven 버전을 사용하기 때문에 프로젝트마다 다른 Maven 버전을 사용해야 하는 상황에서 특히 편리합니다.

따라서 프로젝트에 mvnw.cmd가 있다면 무조건 Maven을 별도로 설치하기 전에 Wrapper 사용 여부를 확인해 보는 것도 좋습니다.

6. 프로젝트 폴더로 이동해야 합니다

이제 Maven 실행 환경이 준비됐다면 실제 프로젝트 폴더로 이동해야 합니다.

예를 들어 프로젝트가 다음 위치에 있다고 가정해 보겠습니다.

C:\workspace\myproject

CMD에서 다음과 같이 입력합니다.

cd C:\workspace\myproject

현재 위치가 제대로 이동했는지 확인하려면 다음 명령어를 사용할 수 있습니다.

dir

여기서 Java Maven 프로젝트라면 보통 다음과 같은 파일을 찾을 수 있습니다.

pom.xml

이 pom.xml 파일이 중요한 포인트입니다.

Maven은 pom.xml을 기준으로 프로젝트의 의존성, 빌드 설정, 플러그인 등을 확인하기 때문입니다.

7. pom.xml이 있는 위치에서 mvn clean package를 실행합니다

이제 드디어 다음 명령어를 실행합니다.

mvn clean package

이 명령어는 크게 clean과 package 두 단계로 생각하면 이해하기 쉽습니다.

clean

mvn clean

이 단계에서는 이전 빌드 결과물 등을 정리합니다.

일반적인 Maven 프로젝트에서는 기존 target 디렉터리가 정리됩니다.

package

mvn package

프로젝트를 컴파일하고 테스트 등의 빌드 과정을 거쳐 패키지 파일을 생성합니다.

Java 애플리케이션이라면 프로젝트 설정에 따라 JAR 또는 WAR 등의 결과물이 생성될 수 있습니다.

그래서 다음과 같이 한 번에 실행하는 것입니다.

mvn clean package

기존 빌드 결과를 정리한 다음 새롭게 프로젝트를 빌드하고 패키징하는 과정이라고 이해하면 됩니다.

8. 빌드가 끝나면 target 폴더를 확인합니다

빌드가 정상적으로 완료되면 프로젝트 폴더 아래에 target 디렉터리가 생성되는 것을 확인할 수 있습니다.

예를 들면 다음과 같은 구조입니다.

myproject
 ├─ src
 ├─ pom.xml
 └─ target

프로젝트 설정에 따라 target 안에 JAR 또는 WAR 파일 등이 생성됩니다.

마지막에 다음과 같은 메시지가 표시된다면 빌드가 성공적으로 끝난 것입니다.

BUILD SUCCESS

반대로

BUILD FAILURE

가 표시된다면 빌드 과정에서 오류가 발생한 것입니다.

9. 자주 발생하는 오류도 미리 알아두면 좋습니다

mvn clean package가 실행되지 않는 대표적인 원인은 몇 가지가 있습니다.

첫 번째는 Maven 자체가 인식되지 않는 경우입니다.

'mvn'은(는) 내부 또는 외부 명령...

이 경우 Maven 설치 여부와 PATH 설정을 확인해야 합니다.

두 번째는 Java 환경변수 문제입니다.

The JAVA_HOME environment variable is not defined correctly

이런 메시지가 나온다면 JAVA_HOME이 올바른 JDK 경로를 가리키고 있는지 확인해야 합니다.

세 번째는 프로젝트 위치가 잘못된 경우입니다.

pom.xml이 없는 폴더에서 Maven 명령어를 실행하면 프로젝트를 찾지 못할 수 있습니다.

따라서 다음 명령어로 현재 위치를 확인하고,

dir

pom.xml이 있는 폴더에서 mvn clean package를 실행하는 것이 중요합니다.

마무리

Windows CMD에서 mvn clean package를 실행하는 방법 자체는 어렵지 않습니다.

다만 처음 설정할 때 몇 가지 준비가 필요합니다.

순서를 간단하게 정리하면 다음과 같습니다.

1. JDK 설치
2. java -version 확인
3. JAVA_HOME 확인
4. Maven 설치 또는 Maven Wrapper 확인
5. mvn -version 확인
6. pom.xml이 있는 프로젝트 폴더로 이동
7. mvn clean package 실행
8. target 폴더와 BUILD SUCCESS 확인

특히 처음부터 mvn clean package만 입력하고 오류가 발생했다고 당황할 필요는 없습니다.

먼저

java -version

그다음

mvn -version

을 실행해 Java와 Maven이 각각 정상적으로 인식되는지 확인하는 것이 좋습니다.

그리고 프로젝트 폴더에 pom.xml이 있는지도 확인해 보세요.

개발 환경을 새로 구성할 때는 Maven 자체의 문제보다 JAVA_HOME, PATH, 현재 CMD 위치 때문에 명령어가 실행되지 않는 경우가 생각보다 많습니다.

이 세 가지만 먼저 확인하는 습관을 들여놓으면 mvn clean package와 관련된 오류를 만났을 때도 어디부터 살펴봐야 할지 훨씬 쉽게 판단할 수 있습니다.