[Backend] Java 8 레거시 환경에서 Spring Boot 2.3 버전으로 다운그레이드 하는 방법 ( 흔한 오류 해결법 포함 )

Spring Boot 3 → 2.3.1 + Java 8 다운그레이드 가이드

Java 1.8 환경에서 안정적으로 동작하도록 프로젝트를 정리하는 단계별 안내와 실제 오류 해결 방법을 모았습니다.

Spring Boot 2.3.1 Java 1.8 Gradle 6.9.4 DSL Groovy

목차

• 왜 다운그레이드가 필요한가
• 최종 목표 스택
• 1) Gradle Wrapper 버전 변경
• 2) settings.gradle 수정
• 3) build.gradle 설정
• 4) IntelliJ 설정 정렬
• 5) jakarta → javax 변환
• 6) 실행 & 포트 문제
• 7) 실제 오류 모음 (원인/해결)
• 8) 문제 지속 시 초기화 3종 세트
• 9) 동작 확인용 컨트롤러
• 10) 결론 체크리스트
• 11) 부록: Windows JDK 8 설치 & Gradle JVM 고정

왜 다운그레이드가 필요한가

⚠️

Spring Boot 3.x는 Java 17+가 필수입니다. Java 8 환경에서는 실행/빌드가 막힙니다. 또한 패키지가 javax.* → jakarta.*로 변경되어 2.x와 호환되지 않습니다.

이 가이드는 Spring Boot 3로 시작한 프로젝트를 2.3.1 + Java 8 조합으로 안전하게 돌리기 위한 실전 절차입니다.

✅ 최종 목표 스택

• Spring Boot: 2.3.1
• Java: 1.8
• Gradle: 6.9.4 (Boot 2.3 권장)
• Gradle DSL: Groovy (build.gradle / settings.gradle)

1) Gradle Wrapper 버전 변경 (가장 중요)

문제 — Spring Boot 2.3 Gradle 플러그인은 **Gradle 6.x (6.3+)**만 호환됩니다. Gradle 7/8로는 빌드 실패·불안정이 발생할 수 있습니다:

Execution failed for task ':compileJava'.
Failed to run Gradle Worker Daemon
Process 'Gradle Worker Daemon ...' finished with non-zero exit value 1

해결 — Wrapper를 6.9.4로 내립니다. gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-6.9.4-bin.zip

적용 확인:

.\gradlew.bat --version
# → Gradle 6.9.4, JVM 1.8.x 가 보여야 정상

2) settings.gradle 수정 (오타 방지 필수)

⛔

아래처럼 쓰면 무조건 에러: Cannot set the value of read-only property 'name'

// ❌ 틀린 예
name = 'demo'  // Cannot set the value of read-only property 'name'

// ✅ 맞는 예
rootProject.name = 'demo'

주의: 루트에 settings.gradle 하나만 두세요. settings.gradle.kts가 같이 있으면 혼선이 생깁니다. (우리는 Groovy DSL 사용)

3) build.gradle (Groovy DSL) 설정

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.3.1.RELEASE'
    id 'io.spring.dependency-management' version '1.0.9.RELEASE'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
description = 'demo'

// ✅ Java 8 고정 (둘 중 하나 방식만 사용)
sourceCompatibility = '1.8'
targetCompatibility = '1.8'
// 또는
// sourceCompatibility = JavaVersion.VERSION_1_8
// targetCompatibility = JavaVersion.VERSION_1_8

repositories { mavenCentral() }

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-validation' // Boot 2.3부터 web starter에 미포함
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') { useJUnitPlatform() }

⚠️

• toolchain 블록은 삭제하세요. (java { toolchain { languageVersion = 17 } })
• JavaVersion._8 같은 표기는 오타 → '1.8' 또는 JavaVersion.VERSION_1_8만 사용.

4) IntelliJ 설정 정렬

• Project SDK: 1.8
• Language level: 8
• Gradle JVM: 1.8
• 캐시 의심 시: File → Invalidate Caches / Restart

💡

플러그인 경고 “종속성 'Spring' … 설치되어 있지 않습니다.”는 IDE 메시지입니다. Ultimate: Spring / Spring Boot 플러그인 설치 Community: 원래 없음 — Gradle로 실행은 정상이니 경고만 무시

5) (필요 시) jakarta.* → javax.* 변환

Spring Boot 3 코드에서 가져온 import가 있다면 2.7에서 컴파일 에러가 납니다. 전부 javax.*로 바꾸세요.

# 검색 (Windows PowerShell)
Get-ChildItem -Path src -Recurse -Include *.java | Select-String "jakarta"

6) 실행 & 포트(8080) 문제 처리

6-1. 기본 실행

.\gradlew.bat clean bootRun

Tomcat started on port(s): 8080 (http) with context path ''
Started DemoApplication...

6-2. 8080 포트 충돌 시

🛑

Web server failed to start. Port 8080 was already in use.

A) 점유 프로세스 찾아 종료

# PID 확인
netstat -ano | findstr :8080
# 또는
Get-NetTCPConnection -LocalPort 8080 | Select-Object State,LocalAddress,LocalPort,OwningProcess

# 어떤 프로세스인지 조회 (예: PID=12345)
Get-Process -Id 12345

# 강제 종료
taskkill /PID 12345 /F
# 또는
Stop-Process -Id 12345 -Force

주의: <PID>는 자리표시자입니다. 실제 숫자로 바꾸세요.

B) 포트를 바꿔서 실행

# 일회성
.\gradlew.bat bootRun --args="--server.port=8081"

# 항상 8081로 — src/main/resources/application.properties
server.port=8081

7) 실제로 겪은 오류 → 원인 → 해결

8) 문제 지속 시 “초기화 3종 세트”

.\gradlew.bat --stop
rmdir /s /q .gradle
rmdir /s /q build
.\gradlew.bat --version     # Gradle 6.9.4, JVM 1.8 확인
.\gradlew.bat clean bootRun

9) 동작 확인용 컨트롤러

// src/main/java/com/example/demo/HelloController.java
package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() { return "ok"; }
}

http://localhost:8080/hello  # → ok

10) 결론 체크리스트

• gradle-wrapper.properties → 6.9.4
• settings.gradle → rootProject.name = 'demo' (오직 1줄, .kts 없음)
• build.gradle → Java 8 고정, toolchain 삭제
• IntelliJ Project SDK / Gradle JVM = 1.8
• 필요 시 jakarta.* → javax.* 교체
• 8080 충돌 시 PID 종료 또는 포트 변경

✅

이 절차대로면 Java 1.8 환경에서도 Spring Boot 2.3.1 프로젝트를 안정적으로 실행할 수 있습니다.

11) 부록: Windows JDK 8 설치 & Gradle JVM 고정

11-1. JDK 8 설치 (Temurin 권장)

아래 링크에서 Windows x64 MSI로 설치하세요. 설치 후 경로 예: C:\Program Files\Java\jdk1.8.0_xxx

Adoptium Temurin 8 다운로드

11-2. 설치 후 한 번만 JDK 8로 강제 실행

cd "C:\Users\비컴솔루션\OneDrive\Desktop\demo"

# 실행 중 Gradle 데몬 중지
.\gradlew --stop 2>$null

# ⚠️ 아래 경로를 실제 JDK 8 경로로 바꾸세요
$JDK = "C:\Program Files\Java\jdk1.8.0_***"

# Gradle이 어떤 JVM으로 도는지 확인 (JVM: 1.8.x가 보여야 정상)
.\gradlew -Dorg.gradle.java.home="$JDK" --version

# 빌드 & 실행
.\gradlew -Dorg.gradle.java.home="$JDK" clean compileJava
.\gradlew -Dorg.gradle.java.home="$JDK" bootRun

11-3. 영구 설정 (둘 중 1개만)

A) 프로젝트에 고정 (권장) — 루트의 gradle.properties에 추가:

org.gradle.java.home=C:\Program Files\Java\jdk1.8.0_***

B) 시스템 환경변수:

setx JAVA_HOME "C:\Program Files\Java\jdk1.8.0_***"
# 새 PowerShell 열고 확인
java -version
.\gradlew -v   # JVM: 1.8.x 출력 확인

11-4. IntelliJ 맞추기

• Project SDK = 1.8, Language level = 8
• Settings → Build Tools → Gradle → Gradle JVM = 1.8

💡

대안: JDK 11 사용 — JDK 11로 Gradle을 실행해도 됩니다(단, 21은 비권장). 이때 build.gradle에 타깃을 명시:

sourceCompatibility = '1.8'
targetCompatibility = '1.8'
tasks.withType(JavaCompile) {
    options.release = 8
}

11-5. Git 줄바꿈 경고(LF→CRLF) 처리

빌드에는 영향 없지만 원하면 아래처럼 정리하세요.

옵션 1(권장) — 자동 변환:

git config core.autocrlf true

옵션 2 — .gitattributes로 고정:

*           text=auto
*.sh        text eol=lf
*.gradle    text eol=lf
*.java      text eol=lf
*.yml       text eol=lf
*.bat       text eol=crlf