VSCode Java 개발 완벽 설정 가이드: 초보자 스텝 바이 스텝

Visual Studio Code로 자바를 배우거나 개발하려는 사람이 점점 늘어나고 있다. IntelliJ나 Eclipse 같은 무거운 IDE 대신 가볍고 빠른 에디터를 선호하는 추세 때문이다. VSCode는 확장 프로그램(Extension)만 제대로 깔면 전문적인 자바 개발이 가능하다. 이 글은 처음 시작하는 사람 입장에서 단계별로 설명한다.

1단계: JDK 설치 전에 확인할 것

자바 개발을 하려면 JDK(Java Development Kit)가 필수다. JDK는 자바 프로그램을 컴파일하고 실행하는 데 필요한 도구 모음이다. 단순히 자바 프로그램을 실행하기만 하는 JRE(Java Runtime Environment)와는 다르다.

현재 컴퓨터에 자바가 설치되어 있는지 확인해보자. 윈도우의 경우 명령 프롬프트(cmd)를 열고 다음을 입력하면 된다:

java -version

만약 명령어를 인식하지 못하거나 버전이 나타나지 않으면 설치가 필요하다. 기존에 자바 8이 깔려 있다면 11 이상 버전으로 업그레이드할 것을 권장한다. Extension Pack for Java가 자바 1.8 이상을 지원하지만, 실무에서는 보통 자바 11 이상을 쓰기 때문이다.

2단계: JDK 설치하기

가장 간단한 방법은 마이크로소프트에서 제공하는 'Coding Pack for Java'를 사용하는 것이다. 이것을 깔면 VSCode와 JDK, 확장 프로그램들이 자동으로 설정된다. 하지만 이미 VSCode가 깔려 있다면 수동으로 진행해도 된다.

공식 자바 배포판을 원한다면 Oracle JDK, Eclipse Temurin, Amazon Corretto 등 여러 선택지가 있다. Oracle의 공식 페이지에서 최신 LTS(Long Term Support) 버전을 받는 게 일반적이다. 2026년 현재 Java 21이 최신 LTS 버전이다.

다운로드 받은 설치 파일을 실행하면 기본값으로 C:\Program Files\Java 폴더에 설치된다. 설치 후 cmd에서 java -version 명령어로 정상 설치를 확인하자. 버전 정보가 나타나면 성공이다.

환경 변수 설정이 필요할 수도 있다. 특히 수동으로 JDK를 설치했다면 JAVA_HOME 변수를 설정해야 한다. 윈도우에서는 제어판 > 시스템 및 보안 > 시스템 > 고급 시스템 설정 > 환경 변수로 들어간다. 또는 윈도우 버튼을 누르고 '환경 변수'를 검색하면 된다.

"새로 만들기" 버튼으로 시스템 변수를 추가한다. 변수명은 JAVA_HOME이고, 변수값은 자바가 설치된 경로다. 예를 들어 C:\Program Files\Java\jdk-21이 입력된다. PATH 변수에도 %JAVA_HOME%\bin을 추가해두면 어느 위치에서든 자바 명령어를 실행할 수 있다. 설정 후 cmd를 재시작하고 다시 java -version을 실행해 적용 여부를 확인한다.

VS CODE 다운로

3단계: VSCode 설치

아직 VSCode를 깔지 않았다면 code.visualstudio.com에서 받으면 된다. 윈도우, 맥, 리눅스 모두 지원한다. 다운로드 후 기본값으로 설치하면 된다. 설치 중에 "Add to PATH" 옵션이 나타나면 체크하자. 터미널에서 code 명령어로 바로 VSCode를 열 수 있게 된다.

4단계: Extension Pack for Java 설치

VSCode를 시작한 후 왼쪽 사이드바에서 Extensions(확장) 아이콘을 클릭한다. Ctrl+Shift+X 단축키로도 열린다. 검색창에 'Extension Pack for Java'를 입력하고 마이크로소프트에서 만든 공식 팩을 찾는다. Install 버튼을 누르면 자동으로 필요한 확장들이 설치된다.

이 팩에는 몇 가지 중요한 확장이 포함되어 있다. Language Support for Java(Red Hat)는 코드 분석과 자동 완성(IntelliSense)을 담당한다. Debugger for Java는 프로그램을 실행하면서 문제를 찾을 때 필요하다. Maven for Java와 Visual Studio Code Extension for Java Test Runner도 함께 깔린다. 모두 자동으로 처리되므로 일일이 선택할 필요 없다.

설치가 끝나면 VSCode를 재시작하는 게 좋다. 특히 JDK를 새로 설치했다면 반드시 재시작해야 설치한 자바 버전이 제대로 인식된다. 우측 하단에 설치 진행 상황이 표시될 것이다. 설치 중일 때는 코딩을 시작하지 말자.

5단계: 첫 번째 프로젝트 만들기

이제 자바 프로젝트를 만들 차례다. Ctrl+Shift+P를 눌러 명령 팔레트를 연다. 이것은 VSCode의 거의 모든 기능에 접근하는 방법이다. 'Java: Create Java Project'를 입력해 검색한다. 엔터를 누르면 프로젝트 템플릿을 선택하는 화면이 나타난다.

초보자라면 'No build tools'를 선택하자. Maven이나 Gradle은 나중에 배워도 된다. 그 다음 프로젝트를 저장할 폴더를 선택하고, 마지막으로 프로젝트 이름을 입력한다. 프로젝트명은 대문자로 시작해야 한다. 예를 들어 'MyFirstApp'이 적절하다.

VSCode가 새로운 창을 열고 프로젝트를 생성한다. 좌측에 탐색기가 열려 있고, src 폴더 안에 App.java 파일이 있을 것이다. 이 파일을 열면 기본적으로 "Hello, World!"를 출력하는 코드가 있다.

6단계: 프로그램 실행하기

App.java 파일을 열면 상단에 작은 메뉴가 나타난다. 'Run'과 'Debug' 두 가지 옵션이 보인다. Run을 클릭하거나 F5 키를 누르면 프로그램이 실행된다. 하단의 Terminal 창에 "Hello, World!" 메시지가 출력되면 성공이다.

처음에는 터미널 창이 보이지 않을 수도 있다. 이 경우 Ctrl+J를 눌러 하단 패널을 열거나, 메뉴에서 View > Terminal을 선택한다. OUTPUT 탭 또는 TERMINAL 탭에서 결과를 볼 수 있다.

간단하게 코드를 수정해 보자. App.java의 main 메서드 안 System.out.println 부분을 바꾼 후 다시 Run을 누르면 바뀐 메시지가 출력된다. 이렇게 간단하게 수정과 실행 과정을 반복할 수 있다.

7단계: 코드 자동 완성 활용하기

자바를 배울 때 IntelliSense가 얼마나 편한지 금방 알게 된다. Ctrl+Space를 누르면 현재 입력할 수 있는 명령어나 메서드들이 자동으로 나타난다. 예를 들어 System.out을 입력한 후 Ctrl+Space를 누르면 println, printf 등의 메서드가 목록으로 표시된다.

점(.) 문자를 입력할 때도 자동으로 제안이 나타난다. 이를 '트리거 문자'라고 부른다. 마우스나 화살표 키로 원하는 항목을 선택하고 탭이나 엔터를 누르면 자동으로 입력된다. CamelCase 필터링도 지원하므로, 메서드명의 대문자만 입력해도 관련 메서드를 빠르게 찾을 수 있다. 예를 들어 'cra'라고 입력하면 'createApplication' 같은 메서드가 추천된다.

변수나 메서드 위에 마우스를 올리면 설명이 팝업으로 나타난다. 이것도 IntelliSense의 기능이다. 자바 API를 공부할 때 매우 유용하다.

VS CODE 기능들

8단계: 디버깅의 기초

프로그램이 예상과 다르게 작동할 때 Debugger for Java를 사용하면 문제를 찾기 쉽다. 코드 줄번호 왼쪽을 클릭하면 빨간 원(중단점)이 생긴다. 이 지점에서 프로그램 실행이 멈춘다. 그 다음 Run 옆에 Debug를 선택하거나 F5를 눌러 디버그 모드로 시작한다.

프로그램이 중단점에 도달하면 일시 중지된다. 하단의 디버그 창에서 변수 값들을 확인할 수 있다. Step Over(F10)는 다음 줄로 한 칸씩 진행하고, Step Into(F11)는 함수 내부로 들어간다. 이렇게 한 줄씩 진행하면서 변수 값이 어떻게 바뀌는지 관찰할 수 있다.

특히 루프나 조건문에서 의도와 다르게 작동할 때 디버거가 유용하다. 변수 값을 직접 수정할 수도 있어서, 여러 경우를 빠르게 테스트하고 싶을 때 도움된다.

9단계: 작은 프로젝트 구조 이해하기

프로젝트를 조금 더 크게 만들어 보자. App.java 외에 다른 클래스 파일들을 추가할 수 있다. src 폴더를 우클릭하고 'New File'을 선택한 후, 예를 들어 'Calculator.java'라고 만든다. 같은 src 폴더에 있는 클래스들은 패키지 선언 없이도 서로 접근할 수 있다.

간단한 계산 기능을 하는 Calculator 클래스를 만들고, App 클래스에서 그것을 사용해 보자. App.java의 main 메서드에서 Calculator 객체를 생성하고 메서드를 호출한다. 이렇게 여러 클래스가 협력하는 구조를 경험하면 객체지향 프로그래밍의 기초를 이해하기 쉬워진다.

10단계: 패키지 구조 만들기

프로그램이 커지면 패키지(package)를 이용해 클래스들을 분류한다. src 폴더 안에 새로운 폴더를 만들고, 그 안에 자바 파일을 넣으면 된다. 예를 들어 src/util 폴더를 만들고, 그 안에 클래스를 넣으면 자동으로 패키지 선언이 추가된다.

패키지명은 폴더 경로와 일치해야 한다. src/util 폴더의 클래스는 'package util;'이라고 선언된다. 다른 패키지의 클래스를 사용할 때는 import 문을 넣어야 한다. VSCode는 이것도 자동으로 제안하고 처리해 준다. 클래스명을 입력하고 Ctrl+Space를 누르면, 자동으로 import 문이 추가된다.

자주 마주치는 문제들

"Java language server is not started"라는 메시지가 나타난다: 이것은 보통 확장이 아직 로드 중이라는 뜻이다. 혹은 폴더를 제대로 열지 않은 경우도 있다. 파일만 열었을 때보다 폴더 전체를 Open Folder로 열어야 한다. 몇 초 기다린 후 다시 시도하면 보통 해결된다. VSCode를 재시작해야 할 때도 있다.

코드를 수정했는데 실행 결과가 바뀌지 않는다: 이전 버전의 컴파일된 파일(클래스 파일)이 실행되고 있을 수 있다. 명령 팔레트에서 'Java: Clean the Java language server workspace'를 검색해 실행하면, 캐시된 파일들이 삭제되고 새로 컴파일된다.

터미널에서 입력을 받으려고 할 때 작동하지 않는다: 기본 설정에서 VSCode의 디버그 콘솔은 입력을 지원하지 않는다. 통합 터미널(Integrated Terminal)을 사용해야 한다. settings.json에서 'java.debug.settings.console' 항목을 찾아 'integratedTerminal'로 설정한다.

특정 자바 버전을 사용하고 싶다: 프로젝트마다 다른 자바 버전을 사용할 수 있다. 명령 팔레트에서 'Java: Configure Runtime for Projects'를 입력하면, 프로젝트 목록과 사용 가능한 자바 버전들이 나타난다. 여러 버전의 JDK를 설치했다면 여기서 선택해 바꿀 수 있다.

Maven과 Gradle을 생각할 때

간단한 자바 학습 목적이라면 'No build tools' 프로젝트로 충분하다. 하지만 라이브러리를 많이 사용하거나 프로젝트가 복잡해지면 Maven이나 Gradle 같은 빌드 도구가 필수가 된다.

VSCode에서 명령 팔레트를 열고 'Java: Create Java Project'를 선택할 때, Maven(Maven create from archetype) 또는 Gradle을 선택할 수 있다. 이렇게 만든 프로젝트는 자동으로 pom.xml(Maven) 또는 build.gradle(Gradle) 파일이 생긴다. 이 파일들에서 라이브러리 의존성을 관리한다.

한편 Gradle Extension을 따로 설치하면 VSCode 좌측에 Gradle 아이콘이 나타나서, 그래픽 인터페이스로 빌드 작업들을 관리할 수 있다.

스프링 부트를 향해

자바 기초를 익힌 후 스프링 부트 개발로 넘어갈 계획이라면, 지금부터 준비할 수 있다. Spring Boot Extension Pack을 설치하면 된다. 이것도 Extension 탭에서 검색해 설치한다.

스프링 부트 프로젝트는 명령 팔레트에서 'Spring Initializr: Create a Maven Project' 또는 'Spring Initializr: Create a Gradle Project'를 선택해 만든다. 자동으로 스프링 부트 프로젝트 템플릿이 생성되고, 기본 구조가 갖춰진다. 데이터베이스 연동, 보안, 테스트 등 여러 스프링 기능을 선택해 추가할 수 있다.

유용한 단축키들

자바 개발을 할 때 자주 쓰는 단축키들을 정리했다. Ctrl+Space는 자동 완성이고, F5는 실행 또는 디버그다. Ctrl+/ 또는 Ctrl+K, Ctrl+C는 선택한 부분을 주석 처리한다. F2를 누르면 변수나 메서드 이름을 한 번에 바꿀 수 있다. 이것을 '이름 바꾸기(Rename)'라고 부른다.

Ctrl+H는 파일 전체에서 특정 텍스트를 찾아 바꾼다. Ctrl+B는 메서드나 클래스 정의 부분으로 이동한다(Go to Definition). Ctrl+P는 파일명으로 파일을 빠르게 열 수 있다. 자주 쓰는 단축키를 몇 개 익혀두면 개발 속도가 눈에 띄게 빨라진다.

VSCode로 자바 개발을 시작하는 것은 생각보다 간단하다. 적절한 확장 몇 개와 JDK만 있으면 충분히 전문적인 환경을 만들 수 있다. 무겁고 느린 IDE를 피하면서도 강력한 기능들을 누릴 수 있다는 게 가장 큰 장점이다.

처음에는 기본 프로젝트로 언어 문법과 객체지향 개념을 익히고, 나중에 필요에 따라 Maven, Gradle, 스프링 부트 같은 도구들을 추가하면 된다. 모든 것을 한 번에 배우려고 하지 말고, 단계별로 조금씩 늘려가는 게 학습 곡선을 완만하게 만든다. 디버거도 능숙하게 다루면 버그를 찾는 데 걸리는 시간이 크게 줄어든다.

자바 개발 커뮤니티는 꽤 활동적이어서, 막히는 부분이 생기면 온라인에서 쉽게 답을 찾을 수 있다. Stack Overflow나 각종 기술 블로그들에 VSCode 자바 설정 관련 질문과 답변이 많이 있다. 처음 세팅이 까다로워 보이지만, 한 번 제대로 해두면 이후로는 편하게 개발할 수 있다.