VS Code + Spring Boot + Gradle에서 외부 JAR 파일 적용하는 방법

 

VS Code에서 Spring Boot와 Gradle 프로젝트에 외부 JAR 파일을 추가하는 방법을 정리했습니다. libs 폴더에 JAR 파일을 추가한 후 Gradle 빌드, Java Language Server 캐시 초기화, VS Code 인식 오류 해결 방법까지 자세히 설명합니다.

Spring Boot 프로젝트를 개발하다 보면 Maven Central이나 Gradle Repository에 등록되어 있지 않은 라이브러리를 직접 받아 프로젝트에 추가해야 하는 경우가 있습니다.

대표적으로 회사 내부 라이브러리나 외부 업체에서 제공하는 SDK, 또는 직접 빌드한 라이브러리를 사용할 때가 많습니다.

IntelliJ에서는 대부분 자동으로 인식되는 경우가 많지만, VS Code에서는 libs 폴더에 JAR 파일만 복사한다고 바로 인식되지 않는 경우가 자주 발생합니다.

특히 Java Language Server의 캐시가 남아있는 경우에는 Gradle 빌드는 정상적으로 완료되더라도 VS Code에서는 다음과 같은 문제가 발생할 수 있습니다.

• import 오류 발생
• Cannot resolve symbol
• 패키지를 찾을 수 없음
• 클래스 자동완성 미동작
• Gradle 빌드는 성공하지만 VS Code에서는 빨간 줄 표시

이 글에서는 이러한 문제를 해결하는 방법을 순서대로 정리했습니다.

---

왜 이런 문제가 발생할까?

VS Code에서 Java 프로젝트는 Java Language Server(JDT Language Server)가 프로젝트 정보를 별도로 관리합니다.

Gradle에서 라이브러리가 변경되어도 Java Language Server가 기존 캐시를 그대로 사용하면 새로운 라이브러리를 인식하지 못하는 경우가 있습니다.

즉,

Gradle
        ↓
빌드는 성공

VS Code(Java Language Server)
        ↓
기존 캐시 사용
        ↓
라이브러리 인식 실패

이러한 이유 때문에 Gradle 빌드만으로는 해결되지 않는 경우가 있습니다.

---

외부 JAR 파일 추가

먼저 프로젝트에 필요한 라이브러리를 /libs 폴더에 추가합니다.

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

project
 ├── build.gradle
 ├── settings.gradle
 ├── libs
 │    ├── 8bytes-core.jar
 │    └── 8bytes-common.jar
 └── src

Gradle에서는 일반적으로 다음과 같이 libs 디렉터리를 참조하도록 설정합니다.

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

이 설정이 되어 있어야 libs 폴더의 모든 JAR 파일을 자동으로 읽어옵니다.

---

1. Gradle 빌드 수행

먼저 프로젝트 루트에서 아래 명령어를 실행합니다.

./gradlew clean build --offline -x test

옵션 설명

옵션설명

clean	기존 빌드 삭제
build	프로젝트 전체 빌드
--offline	인터넷 저장소 조회 없이 로컬 캐시 사용
-x test	테스트 제외

이미 필요한 라이브러리가 모두 다운로드되어 있다면 --offline 옵션을 사용하면 빌드 속도를 조금 더 줄일 수 있습니다.

---

2. VS Code Java 캐시 삭제

Gradle 빌드가 완료되었다고 해서 VS Code가 바로 새로운 라이브러리를 인식하는 것은 아닙니다.

Java Language Server의 캐시를 삭제해야 합니다.

순서는 다음과 같습니다.

① Command Palette 실행

Ctrl + Shift + P

② 아래 명령 실행

Java: Clean Java Language Server Workspace

③ 다음 버튼 선택

Restart and Delete

이 작업을 수행하면 Java Language Server가 사용하는 프로젝트 캐시가 삭제되고 VS Code가 자동으로 다시 시작됩니다.

---

3. Gradle 클래스 다시 생성

VS Code가 다시 실행되면 아래 명령어를 실행합니다.

./gradlew classes --offline

이 명령은 소스 코드를 다시 컴파일하면서 Java Language Server가 새로운 Gradle 정보를 다시 읽도록 도와줍니다.

---

정상적으로 적용되었는지 확인하는 방법

다음 사항을 확인해 보세요.

• import 오류가 사라진다.
• 빨간 줄이 없어졌다.
• 외부 라이브러리 클래스 자동완성이 된다.
• Gradle Tasks 실행이 정상이다.
• Build Success가 출력된다.

---

그래도 인식되지 않는다면

다음 사항도 함께 확인해 보는 것이 좋습니다.

build.gradle 확인

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

fileTree 설정이 빠져 있으면 Gradle이 라이브러리를 읽지 못합니다.

---

Gradle 새로고침

VS Code 좌측 Gradle 탭에서

Refresh Gradle Project

를 실행하면 라이브러리 정보를 다시 불러옵니다.

---

JDK 버전 확인

외부 라이브러리가 Java 17로 컴파일되었는데 프로젝트는 Java 11을 사용한다면 클래스 로딩 오류가 발생할 수 있습니다.

다음 명령으로 현재 Java 버전을 확인합니다.

java -version

---

Gradle 캐시 문제

간혹 Gradle 캐시 자체가 꼬이는 경우도 있습니다.

이 경우에는 다음 명령으로 다시 다운로드합니다.

./gradlew clean build --refresh-dependencies

단, --offline 옵션을 사용할 경우에는 실행되지 않습니다.

---

실무에서 자주 사용하는 적용 순서

실제로 외부 라이브러리가 변경될 때마다 아래 순서로 진행하면 대부분 문제가 해결됩니다.

1. libs 폴더에 jar 복사

↓

2. clean build

↓

3. Java Language Server Workspace 삭제

↓

4. Restart and Delete

↓

5. gradlew classes 실행

↓

6. 정상 인식 확인

회사 프로젝트에서도 외부 SDK나 내부 공통 라이브러리를 배포받아 사용하는 경우 이 방법으로 대부분 해결할 수 있습니다.

---

FAQ

Q. build는 성공하는데 VS Code에서만 빨간 줄이 생깁니다.

대부분 Java Language Server 캐시 문제입니다.

Java: Clean Java Language Server Workspace를 실행한 후 Restart and Delete를 선택하면 해결되는 경우가 많습니다.

---

Q. IntelliJ에서는 정상인데 VS Code만 오류가 발생합니다.

IntelliJ와 VS Code는 프로젝트를 관리하는 방식이 다릅니다.

VS Code는 Java Language Server가 별도의 캐시를 사용하기 때문에 캐시 초기화가 필요할 수 있습니다.

---

Q. libs 폴더만 만들면 자동으로 인식되나요?

아닙니다.

build.gradle에 다음 설정이 반드시 있어야 합니다.

implementation fileTree(dir: 'libs', include: ['*.jar'])

---

Q. --offline 옵션은 언제 사용하나요?

이미 필요한 라이브러리가 모두 다운로드되어 있는 환경이라면 인터넷 저장소에 접근하지 않고 로컬 캐시만 사용하여 빌드할 수 있습니다.

CI/CD 환경이나 사내망에서도 자주 사용하는 옵션입니다.

---

마무리

VS Code에서 Spring Boot와 Gradle 프로젝트에 외부 JAR 파일을 추가한 후 라이브러리가 인식되지 않는다면 대부분 Java Language Server 캐시가 원인입니다.

단순히 libs 폴더에 JAR 파일을 복사하는 것만으로는 충분하지 않으며, Gradle 빌드 → Java Language Server 캐시 삭제 → Gradle classes 실행 순서로 진행하면 대부분의 문제가 해결됩니다.

외부 SDK나 사내 공통 라이브러리를 사용하는 프로젝트에서는 이 절차를 알아두면 개발 환경을 빠르게 복구할 수 있으며, VS Code를 사용하는 개발자라면 한 번쯤은 겪게 되는 문제를 손쉽게 해결할 수 있습니다.