Skip to main content

VS Code 프로젝트 환경 완전 초기화 및 재건축 가이드

등록일: 2026. 4. 9.

1. 개요​

  • 지속적인 환경 변수 충돌 및 VS Code 자바 확장팩 캐시 꼬임 해결을 위한 가이드임.
  • 땜질식 처방이 아닌 물리적 삭제 및 Gradle 주도의 선행 빌드를 통해 무결한 환경을 확보함.

2. 1단계: 물리적 박멸 (Cleanup)​

2.1 VS Code 및 설정 삭제​

  • VS Code 언인스톨 수행함.
  • 아래 경로의 설정/캐시 폴더를 수동으로 영구 삭제함.
    • %AppData%\Code (사용자 설정 및 캐시)
    • %UserProfile%\.vscode (확장 프로그램 데이터)
    • %LocalAppData%\Programs\Microsoft VS Code (설치 잔해)

2.2 빌드 및 패키지 캐시 삭제​

  • 아래 경로의 Gradle 및 Maven 라이브러리 캐시를 삭제함.
    • %UserProfile%\.gradle (프로젝트 의존성 및 설정 캐시)
    • %UserProfile%\.m2\repository (메이븐 라이브러리 저장소)
  • 윈도우 임시 폴더 정화함.
    • %Temp% 내 모든 파일 삭제 (사용 중인 파일 제외)

2.3 프로젝트 잔해 제거​

  • 기존 nexus 프로젝트 폴더를 삭제하여 이전 컴파일 결과물(.class, bin, build)을 완전 박멸함.

3. 2단계: 기초 환경 조성 (Foundations)​

3.1 JDK 배치​

  • JDK 21 및 JDK 25를 설치형(.exe) 대신 압축형(.zip)으로 준비하여 특정 경로에 관리함. (예: C:\dev\bin\jdk\)
  • 윈도우 시스템 환경 변수 설정함.
    • JAVA_HOME: C:\dev\bin\jdk\jdk-21.x.x (프로젝트 런타임 기준)
    • Path: %JAVA_HOME%\bin 추가함.

3.2 VS Code 재설치 및 필수 확장​

  • VS Code 최신 버전 설치함.
  • 아래 필수 확장 프로그램만 우선 설치함.
    • Extension Pack for Java (Microsoft)
    • Spring Boot Extension Pack (VMware)
    • Lombok (Gabriel BB)

4. 3단계: VS Code 전역 설정 (settings.json)​

  • Ctrl + Shift + P -> Open User Settings (JSON)에 아래 설정 강제 주입함.
  • 특히 -parameters 관련 설정은 런타임 에러 방지를 위해 필수임.
{
    "java.jdt.ls.java.home": "C:\\dev\\bin\\jdk\\jdk-25.x.x",
    "java.configuration.runtimes": [
        {
            "name": "JavaSE-21",
            "path": "C:\\dev\\bin\\jdk\\jdk-21.x.x",
            "default": true
        }
    ],
    "java.import.gradle.java.home": "C:\\dev\\bin\\jdk\\jdk-21.x.x",
    "java.javac.generateMetadata": true,
    "java.compiler.javac.exportParameterFormatting": true,
    "java.debug.settings.forceBuildBeforeLaunch": true,
    "java.import.gradle.wrapper.enabled": true,
    "java.autobuild.enabled": true
}

5. 4단계: 터미널 주도 선행 빌드 (Reconstruction)​

  • 중요: VS Code를 켜기 전에 터미널에서 Gradle이 주도권을 잡아야 함.

  1. 프로젝트 클론:

    cd c:/dev/workspace
    git clone [https://github.com/sleepzzzzz/nexus.git](https://github.com/sleepzzzzz/nexus.git)
    cd nexus

  2. Gradle 클린 빌드:

    ./gradlew clean build -x test
    • -parameters 플래그가 포함된 클래스 파일이 build/ 폴더에 생성됨을 보장함.
    • BUILD SUCCESSFUL 확인 전까지 절대 IDE 실행 금지함.

6. 5단계: IDE 동기화 및 검증 (Verification)​

  1. VS Code 실행: code .
  2. 프로젝트 구성 업데이트: Ctrl + Shift + P -> Java: Update Project Configuration 실행함.
  3. 캐시 정화: Ctrl + Shift + P -> Java: Clean Java Language Server Workspace 실행 후 재시작함.
  4. 디버그 실행: 스프링 부트 대시보드를 통해 런타임 파라미터 에러 발생 여부 최종 확인함.

주의사항:

  • ./gradlew bootRun은 잘 되는데 디버그 모드에서만 에러가 난다면 VS Code 설정(exportParameterFormatting)이 누락된 것이니 재점검 요망함.
  • 컨트롤러 메서드에서 @RequestParam 이름 추론 실패 시 어노테이션에 이름을 명시(@RequestParam("name"))하는 것이 가장 확실한 우회책임.