[IntelliJ IDEA] 인텔리제이와 Maven 프로젝트 연동

📌 핵심 요약

• 사전 준비 — JDK, Apache Tomcat, IntelliJ IDEA Ultimate 설치 필요
• Maven 자동 처리 — pom.xml만 올바르면 의존성은 IntelliJ가 자동으로 다운로드
• 핵심 설정 순서 — SDK 지정 → 웹 팩셋 → 아티팩트 → 톰캣 연결 순으로 진행

 

목차

1 사전 준비물 설치

메이븐 프로젝트를 깃허브에서 가져온 후 로컬 실행이 되도록 프로젝트를 연동하려고 합니다.

프로젝트를 IntelliJ에서 실행하기위해서 아래 세 가지가 먼저 설치되어 있어야 합니다.

Maven은 IntelliJ에 내장되어 있으므로 별도 설치가 필요 없습니다.

준비물	권장 버전	역할
JDK	프로젝트에 맞는 버전	Java 컴파일 및 실행 환경. 환경변수 JAVA_HOME 설정 필요
Apache Tomcat	프로젝트에 맞는 버전	웹 애플리케이션을 구동하는 서버. 설치 경로를 기억해 둘 것
IntelliJ IDEA	Ultimate 권장	개발 도구. Community 버전은 웹·서버 관련 기능이 제한됨

⚠️

JDK 버전 주의

프로젝트의 pom.xml에 명시된 Java 버전과 IntelliJ에 등록된 JDK 버전을 반드시 일치시켜야 합니다. 버전이 다르면 빌드 오류 또는 런타임 오류가 발생합니다.

2 SDK(JDK) 설정

IntelliJ가 어떤 Java 버전으로 컴파일할지 지정하는 단계입니다. 프로젝트를 처음 열면 SDK가 비어 있는 경우가 많으므로 반드시 확인합니다.

1. File → Project Structure (단축키: Ctrl + Alt + Shift + S)
2. 왼쪽 메뉴에서 Project 클릭
3. SDK 드롭다운에서 사용할 JDK 선택
   목록에 없으면 "Add SDK → JDK" 클릭 후 JDK 설치 경로 지정
4. Language level을 프로젝트 Java 버전에 맞게 선택

ℹ️

Language level이란?

컴파일러가 허용할 Java 문법의 최대 버전을 지정하는 설정입니다. SDK 버전보다 높게 설정하면 빌드가 실패하므로, SDK 버전과 동일하거나 낮게 맞춰주세요.

3 Maven 의존성 확인 및 갱신

Maven 프로젝트는 pom.xml에 선언된 라이브러리를 자동으로 다운로드합니다. 프로젝트를 열면 IntelliJ가 자동으로 의존성을 받아오지만, 수동으로 강제 갱신이 필요한 경우도 있습니다.

의존성 수동 갱신 방법

1. 우측 Maven 패널 클릭 (없으면 View → Tool Windows → Maven)
2. 패널 상단의 새로고침 버튼 (Reload All Maven Projects) 클릭
3. 하단 Build 탭에서 다운로드 진행 상황 확인
4. 완료 후 빨간 줄(의존성 오류)이 사라지면 정상

 

pom.xml — Spring MVC + Servlet 기본 의존성 예시

<dependencies>

  <!-- Spring MVC -->
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>5.3.39</version>
  </dependency>

  <!-- Servlet API (provided: 톰캣이 이미 포함) -->
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <scope>provided</scope>
  </dependency>

</dependencies>

💡

scope: provided란?

Servlet API처럼 톰캣이 이미 제공하는 라이브러리는 provided로 설정합니다. 이렇게 하면 빌드 결과물(war)에 해당 라이브러리가 포함되지 않아 충돌을 방지할 수 있습니다.

4 웹 팩셋(Web Facet) 설정

팩셋(Facet)은 IntelliJ에게 "이 프로젝트는 웹 프로젝트이고, 웹 루트 폴더는 여기야"라고 알려주는 설정입니다.

Maven 웹 프로젝트라면 대부분 src/main/webapp이 웹 루트입니다.

1. File → Project Structure → 왼쪽 Facets 클릭
2. Web 팩셋이 자동으로 추가되어 있는지 확인
   없으면 "+" → "Web" 클릭 후 모듈 선택
3. [Deployment Descriptors] 항목에서 web.xml 경로 확인
   기본값: src/main/webapp/WEB-INF/web.xml
4. [Web Resource Directories] 항목에서 웹 루트 경로 확인
   기본값: src/main/webapp → Web Resource Directory: /

🚨

웹 루트 경로가 잘못되면 404 발생

웹 루트가 src/main/webapp이 아닌 다른 경로로 지정되어 있으면 배포 후 빈 페이지 또는 404 오류가 발생합니다. 반드시 실제 webapp 폴더 위치와 일치시키세요.

5 아티팩트(Artifact) 설정

아티팩트는 소스코드와 의존성을 묶어 톰캣에 올릴 배포 패키지를 만드는 설정입니다.

Maven 웹 프로젝트에서는 주로 war exploded 방식을 사용합니다.

war vs war exploded 차이

방식	특징	개발 시 사용
war	단일 .war 파일로 압축 배포	비권장
war exploded	압축 없이 폴더 그대로 배포, 핫리로드 가능	권장

1. File → Project Structure → Artifacts 클릭
2. "+" → "Web Application: Exploded" → "From Modules..."
3. 모듈 선택 후 OK
4. Output directory는 기본값 유지 → OK

6 톰캣 서버 연결

IntelliJ에서 직접 톰캣을 실행하도록 실행 구성(Run Configuration)을 설정합니다.

1. 상단 메뉴 Run → Edit Configurations
2. 좌측 상단 "+" → "Tomcat Server" → "Local"
3. [Server 탭] — Application server의 "Configure..." 클릭
   → Tomcat Home에 설치 경로 지정 → JRE를 프로젝트 JDK에 맞게 선택
4. [Deployment 탭] — "+" → "Artifact..." 클릭
   → 프로젝트명:war exploded 선택 → OK
5. Application context 입력: / (루트) 또는 원하는 경로
6. OK 후 상단 초록 실행 버튼 클릭

💡

On 'Update' action 설정

Server 탭에서 On 'Update' action을 "Update classes and resources"로 설정하면 코드 수정 후 서버 재시작 없이 변경사항을 반영할 수 있습니다.

7 빌드 및 실행 확인

1. Build → Build Project (Ctrl + F9) — 빨간 줄 없이 완료되면 정상
2. 상단 실행 버튼 (▶) 클릭 또는 Shift + F10
3. 하단 콘솔에 "Artifact is deployed successfully" 메시지 확인
4. 브라우저에서 http://localhost:8080/ (또는 설정한 context 경로) 접속

ℹ️

포트 충돌 오류가 발생하면

Address already in use: 8080 오류는 이미 다른 프로세스가 8080 포트를 사용 중인 경우입니다. 톰캣 설정에서 HTTP port를 8081 등 다른 포트로 변경하거나, 기존 프로세스를 종료하세요.

8 자주 발생하는 오류와 해결법

오류 1 — 의존성 빨간 줄 (Cannot resolve symbol)

Maven 의존성이 로컬에 없거나 아직 다운로드되지 않은 경우입니다.

Maven 패널에서 Reload All Maven Projects 버튼을 클릭하거나, 터미널에서 mvn install을 실행하세요.

오류 2 — 404 Not Found

웹 팩셋의 웹 루트 경로가 잘못 지정된 경우가 가장 흔합니다.

Project Structure → Facets → Web에서 Web Resource Directory가 실제 webapp 폴더를 가리키는지 확인하세요. Application context 경로와 접속 URL이 일치하는지도 확인합니다.

오류 3 — 서버 시작 실패 (Context initialization failed)

Spring 설정 파일(XML 또는 @Configuration)의 오류이거나 DB 연결 실패입니다.

콘솔의 Caused by: 라인을 따라가면 실제 원인을 확인할 수 있습니다.

오류 4 — ClassNotFoundException / NoClassDefFoundError

아티팩트에 라이브러리가 포함되지 않은 경우입니다.

Project Structure → Artifacts에서 해당 아티팩트를 선택하고, Available Elements에 있는 라이브러리를 더블클릭하여 WEB-INF/lib에 추가하세요.

오류 5 — web.xml 버전 오류

Tomcat 버전이 Servlet 버전과 맞지 않은 경우입니다.

필자가 사용한 Tomcat 8.5는 Servlet 3.1까지만 지원합니다.

web.xml 상단의 version="4.0"은 Tomcat 9 이상에서만 동작합니다.

사용 중인 Tomcat 버전에 맞게 Servlet 버전을 조정하세요.

Tomcat 버전	지원 Servlet 버전	web.xml version 값
Tomcat 8.5	Servlet 3.1	version="3.1"
Tomcat 9	Servlet 4.0	version="4.0"
Tomcat 10	Servlet 5.0 (Jakarta)	version="5.0"

잘못된 내용이 있다면 지적부탁드립니다. 방문해주셔서 감사합니다.