VSCode로 코드를 작성하는 사람은 많지만, 막상 VSCode 디버깅은 어렵게 느끼는 경우가 많습니다. 콘솔에 print나 console.log만 계속 찍다 보면 문제 원인을 찾는 데 시간이 오래 걸리고, 조건이 조금만 복잡해져도 어디서 값이 꼬였는지 놓치기 쉽습니다. 특히 초보자는 브레이크포인트를 어디에 찍어야 하는지, launch.json은 왜 필요한지, Node와 Python은 무엇이 다른지부터 헷갈리기 쉽죠.
결론부터 말하면, VSCode 디버깅은 “코드를 한 줄씩 멈춰 보면서 값의 흐름을 추적하는 습관”만 익히면 생각보다 훨씬 쉽습니다. 이 글에서는 가장 많이 쓰는 브레이크포인트, 변수 확인, Step Over/Into/Out의 차이, 그리고 launch.json으로 Node 디버깅과 Python 디버깅을 시작하는 방법까지 한 번에 정리합니다. 처음 쓰는 분도 10분 안에 따라 할 수 있도록 최대한 실전형으로 설명해볼게요.
VSCode 디버깅, 왜 꼭 배워야 할까?
처음에는 로그 출력만으로도 어느 정도 문제를 찾을 수 있습니다. 하지만 함수가 여러 번 호출되거나, 비동기 로직이 섞이거나, 조건문이 중첩되기 시작하면 로그만으로는 한계가 금방 옵니다. 이때 VSCode 디버깅을 쓰면 코드가 실제로 어떤 순서로 실행되는지, 변수 값이 언제 바뀌는지, 내가 생각한 흐름과 실제 흐름이 어디서 갈라지는지를 눈으로 확인할 수 있습니다.
- 변수 값이 예상과 다르게 바뀌는 순간을 바로 찾을 수 있음
- 함수 호출 순서를 한 줄씩 추적할 수 있음
- 조건문이 왜 특정 분기로 들어가는지 확인 가능
- Node 디버깅, Python 디버깅을 같은 인터페이스로 익힐 수 있음
launch.json으로 반복 실행 환경을 저장할 수 있음
즉, 디버깅은 단순히 “오류 고치기 기술”이 아니라, 코드 이해 속도를 올리는 도구입니다. 특히 협업 프로젝트에서는 남이 작성한 로직을 이해할 때도 디버거가 큰 힘을 발휘합니다.
가장 먼저 익혀야 할 4가지: 브레이크포인트, 변수창, 콜 스택, 실행 버튼
1) 브레이크포인트: 디버깅의 시작점
브레이크포인트는 “여기서 잠깐 멈춰라”라고 표시하는 지점입니다. VSCode 왼쪽 줄 번호 옆을 클릭하면 빨간 점이 생기는데, 이게 가장 기본적인 브레이크포인트입니다. 프로그램을 디버그 모드로 실행하면 해당 줄에서 멈추고, 그 상태에서 변수 값과 실행 흐름을 확인할 수 있습니다.
2) Variables: 지금 이 순간의 값 확인
코드가 멈춘 상태에서 Variables 패널을 보면 현재 스코프 안의 값들이 표시됩니다. 초보자가 가장 많이 감탄하는 부분이 바로 여기입니다. 콘솔을 여러 번 찍지 않아도 현재 변수 상태를 바로 확인할 수 있기 때문입니다. 객체 내부 구조도 펼쳐 볼 수 있어 API 응답이나 설정값 확인에 특히 유용합니다.
3) Call Stack: 어디서 여기까지 왔는지 추적
콜 스택은 현재 실행 중인 함수가 어떤 순서로 호출되어 여기까지 왔는지를 보여줍니다. “내가 이 함수 직접 호출한 적 없는데 왜 실행되지?” 같은 순간에 매우 유용합니다. 특히 이벤트 핸들러, 헬퍼 함수, 유틸 함수가 많아질수록 콜 스택 이해가 중요해집니다.
4) Step Over / Step Into / Step Out 차이
| 기능 | 언제 쓰면 좋은가 | 설명 |
|---|---|---|
| Step Over | 현재 줄만 넘기고 싶을 때 | 함수 내부로 들어가지 않고 다음 줄로 이동 |
| Step Into | 함수 안 흐름까지 보고 싶을 때 | 호출한 함수 내부로 진입 |
| Step Out | 현재 함수는 대충 파악했고 빠져나가고 싶을 때 | 현재 함수 실행을 마치고 바깥 호출 위치로 복귀 |
처음에는 Step Over만 잘 써도 충분합니다. 익숙해지면 특정 함수 내부가 의심될 때만 Step Into를 활용하세요. 이것만으로도 브레이크포인트 활용 효율이 훨씬 좋아집니다.
launch.json은 왜 필요한가?
많은 분들이 처음에는 브레이크포인트만 찍고 실행하다가, 어느 순간 launch.json이 왜 필요한지 궁금해집니다. 쉽게 말하면 launch.json은 “디버깅 실행 설정 저장 파일”입니다. 어떤 파일을 어떤 런타임으로 실행할지, 작업 디렉터리는 어디인지, 환경변수는 무엇인지 등을 저장해두는 역할을 합니다.
한 번 설정해두면 매번 터미널에서 긴 명령어를 입력할 필요가 없습니다. 프로젝트마다 디버그 구성을 따로 둘 수 있어서, 같은 VSCode 안에서 Node 디버깅과 Python 디버깅을 구분해 관리하기도 편합니다.
- 사이드바에서 실행 및 디버그(▶ 벌레 아이콘) 열기
- “create a launch.json file” 선택
- 실행 환경(Node.js 또는 Python) 선택
- 생성된 설정 파일을 프로젝트에 맞게 수정
Node 디버깅 10분 입문: 가장 쉬운 설정 예시
먼저 Node 디버깅부터 시작해보겠습니다. 파일 하나를 직접 실행하는 가장 단순한 예시 기준으로 보면, 아래처럼 launch.json을 구성하면 됩니다.
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Node: 현재 파일 실행",
"program": "${file}",
"skipFiles": ["<node_internals>/**"]
}
]
}
이 설정의 핵심은 "program": "${file}"입니다. 지금 열려 있는 파일을 기준으로 실행한다는 뜻이기 때문에, 간단한 테스트 파일이나 학습용 예제에서 빠르게 쓰기 좋습니다. 브레이크포인트를 찍고 F5를 누르면 바로 실행됩니다.
Node 디버깅 예제 코드
function calculateTotal(price, quantity) {
const total = price * quantity;
return total;
}
const userType = "member";
const discount = userType === "member" ? 0.9 : 1;
const finalPrice = calculateTotal(10000, 2) * discount;
console.log(finalPrice);
이 코드에서 discount 줄이나 calculateTotal 함수 내부에 브레이크포인트를 찍어보세요. 그러면 회원 할인 로직이 실제로 어떻게 계산되는지 한 줄씩 확인할 수 있습니다. 디버깅 초보자에게 이 정도 예제가 가장 이해가 빠릅니다.
Python 디버깅 10분 입문: 인터프리터만 맞으면 생각보다 쉽다
Python 디버깅도 흐름은 거의 같습니다. 다만 Node보다 더 자주 막히는 부분이 “현재 선택된 파이썬 인터프리터가 맞는가?”입니다. 가상환경을 쓰는 프로젝트라면 VSCode 오른쪽 아래 또는 Command Palette에서 인터프리터를 먼저 정확하게 선택해야 합니다.
기본적인 launch.json 예시는 아래처럼 잡으면 됩니다.
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: 현재 파일 디버그",
"type": "python",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal"
}
]
}Python 디버깅 예제 코드
def calculate_total(price, quantity, user_type):
subtotal = price * quantity
discount = 0.9 if user_type == "member" else 1
return subtotal * discount
result = calculate_total(10000, 2, "member")
print(result)이 예제 역시 함수 내부와 반환 직전에 브레이크포인트를 걸어보면 좋습니다. Python 디버깅에서 중요한 포인트는 변수창에서 숫자, 문자열, 리스트, 딕셔너리 값을 천천히 확인하는 습관입니다. 특히 API 응답을 받아 처리하는 로직에서는 변수창만 잘 봐도 원인 파악이 매우 빨라집니다.
초보자가 가장 자주 막히는 오류 7가지
| 막히는 지점 | 원인 | 해결 방법 |
|---|---|---|
| 브레이크포인트가 회색으로 뜸 | 실행 파일/환경이 맞지 않음 | 올바른 launch 설정과 실행 파일 확인 |
| F5 눌러도 디버깅이 시작되지 않음 | 런타임 또는 확장 미설치 | Node/Python 확장 및 런타임 설치 확인 |
| Python이 다른 버전으로 실행됨 | 인터프리터 선택 오류 | 현재 워크스페이스 인터프리터 재선택 |
| 터미널에서만 실행되고 디버거가 안 붙음 | Run과 Debug를 혼동 | 실행 및 디버그 메뉴에서 F5로 시작 |
| 환경변수가 안 먹음 | launch.json 설정 누락 | env, cwd, args 항목 점검 |
| 함수 안으로 너무 자주 들어감 | Step Into 남용 | 처음엔 Step Over 위주로 사용 |
| 내 코드보다 내부 라이브러리로 자꾸 들어감 | skip 설정 부족 | Node는 skipFiles, Python은 justMyCode 옵션 확인 |
실전에서 바로 쓰는 디버깅 루틴
디버깅을 잘하는 사람은 복잡한 기능을 한 번에 전부 보지 않습니다. 먼저 문제가 “입력값 문제인지”, “조건 분기 문제인지”, “함수 호출 순서 문제인지”를 좁힌 뒤, 필요한 위치에만 브레이크포인트를 배치합니다. 이 루틴만 익혀도 디버깅 시간이 크게 줄어듭니다.
- 오류가 시작된 것으로 의심되는 위치 1~2곳만 고른다
- 입력값 확인용 브레이크포인트를 먼저 건다
- 변수창에서 실제 값이 기대값과 같은지 본다
- 이상 없으면 Step Over로 분기 지점까지 이동한다
- 함수 내부가 의심될 때만 Step Into를 사용한다
- 원인을 찾았으면 launch.json에 실행 구성을 저장해 재현 가능하게 만든다
이 방식은 VSCode 디버깅뿐 아니라 다른 IDE로 옮겨가도 그대로 통합니다. 핵심은 도구보다 사고방식입니다. “한 줄씩 멈추고, 값과 흐름을 확인한다”는 원칙이 가장 중요합니다.
VSCode 디버깅 전 체크리스트
- VSCode 관련 확장이 제대로 설치되어 있는가
- Node.js 또는 Python 런타임이 실제로 설치되어 있는가
- 프로젝트 루트 폴더를 올바르게 열었는가
launch.json이 현재 프로젝트 기준으로 작성되었는가- Python이라면 인터프리터/가상환경이 맞는가
- 터미널 PATH 문제는 없는가
- 브레이크포인트가 실제 실행되는 코드 줄에 걸려 있는가
마무리: 처음 배울수록 디버깅이 큰 차이를 만든다
처음부터 완벽하게 launch.json을 다 이해할 필요는 없습니다. 가장 먼저 할 일은 간단한 파일 하나를 열고, 브레이크포인트를 찍고, F5로 실행해보고, 변수 값을 보는 것입니다. 그 다음에 Step Over와 Step Into 차이를 익히고, 마지막으로 launch.json을 저장형 설정으로 이해하면 됩니다.
결국 VSCode 디버깅의 핵심은 복잡한 기능이 아니라 “코드를 눈으로 따라가는 힘”입니다. 로그만 보던 단계에서 벗어나면 Node 디버깅도, Python 디버깅도 훨씬 덜 막히게 됩니다. 지금 바로 가장 짧은 예제 파일 하나로 먼저 시작해보세요.
댓글