[Spring Boot] Spring Initializr로 프로젝트 시작하기 (+인텔리제이 환경설정)

Spring Initializr를 이용한 프로젝트 생성 방법과 IntelliJ에서 발생할 수 있는 주요 오류 해결 방법 정리

1단계: Spring Initializr 설정 (start.spring.io)

먼저 Spring Initializr 사이트에서 프로젝트의 뼈대를 만든다.

 

[설정 예시]

• Project: Gradle - Groovy
• Language: Java
• Spring Boot: SNAPSHOT이나 M1이 붙지 않은 최신 정식 버전 (예: 4.0.x, 3.4.x 등)
• Project Metadata: Group, Artifact 이름 설정
• Packaging: Jar
• Java: 17 (현재 가장 많이 쓰이는 LTS 버전)

💡 중요: 여기서 Java 17을 골랐다면, 이후의 모든 IntelliJ 설정도 17로 통일해야 한다.

2단계: IntelliJ로 프로젝트 열기

1. 다운로드한 압축 파일(demo.zip)을 원하는 경로에 푼다.
2. IntelliJ 초기 화면에서 Open을 클릭한다.
3. 압축을 푼 demo 폴더를 선택하고 OK를 누른다.
4. Trust Project? 팝업이 뜨면 Trust Project를 클릭한다.

💡 프로젝트를 열었는데 오른쪽 사이드바에 Gradle 탭이 안 보일 경우 해결 방법

• 상단 메뉴에서 View > Tool Windows > Gradle을 선택
• 만약 Gradle 창이 열렸는데 내용이 비어 있다면, 창 상단의 + (Link Gradle Project) 버튼을 누르고 build.gradle 파일을 선택

3단계: IntelliJ 환경 설정

프로젝트를 열자마자 빌드 에러가 난다면 이 설정이 안 맞아서일 확률이 높다.

다음 세 가지를 확인하자.

1. Gradle JVM 설정

Gradle이 빌드할 때 사용할 자바 버전을 지정한다.

• 경로: Settings > Build, Execution, Deployment > Build Tools > Gradle
• 설정: Gradle JVM을 Java 17로 설정한다. (Project SDK와 동일한 버전)
  • 주의: 만약 JAVA_HOME 환경변수가 다른 버전으로 되어 있다면 여기서 명시적으로 17을 선택해줘야 한다.

2. Project SDK 설정

• 경로: File > Project Structure > Project
• 설정: SDK를 17로 설정한다.

3. Language Level 설정

• 경로: File > Project Structure > Project
• 설정: Language level을 SDK와 동일한 17로 맞춘다.
  • 주의: 목록 상단에 있는 SDK Default나 17 - Sealed types...를 선택.
  • 실수로 최신 버전인 24나 Preview 버전을 선택하면 컴파일 에러가 발생한다.

4단계: 자주 발생하는 오류와 해결법

설정을 다 했는데도 빨간 줄이 뜨거나 빌드가 안 될 때 해결하는 방법

상황 1: Undefined Toolchain Download Repositories 에러

• 증상: 빌드 창에 Source set model building failure 등의 에러가 뜨면서 실패함.
• 원인: Gradle 설정의 자바 버전이 내 컴퓨터에 없거나, 다운로드 설정이 안 되어 있음.
• 해결: 위 3단계의 'Gradle JVM' 설정이 프로젝트 버전(Java 17)과 일치하는지 다시 확인하고 변경한다.

상황 2: The project is already registered 및 Gradle 창이 비어있음

• 증상: 우측에 코끼리 아이콘(Reload)을 눌렀는데 "Nothing to show"라고 뜨거나, 프로젝트가 이미 등록되었다는 에러 팝업이 뜸.
• 원인: IntelliJ의 내부 캐시가 꼬여서 프로젝트 인식을 제대로 못 하는 상태.
• 해결: 캐시를 비우고 재시작한다.
  1. 상단 메뉴 File > Invalidate Caches... 클릭
  2. 옵션 선택(기본값) 후 [Invalidate and Restart] 클릭
  3. 재시작 후 인덱싱이 끝날 때까지 기다리면 Gradle 탭이 정상적으로 복구된다.

5단계: 빌드 확인 및 실행

모든 설정이 완료되었다면:

1. IntelliJ 우측 상단의 코끼리 아이콘(Load Gradle Changes)을 누른다.
2. 하단 Build Output에 초록색 체크 표시(UP-TO-DATE)가 뜨는지 확인한다.
3. 상단의 ▶ 실행 버튼을 눌러 스프링 부트 애플리케이션을 시작한다.

이렇게 하면 기본 세팅이 완료된다. 

정상적으로 빌드 된 화면