VS Code C++ 설정 | IntelliSense·빌드·디버깅

Q: 선행으로 읽으면 좋은 글은?

각 글 하단의 이전 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q: 더 깊이 공부하려면?

cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

2026년 2월 17일 · 25분 읽기 · 수정 2026년 3월 12일 초급 실습

이 글의 핵심

VS Code C++ 설정에 대한 실전 가이드입니다. IntelliSense·빌드·디버깅 등을 예제와 함께 상세히 설명합니다.

[C++ 실전 가이드 #3] VS Code C++ 개발 환경 설정

이 글을 읽으면 VS Code에서 IntelliSense, 빌드 작업, 디버깅을 설정하고 C++ 개발을 바로 시작할 수 있습니다.

”빌드는 되는데 VS Code에서 빨간 밑줄이 잔뜩 나와요”

VS Code로 C++을 처음 쓸 때 가장 흔한 문제입니다. 터미널에서는 g++ main.cpp -o main이 잘 되는데, 에디터에서는 <iostream>, <vector> 같은 표준 라이브러리에 빨간 밑줄이 쫙 그어지고, 자동 완성도 제대로 동작하지 않습니다. 원인은 VS Code C++ 확장이 “어느 컴파일러를 쓰고, 어디서 헤더를 찾을지” 모르기 때문입니다. 이 글에서는 이 문제를 해결하고, 빌드·디버깅까지 한 번에 설정하는 방법을 단계별로 설명합니다.

VS Code는 가볍고 강력한 코드 편집기로, C++ 개발에도 매우 적합합니다. 쉽게 말해 “메모장보다 훨씬 똑똑하고, Visual Studio보다 가벼운 중간 단계”라고 보면 됩니다. IntelliSense(코드 자동 완성·함수 시그니처 표시·에러 밑줄 등 편집 시 도움을 주는 기능) 설정, 빌드 자동화, 디버깅 설정까지 모든 과정을 다룹니다.

추가 문제 시나리오

시나리오 1: 팀원이 새 PC에서 VS Code 설정
팀원이 새로 합류했는데, 같은 코드베이스를 열었을 때 빨간 밑줄이 잔뜩 나오고 빌드가 안 됩니다. compilerPath가 각자 PC의 설치 경로에 따라 달라지기 때문입니다. .vscode 설정을 Git에 커밋하고, OS별 구성(Windows/Linux/Mac)을 함께 제공하면 해결됩니다.

시나리오 2: CMake 프로젝트를 VS Code로 열었는데 IntelliSense가 안 됨
CMakeLists.txt 기반 프로젝트를 열었을 때 #include 경로를 인식하지 못합니다. CMake 확장이 compile_commands.json을 생성하면 자동으로 해결되지만, 확장 미설치나 CMAKE_EXPORT_COMPILE_COMMANDS 미설정 시 수동으로 c_cpp_properties.json을 맞춰야 합니다.

시나리오 3: Windows에서 WSL로 Linux C++ 빌드하려면
Windows에서 WSL(Windows Subsystem for Linux) 내부의 g++로 빌드하고 싶을 때, VS Code의 “Remote - WSL” 확장으로 WSL 폴더를 열고, 해당 환경에서 g++/gdb를 사용하도록 설정하면 됩니다. compilerPath는 WSL 내부 경로(예: /usr/bin/g++)를 사용합니다.

시나리오 4: 디버깅 시 “Could not find the task” 오류
F5로 디버깅을 시작할 때마다 “preLaunchTask ‘C++ Build’ not found”가 뜹니다. tasks.json의 label과 launch.json의 preLaunchTask 문자열이 정확히 일치해야 합니다. 대소문자, 공백이 하나라도 다르면 실패합니다.

시나리오 5: macOS에서 LLDB 오류
F5를 누르면 “Unable to find debugger” 또는 LLDB 관련 오류가 발생합니다. Xcode Command Line Tools가 설치되지 않았거나, launch.json에서 MIMode가 gdb로 되어 있어서 발생합니다. macOS는 기본 lldb를 사용해야 합니다.

컴파일러(#2)와 빌드 도구(CMake 입문(#4))가 준비되어 있어야 IntelliSense와 빌드 작업이 제대로 동작하므로, 순서대로 진행했다면 이제 편집기만 맞춰 주면 됩니다.

VS Code C++ 환경 전체 흐름

flowchart TB
    subgraph editor["VS Code 에디터"]
        A[소스 코드 편집]
        B[IntelliSense]
    end
    subgraph config["설정 파일 (.vscode/)"]
        C[c_cpp_properties.json]
        D[tasks.json]
        E[launch.json]
    end
    subgraph build["빌드 & 실행"]
        F[g++/clang++]
        G[실행 파일]
        H[GDB/LLDB]
    end

    C -->|컴파일러 경로, 헤더 경로| B
    B -->|자동 완성, 에러 표시| A
    D -->|빌드 명령 정의| F
    F -->|컴파일| G
    E -->|디버그 설정| H
    H -->|디버깅| G

1. VS Code 설치

VS Code는 Microsoft가 개발한 무료 오픈소스 코드 편집기입니다. 가볍지만 강력한 확장 기능을 통해 본격적인 IDE로 변신할 수 있습니다.

VS Code 다운로드 및 설치

VS Code 공식 사이트에서 운영체제에 맞는 설치 프로그램을 다운로드합니다.

설치 과정은 매우 간단합니다. 기본 설정으로 진행하면 됩니다.

권장 설정:

“PATH에 추가” 옵션을 체크하면 터미널에서 code 명령으로 프로젝트를 열 수 있습니다.
“파일 연결” 옵션을 체크하면 .cpp 파일을 더블클릭했을 때 VS Code로 열립니다.

C++ 확장 설치

VS Code 자체는 C++을 직접 지원하지 않습니다. C++ 개발을 위해서는 Microsoft의 C++ 확장을 설치해야 합니다.

설치 방법:

VS Code를 실행합니다.
왼쪽 사이드바의 Extensions 아이콘을 클릭하거나 Ctrl+Shift+X (macOS: Cmd+Shift+X)를 누릅니다.
검색창에 “C/C++“를 입력합니다.
Microsoft가 제공하는 “C/C++” 확장을 찾아서 Install 버튼을 클릭합니다.

이 확장은 IntelliSense(자동 완성), 코드 네비게이션, GDB(GNU 디버거—Linux 등에서 사용하는 콘솔 디버거)·LLDB(LLVM 디버거—macOS 기본, Clang 계열)를 이용한 디버깅 기능을 제공합니다.

왜 컴파일러 경로가 중요할까?
VS Code C++ 확장은 실제로 설치된 컴파일러를 참조해서 헤더 경로와 표준 버전을 파악합니다. compilerPath가 잘못되거나 비어 있으면 시스템 헤더(<vector>, <iostream> 등)를 찾지 못해 “빨간 밑줄이 잔뜩 나오는데 빌드는 된다”는 상황이 생깁니다. .vscode/c_cpp_properties.json에서 compilerPath를 터미널에서 사용하는 g++ 또는 clang++ 경로와 동일하게 맞춰 주면 해결됩니다.

2. IntelliSense 설정

c_cpp_properties.json이란?

프로젝트 폴더에 .vscode/c_cpp_properties.json을 만들면, C++ 확장이 어느 컴파일러를 쓰고 어느 경로의 헤더를 참조할지 알 수 있어 자동 완성과 오류 표시가 정확해집니다.

정의를 풀어 쓰면 IntelliSense는 “코드를 입력할 때 자동 완성·함수 시그니처·에러 표시를 해 주는 기능”입니다. compilerPath는 실제로 사용하는 g++/clang++ 경로와 맞추는 것이 좋고, cppStandard는 프로젝트에서 쓰는 C++ 표준(예: C++17, C++20)으로 맞춥니다. includePath의 ${workspaceFolder}/*는 “현재 워크스페이스 아래 모든 경로를 헤더 검색 경로에 포함”한다는 뜻이라, 프로젝트 내 자작 헤더를 쓸 때 편합니다. 처음에는 컴파일러 경로만 맞춰도 빨간 밑줄이 많이 사라지는 걸 확인할 수 있습니다.

c_cpp_properties.json 생성

프로젝트 루트에 .vscode 폴더를 만들고, 그 안에 c_cpp_properties.json을 생성합니다.

Linux 기본 예시:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/g++",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

c_cpp_properties.json 필드 상세 설명:

"name": "Linux": 이 구성의 이름입니다. 여러 OS별 구성을 만들 수 있습니다.
- 예: "Linux", "Windows", "Mac"
- VS Code는 현재 OS에 맞는 구성을 자동으로 선택합니다.
"includePath": 헤더 파일을 검색할 경로 목록입니다.
- "${workspaceFolder}/**": 작업 공간의 모든 하위 디렉토리를 포함합니다.
  - **는 재귀적으로 모든 하위 디렉토리를 의미합니다.
- 프로젝트 내 헤더: #include "myheader.h" 인식
- 추가 경로 예시: "/usr/local/include", "${workspaceFolder}/external/boost"
"defines": []: 전처리기 매크로 정의 목록입니다.
- 예: ["DEBUG=1", "VERSION=2"]
- #ifdef DEBUG 같은 조건부 컴파일을 IntelliSense가 인식하게 합니다.
"compilerPath": "/usr/bin/g++": 사용할 컴파일러의 전체 경로입니다.
- 매우 중요! 이 경로가 틀리면 시스템 헤더를 찾지 못합니다.
- 확인 방법: 터미널에서 which g++ 또는 which clang++
- Windows MinGW: "C:/msys64/mingw64/bin/g++.exe"
- macOS: "/usr/bin/clang++"
"cppStandard": "c++17": 사용할 C++ 표준 버전입니다.
- 옵션: "c++11", "c++14", "c++17", "c++20", "c++23"
- 프로젝트에서 사용하는 표준과 일치시켜야 합니다.
- 예: C++20 기능(std::format)을 쓰는데 c++17로 설정하면 에러 표시됩니다.
"intelliSenseMode": "linux-gcc-x64": IntelliSense 엔진 모드입니다.
- 형식: {os}-{compiler}-{architecture}
- Linux GCC: "linux-gcc-x64"
- Windows GCC: "windows-gcc-x64"
- macOS Clang: "macos-clang-x64"
- Windows MSVC: "windows-msvc-x64"
- 컴파일러 타입과 맞지 않으면 IntelliSense가 오작동할 수 있습니다.

OS별 compilerPath와 intelliSenseMode

Windows (MinGW):

"compilerPath": "C:/msys64/mingw64/bin/g++.exe",
"intelliSenseMode": "windows-gcc-x64"

macOS:

"compilerPath": "/usr/bin/clang++",
"intelliSenseMode": "macos-clang-x64"

여러 OS를 동시에 지원하는 구성 예시:

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": ["${workspaceFolder}/**"],
            "defines": [],
            "compilerPath": "/usr/bin/g++",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        },
        {
            "name": "Mac",
            "includePath": ["${workspaceFolder}/**"],
            "defines": [],
            "compilerPath": "/usr/bin/clang++",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "macos-clang-x64"
        },
        {
            "name": "Win32",
            "includePath": ["${workspaceFolder}/**"],
            "defines": [],
            "compilerPath": "C:/msys64/mingw64/bin/g++.exe",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "windows-gcc-x64"
        }
    ],
    "version": 4
}

3. 빌드 작업 설정

tasks.json이란?

tasks.json은 “빌드” 버튼이나 Ctrl+Shift+B를 눌렀을 때 실행할 셸 명령을 정의합니다. 아래 설정에서는 command가 g++이고, args에 -g(디버그 정보 포함), ${file}(현재 열린 파일), -o 다음에 출력 실행 파일 경로가 옵니다. ${fileDirname}/${fileBasenameNoExtension}은 “현재 파일과 같은 폴더에, 확장자 없이 같은 이름”으로 실행 파일을 만든다는 뜻이라, main.cpp를 열고 빌드하면 main 실행 파일이 같은 폴더에 생깁니다. group.isDefault: true로 두면 “기본 빌드 작업”이 되어 단축키로 바로 실행됩니다.

tasks.json 생성

.vscode/tasks.json 생성:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "C++ Build",
            "type": "shell",
            "command": "g++",
            "args": [
                "-g",
                "-std=c++17",
                "${file}",
                "-o",
                "${fileDirname}/${fileBasenameNoExtension}"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

tasks.json 필드 상세 설명:

"version": "2.0.0": tasks.json 파일 형식 버전입니다. 2.0.0이 현재 표준입니다.
"label": "C++ Build": 이 작업의 이름입니다. 나중에 launch.json에서 이 이름으로 참조합니다.
"type": "shell": 셸 명령을 실행하는 작업입니다.
- 다른 옵션: "process" (셸 없이 직접 실행)
"command": "g++": 실행할 명령어입니다. 경로가 환경변수에 있어야 합니다.
"args": 명령어에 전달할 인자 배열입니다.
- "-g": 디버그 정보를 포함합니다. 이것이 없으면 디버거에서 소스 코드를 볼 수 없습니다.
- "-std=c++17": C++17 표준을 사용합니다. 프로젝트에 맞게 변경하세요.
- "${file}": 현재 편집 중인 파일의 전체 경로입니다.
  - 예: /home/user/project/main.cpp
- "-o": 출력 파일을 지정하는 옵션입니다.
- "${fileDirname}/${fileBasenameNoExtension}": 출력 파일 경로입니다.
  - ${fileDirname}: 현재 파일의 디렉토리 (예: /home/user/project)
  - ${fileBasenameNoExtension}: 확장자 없는 파일 이름 (예: main)
  - 결과: /home/user/project/main
"group": 작업 그룹 설정입니다.
- "kind": "build": 빌드 작업임을 표시합니다.
- "isDefault": true: 이 작업을 기본 빌드 작업으로 설정합니다. Ctrl+Shift+B를 누르면 이 작업이 실행됩니다.

VS Code 변수 목록

변수	설명
`${workspaceFolder}`	작업 공간 루트 디렉토리
`${file}`	현재 파일 전체 경로
`${fileBasename}`	현재 파일 이름 (예: `main.cpp`)
`${fileBasenameNoExtension}`	확장자 없는 파일 이름 (예: `main`)
`${fileDirname}`	현재 파일의 디렉토리

빌드 실행

단축키: Ctrl+Shift+B (macOS: Cmd+Shift+B)
또는 Terminal → Run Build Task

참고: tasks.json의 "${file}"은 현재 열린 파일 하나만 컴파일합니다. 여러 소스 파일(main.cpp + utils.cpp 등)을 함께 빌드하려면 아래 “멀티파일 빌드”처럼 args에 파일 목록을 나열하거나, CMake를 쓰는 편이 관리하기 쉽습니다.

4. 디버깅 설정

launch.json이란?

launch.json은 디버거가 어떤 실행 파일을 어떻게 실행할지 정의합니다. preLaunchTask로 빌드 작업을 연결하면, 디버깅 시작 전에 자동으로 빌드가 실행됩니다.

launch.json 생성

.vscode/launch.json 생성:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "C++ Debug",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}/${fileBasenameNoExtension}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ],
            "preLaunchTask": "C++ Build",
            "miDebuggerPath": "/usr/bin/gdb"
        }
    ]
}

launch.json 필드 상세 설명:

"name": "C++ Debug": 디버그 구성의 이름입니다. 디버그 패널에서 이 이름으로 표시됩니다.
"type": "cppdbg": C/C++ 디버깅 타입입니다. C/C++ 확장이 이 타입을 처리합니다.
"request": "launch": 새로 프로그램을 실행합니다.
- 다른 옵션: "attach" (이미 실행 중인 프로세스에 붙음)
"program": "${fileDirname}/${fileBasenameNoExtension}": 디버깅할 실행 파일 경로입니다.
- tasks.json에서 생성한 실행 파일과 같은 경로여야 합니다.
- 예: main.cpp를 열면 ./main 실행 파일을 디버깅합니다.
"args": []: 프로그램에 전달할 명령줄 인자입니다.
- 예: ["input.txt", "output.txt"]
"stopAtEntry": false: main 함수 첫 줄에서 자동으로 멈출지 여부입니다.
- true: 시작하자마자 멈춤 (단계별 실행 가능)
- false: 브레이크포인트까지 실행
"cwd": "${fileDirname}": 프로그램이 실행될 작업 디렉토리입니다.
- 파일 읽기/쓰기 시 상대 경로의 기준이 됩니다.
"externalConsole": false: VS Code 내장 터미널을 사용합니다.
- true: 외부 터미널 창을 엽니다.
"MIMode": "gdb": 사용할 디버거 종류입니다.
- Linux/Windows(MinGW): "gdb"
- macOS: "lldb"
"preLaunchTask": "C++ Build": 디버깅 전에 실행할 작업입니다.
- tasks.json의 "label"과 일치해야 합니다.
- 디버깅 전에 자동으로 빌드합니다.
"miDebuggerPath": "/usr/bin/gdb": GDB 실행 파일 경로입니다.
- which gdb 명령으로 확인할 수 있습니다.
- Windows: "C:/msys64/mingw64/bin/gdb.exe"
- macOS: "/usr/bin/lldb" (MIMode도 lldb로 변경)

OS별 디버거 설정

Windows (MinGW):

"MIMode": "gdb",
"miDebuggerPath": "C:/msys64/mingw64/bin/gdb.exe"

macOS:

"MIMode": "lldb"

macOS에서는 miDebuggerPath를 생략해도 됩니다. LLDB는 시스템 기본 경로에 있습니다.

디버깅 실행

브레이크포인트 설정 (줄 번호 왼쪽 클릭)
F5 또는 Run → Start Debugging

디버깅 단축키

단축키	동작
`F5`	디버깅 시작/계속
`F10`	Step Over (다음 줄)
`F11`	Step Into (함수 안으로)
`Shift+F11`	Step Out (함수 밖으로)
`Shift+F5`	디버깅 중지

5. 자주 발생하는 문제와 해결법

문제 1: “빌드는 되는데 빨간 밑줄이 나와요”

증상: <iostream>, <vector> 등 표준 라이브러리에 빨간 밑줄. 터미널에서는 g++ 빌드가 정상 동작.

원인: c_cpp_properties.json의 compilerPath가 비어 있거나 잘못됨.

해결법:

# 터미널에서 컴파일러 경로 확인
which g++
# 또는
which clang++

확인한 경로를 c_cpp_properties.json의 compilerPath에 정확히 입력합니다.

"compilerPath": "/usr/bin/g++"

추가 확인: intelliSenseMode가 사용 중인 컴파일러와 맞는지 확인 (GCC → linux-gcc-x64, Clang → macos-clang-x64).

문제 2: “Cannot find source file” 또는 헤더를 찾을 수 없음

증상: #include "myheader.h"에 빨간 밑줄. “file not found” 오류.

원인: includePath에 해당 헤더 경로가 없음.

해결법:

"includePath": [
    "${workspaceFolder}/**",
    "${workspaceFolder}/external/boost",
    "/usr/local/include"
]

외부 라이브러리를 쓰는 경우, 해당 include 경로를 includePath에 추가합니다.

문제 3: “preLaunchTask ‘C++ Build’ not found”

증상: F5로 디버깅 시 “Could not find the task ‘C++ Build’” 오류.

원인: launch.json의 preLaunchTask 값이 tasks.json의 label과 일치하지 않음.

해결법:

tasks.json의 label과 launch.json의 preLaunchTask를 동일하게 맞춥니다.

// tasks.json
"label": "C++ Build"

// launch.json
"preLaunchTask": "C++ Build"

문제 4: macOS에서 “Unable to find debugger” 또는 LLDB 오류

증상: macOS에서 F5 시 디버거를 찾을 수 없다는 오류.

원인: Xcode Command Line Tools 미설치 또는 LLDB 경로 문제.

해결법:

# Xcode Command Line Tools 설치
xcode-select --install

launch.json에서 MIMode를 "lldb"로 설정하고, miDebuggerPath는 생략하거나 /usr/bin/lldb로 지정합니다.

문제 5: Windows에서 “g++ not found” 또는 “gdb not found”

증상: 빌드/디버깅 시 g++ 또는 gdb를 찾을 수 없음.

원인: MinGW/MSYS2가 PATH에 추가되지 않음.

해결법:

MSYS2 설치 후 pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb로 설치
VS Code를 MSYS2 터미널에서 실행하거나, 시스템 환경 변수 PATH에 C:\msys64\mingw64\bin 추가
tasks.json과 launch.json에서 전체 경로 사용:

"command": "C:/msys64/mingw64/bin/g++.exe",
"miDebuggerPath": "C:/msys64/mingw64/bin/gdb.exe"

문제 6: C++20 기능에 빨간 밑줄 (std::format 등)

증상: std::format, std::ranges 등 C++20 기능에 “not found” 또는 에러 표시.

원인: cppStandard가 c++17 이하로 설정됨.

해결법:

c_cpp_properties.json과 tasks.json 모두 C++20으로 맞춥니다.

// c_cpp_properties.json
"cppStandard": "c++20"

// tasks.json args에 추가
"-std=c++20"

문제 7: “undefined reference to” 링크 에러

증상: 컴파일은 되는데 링크 시 undefined reference to '함수명' 오류.

원인: 헤더만 include하고 구현 파일(.cpp)을 빌드에 포함하지 않음. 또는 라이브러리(-l 옵션) 미지정.

해결법:

// tasks.json - 여러 .cpp 파일을 함께 빌드
"args": [
    "-g", "-std=c++17",
    "main.cpp", "utils.cpp", "parser.cpp",
    "-o", "myapp"
]

외부 라이브러리 사용 시:

"args": [
    "-g", "-std=c++17", "${file}",
    "-o", "${fileDirname}/${fileBasenameNoExtension}",
    "-lpthread", "-lm"
]

문제 8: IntelliSense가 느리거나 멈춤

증상: 코드 입력 시 자동 완성이 늦게 뜨거나, 에디터가 잠시 멈춤.

원인: 대형 프로젝트에서 includePath에 **로 전체 폴더를 스캔하거나, 외부 라이브러리 경로가 과도함.

해결법:

includePath를 필요한 경로만 지정 (예: "${workspaceFolder}/src", "${workspaceFolder}/include")
CMake 사용 시 compile_commands.json 활용 (C++ 확장이 자동 인식)
C_Cpp.intelliSenseEngine을 default로 유지 (Tag Parser는 더 느릴 수 있음)

문제 9: 디버깅 시 변수 값이 “optimized out”으로 표시

증상: 브레이크포인트에서 변수 값을 볼 때 “optimized out” 또는 <optimized out> 표시.

원인: -O2, -O3 등 최적화 옵션으로 빌드했기 때문. 최적화 시 변수가 레지스터에만 있거나 제거됨.

해결법:

디버그 빌드 시 -O0 -g 사용:

"args": ["-O0", "-g", "-std=c++17", "${file}", "-o", "..."],

문제 10: Windows에서 한글 경로 문제

증상: 파일 경로에 한글이 있으면 빌드·실행 시 오류.

원인: 일부 빌드 도구가 UTF-8 경로를 제대로 처리하지 못함.

해결법:

가능하면 프로젝트 경로에 영문만 사용
tasks.json에 "options": { "env": { "LANG": "en_US.UTF-8" } } 추가 (일부 환경에서 도움됨)
MSYS2/MinGW 사용 시 chcp 65001로 콘솔 코드페이지를 UTF-8로 설정

6. 실전 예제

프로젝트 구조

myproject/
├── .vscode/
│   ├── c_cpp_properties.json  # IntelliSense 설정
│   ├── tasks.json             # 빌드 태스크
│   └── launch.json            # 디버그 설정
├── main.cpp
├── utils.h
└── utils.cpp

main.cpp

#include <iostream>
#include "utils.h"

int main() {
    int result = add(5, 3);
    std::cout << "5 + 3 = " << result << std::endl;
    return 0;
}

utils.h

#pragma once
int add(int a, int b);

utils.cpp

#include "utils.h"

int add(int a, int b) {
    return a + b;
}

멀티파일 빌드

tasks.json에 추가 태스크:

{
    "label": "C++ Build Multi-File",
    "type": "shell",
    "command": "g++",
    "args": [
        "-g",
        "-std=c++17",
        "main.cpp",
        "utils.cpp",
        "-o",
        "myapp"
    ],
    "group": {
        "kind": "build",
        "isDefault": false
    },
    "options": {
        "cwd": "${workspaceFolder}"
    }
}

주의: 멀티파일 빌드 시 "${file}" 대신 main.cpp, utils.cpp처럼 파일 목록을 명시합니다. cwd를 ${workspaceFolder}로 두어 프로젝트 루트에서 빌드되도록 합니다.

launch.json에서 멀티파일 빌드를 사용하려면:

"program": "${workspaceFolder}/myapp",
"preLaunchTask": "C++ Build Multi-File"

CMake 프로젝트와 연동

프로젝트가 커지면 CMake를 사용하는 편이 좋습니다. CMake 확장을 설치하면 CMakeLists.txt 기반으로 자동으로 tasks.json과 launch.json을 생성할 수 있습니다.

# CMake 확장 설치 후
# Ctrl+Shift+P → "CMake: Configure" 실행
# 빌드: Ctrl+Shift+B
# 디버깅: F5

환경 확인 스크립트

새 PC나 팀원 환경에서 설정이 제대로 되었는지 확인할 때 아래 스크립트를 실행해 보세요.

Linux/macOS:

#!/bin/bash
echo "=== C++ 개발 환경 확인 ==="
echo "g++: $(which g++ 2>/dev/null || echo '미설치')"
echo "clang++: $(which clang++ 2>/dev/null || echo '미설치')"
echo "gdb: $(which gdb 2>/dev/null || echo '미설치')"
echo "lldb: $(which lldb 2>/dev/null || echo '미설치')"
echo ""
echo "g++ 버전:"
g++ --version 2>/dev/null | head -1 || echo "g++ 없음"
echo ""
echo "clang++ 버전:"
clang++ --version 2>/dev/null | head -1 || echo "clang++ 없음"

Windows (PowerShell):

Write-Host "=== C++ 개발 환경 확인 ==="
Write-Host "g++: $(Get-Command g++ -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source)"
Write-Host "gdb: $(Get-Command gdb -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source)"
g++ --version 2>$null

VS Code C++ 관련 추천 확장

확장	용도
C/C++ (Microsoft)	필수. IntelliSense, 디버깅
CMake Tools	CMake 프로젝트 빌드·디버깅
clangd	대안 IntelliSense (선택, c_cpp_properties 대신 compile_commands.json 사용)
CodeLLDB	macOS/Linux에서 LLDB 디버깅 개선
Better C++ Syntax	C++ 문법 하이라이팅 개선

참고: clangd와 Microsoft C++ 확장을 동시에 쓰면 충돌할 수 있습니다. 하나만 사용하세요.

프로젝트별 확장 추천 (.vscode/extensions.json)

팀원이 프로젝트를 열었을 때 필요한 확장을 자동으로 추천받도록 .vscode/extensions.json을 만들 수 있습니다.

{
    "recommendations": [
        "ms-vscode.cpptools",
        "ms-vscode.cmake-tools"
    ],
    "unwantedRecommendations": []
}

완전한 VS Code 설정 예시 (단일 파일)

아래는 .cpp 파일 하나를 빌드·디버깅하는 최소 완전한 설정입니다. 프로젝트 루트에 .vscode 폴더를 만들고, 아래 세 파일을 그대로 복사해 사용할 수 있습니다.

c_cpp_properties.json (Linux 기준):

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "/usr/local/include"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/g++",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

tasks.json (단일 파일 + 멀티파일 빌드):

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "C++ Build",
            "type": "shell",
            "command": "g++",
            "args": [
                "-g",
                "-std=c++17",
                "-Wall",
                "-Wextra",
                "${file}",
                "-o",
                "${fileDirname}/${fileBasenameNoExtension}"
            ],
            "group": { "kind": "build", "isDefault": true },
            "presentation": { "reveal": "silent", "echo": true }
        },
        {
            "label": "C++ Build Release",
            "type": "shell",
            "command": "g++",
            "args": [
                "-O3",
                "-std=c++17",
                "-Wall",
                "-DNDEBUG",
                "${file}",
                "-o",
                "${fileDirname}/${fileBasenameNoExtension}"
            ],
            "group": "build"
        }
    ]
}

launch.json (Linux + macOS):

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "C++ Debug",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}/${fileBasenameNoExtension}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "/usr/bin/gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ],
            "preLaunchTask": "C++ Build"
        },
        {
            "name": "C++ Debug (macOS)",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}/${fileBasenameNoExtension}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "MIMode": "lldb",
            "preLaunchTask": "C++ Build"
        }
    ]
}

Windows (MinGW) 예시:

{
    "configurations": [
        {
            "name": "C++ Debug (Windows)",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}/${fileBasenameNoExtension}.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "MIMode": "gdb",
            "miDebuggerPath": "C:/msys64/mingw64/bin/gdb.exe",
            "preLaunchTask": "C++ Build"
        }
    ]
}

tasks.json Windows용 (command 경로 지정):

{
    "tasks": [
        {
            "label": "C++ Build",
            "type": "shell",
            "command": "C:/msys64/mingw64/bin/g++.exe",
            "args": ["-g", "-std=c++17", "${file}", "-o", "${fileDirname}/${fileBasenameNoExtension}.exe"],
            "group": { "kind": "build", "isDefault": true }
        }
    ]
}

실전 활용 팁

1. 여러 빌드 구성 (Debug/Release)
tasks.json에 Debug·Release 태스크를 나누고, -O0 -g(디버그)와 -O3(릴리스)를 구분해 사용할 수 있습니다.

2. 터미널에서 빌드 출력 숨기기
"presentation": { "reveal": "silent" }를 tasks.json 태스크에 추가하면 빌드 시 터미널 패널이 자동으로 열리지 않습니다.

3. 조건부 컴파일
c_cpp_properties.json의 defines에 ["DEBUG=1"]를 넣으면 #ifdef DEBUG 블록이 IntelliSense에 반영됩니다.

4. 워크스페이스별 설정
.vscode 폴더는 프로젝트 루트에 두면, 해당 폴더를 열었을 때만 설정이 적용됩니다. 팀원과 .vscode를 Git에 커밋해 공유할 수 있습니다.

7. 생산성 향상 팁

필수 단축키

단축키	동작
`Ctrl+Shift+B` / `Cmd+Shift+B`	빌드 실행
`F5`	디버깅 시작
`Ctrl+Shift+P` / `Cmd+Shift+P`	명령 팔레트
`Ctrl+P` / `Cmd+P`	파일 빠른 열기
`Ctrl+Shift+O` / `Cmd+Shift+O`	현재 파일 심볼(함수) 이동
`F12`	정의로 이동
`F2`	심볼 이름 변경 (리팩터링)
`Ctrl+Space` / `Cmd+Space`	IntelliSense 자동 완성 강제

IntelliSense 재시작

compilerPath나 includePath를 수정했는데도 빨간 밑줄이 사라지지 않을 때:

Ctrl+Shift+P / Cmd+Shift+P → “C++: Reset IntelliSense Database” 실행
또는 “Developer: Reload Window”로 VS Code 재시작

멀티커서로 빠른 편집

Ctrl+D / Cmd+D: 같은 단어를 순차적으로 선택
Alt+클릭 / Option+클릭: 여러 위치에 커서 추가
Ctrl+Shift+L / Cmd+Shift+L: 선택한 단어 전체 선택

파일/심볼 검색

Ctrl+P 후 @ 입력: 현재 파일 내 심볼(함수, 클래스) 검색
Ctrl+P 후 # 입력: 워크스페이스 전체 심볼 검색
Ctrl+Shift+F / Cmd+Shift+F: 전체 워크스페이스 텍스트 검색

조건부 브레이크포인트

브레이크포인트를 우클릭 → “Edit Breakpoint” → 조건 입력 (예: i == 5).
반복문에서 특정 반복 시에만 멈출 때 유용합니다.

8. 프로덕션 패턴

.vscode 폴더 Git 관리

권장: .vscode 폴더를 Git에 커밋하여 팀 전체가 동일한 설정을 사용합니다.

# .gitignore에 넣지 말 것 (권장)
# .vscode/

# 개인 설정만 제외할 경우
# .vscode/settings.json  # 개인 선호도

개인 설정 분리: settings.json에 팀 공통 설정과 개인 설정이 섞일 수 있습니다. 팀 공통은 .vscode/settings.json에 두고, 사용자별 설정은 VS Code 사용자 설정(~/.config/Code/User/settings.json)에 둡니다.

팀 온보딩 체크리스트

새 팀원이 VS Code 설정을 완료했는지 확인하는 체크리스트:

# C++ 개발 환경 설정 체크리스트

- [ ] VS Code + C/C++ 확장 설치
- [ ] g++ 또는 clang++ 설치 (which g++ 확인)
- [ ] gdb 또는 lldb 설치 (디버깅용)
- [ ] .vscode 폴더가 프로젝트에 있음
- [ ] Ctrl+Shift+B로 빌드 성공
- [ ] F5로 디버깅 시작 가능
- [ ] IntelliSense 빨간 밑줄 없음

CI/CD 빌드와 연동

VS Code tasks.json의 빌드 명령과 CI/CD 파이프라인을 동일하게 유지하면 “로컬에서는 되는데 CI에서 안 된다”는 문제를 줄일 수 있습니다.

예: GitHub Actions:

# .github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: |
          g++ -std=c++17 -Wall -Wextra -O2 src/main.cpp src/utils.cpp -o myapp

tasks.json의 args와 위 run 명령을 동일하게 맞추면 됩니다.

대형 프로젝트: CMake + compile_commands.json

소스 파일이 많아지면 tasks.json에서 파일을 수동으로 나열하기 어렵습니다. 이때 CMake를 사용하고:

# CMakeLists.txt
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

CMake 확장이 compile_commands.json을 생성하면, C++ 확장이 이를 자동으로 읽어 IntelliSense를 설정합니다. c_cpp_properties.json을 수동으로 관리할 필요가 없어집니다.

문제 해결 흐름도

flowchart TD
    A[빨간 밑줄 / 빌드 오류] --> B{터미널에서 빌드 가능?}
    B -->|예| C[compilerPath 확인]
    B -->|아니오| D[g++/clang++ 설치 확인]
    C --> E[which g++ 결과를 compilerPath에 입력]
    E --> F[IntelliSense 재시작: Ctrl+Shift+P → C++: Reset IntelliSense]
    D --> G[패키지 매니저로 설치]
    G --> H[PATH 환경변수 확인]

9. 설정 체크리스트

VS Code C++ 환경 구축 시 아래 항목을 확인하세요.

설치 및 확장

VS Code 설치 완료
C/C++ 확장 (Microsoft) 설치
터미널에서 g++ 또는 clang++ 실행 가능
터미널에서 gdb 또는 lldb 실행 가능 (디버깅용)

IntelliSense (c_cpp_properties.json)

.vscode/c_cpp_properties.json 생성
compilerPath가 which g++/which clang++ 결과와 일치
intelliSenseMode가 OS·컴파일러에 맞음
cppStandard가 프로젝트 C++ 버전과 일치
includePath에 프로젝트 및 외부 라이브러리 경로 포함

빌드 (tasks.json)

.vscode/tasks.json 생성
label이 launch.json의 preLaunchTask와 일치
-g 옵션 포함 (디버깅용)
-std=c++17 등 표준 옵션 프로젝트에 맞게 설정

디버깅 (launch.json)

.vscode/launch.json 생성
program 경로가 tasks.json 출력과 일치
preLaunchTask가 tasks.json의 label과 일치
MIMode·miDebuggerPath가 OS에 맞음

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

C++ 개발 환경 구축 | “C++ 어디서 시작하죠?” 컴파일러 설치부터 Hello World까지
C++ GDB/LLDB | cout 100개 찍어도 못 찾은 버그, 디버거로 5분 만에 해결
CMake 입문 | 수십 개 파일 컴파일할 때 필요한 빌드 자동화 (CMakeLists.txt 기초)

이 글에서 다루는 키워드 (관련 검색어)

VS Code C++, VSCode C++ 설정, c_cpp_properties.json, tasks.json launch.json, C++ IntelliSense, C++ 디버깅 GDB LLDB, C++ 빌드 자동화 등으로 검색하시면 이 글이 도움이 됩니다.

마무리

핵심 요약

VS Code에서 C++ 개발 환경을 구축하는 방법을 정리하겠습니다:

✅ IntelliSense 설정: .vscode/c_cpp_properties.json 파일로 자동 완성과 코드 네비게이션을 설정합니다. compilerPath를 정확히 맞추는 것이 가장 중요합니다.

✅ 빌드 자동화: .vscode/tasks.json 파일로 빌드 작업을 정의하고, Ctrl+Shift+B로 빠르게 빌드할 수 있습니다.

✅ 디버깅 설정: .vscode/launch.json 파일로 디버거를 구성하고, F5로 디버깅을 시작할 수 있습니다. preLaunchTask로 빌드와 연동하면 편리합니다.

✅ 멀티파일 프로젝트: 여러 소스 파일이 있는 경우, tasks.json의 args 배열에 모든 파일을 나열하거나, CMake를 사용합니다.

VS Code의 장점

가볍고 빠른 실행 속도
강력한 확장 생태계
무료 오픈소스
크로스 플랫폼 지원
Git 통합

프로젝트가 커지면 수동으로 빌드 명령어를 관리하는 것이 어려워집니다. 이때 필요한 것이 CMake입니다.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. Visual Studio Code로 C++ 개발 환경 구축하는 완벽 가이드. c_cpp_properties.json으로 IntelliSense 설정, tasks.json으로 빌드 자동화, launch.json으로 디버깅 설정. 실무에서는 위 본문의 예제와 OS별 설정 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. VS Code C++ 문서와 C++ 확장 GitHub도 활용하면 좋습니다.

Q. Visual Studio와 VS Code 중 뭘 써야 하나요?

A. Visual Studio는 Windows 전용 통합 IDE로, 대규모 프로젝트·MSVC 디버깅에 강합니다. VS Code는 가볍고 크로스 플랫폼이라 Linux/macOS 개발, 원격 개발, 터미널 중심 워크플로우에 적합합니다. 팀 환경이 Windows만 쓰면 Visual Studio, 혼합이면 VS Code를 많이 씁니다.

C++ 컴파일러 비교 | GCC vs Clang vs MSVC, 어떤 걸 써야 할까?
C++ 컴파일러 최적화 | PGO·LTO로
C++ 멀티 컴파일러 전략과 CI/CD 파이프라인 구축 | 실무 가이드
C++ 컴파일러 뭘 쓸까? GCC vs Clang vs MSVC 차이·선택 가이드
C++ GDB 기초 완벽 가이드 | 브레이크포인트·워치포인트

이 글의 핵심

[C++ 실전 가이드 #3] VS Code C++ 개발 환경 설정

”빌드는 되는데 VS Code에서 빨간 밑줄이 잔뜩 나와요”

추가 문제 시나리오

VS Code C++ 환경 전체 흐름

목차

1. VS Code 설치

VS Code 다운로드 및 설치

C++ 확장 설치

2. IntelliSense 설정

c_cpp_properties.json이란?

c_cpp_properties.json 생성

OS별 compilerPath와 intelliSenseMode

3. 빌드 작업 설정

tasks.json이란?

tasks.json 생성

VS Code 변수 목록

빌드 실행

4. 디버깅 설정

launch.json이란?

launch.json 생성

OS별 디버거 설정

디버깅 실행

디버깅 단축키

5. 자주 발생하는 문제와 해결법

문제 1: “빌드는 되는데 빨간 밑줄이 나와요”

문제 2: “Cannot find source file” 또는 헤더를 찾을 수 없음

문제 3: “preLaunchTask ‘C++ Build’ not found”

문제 4: macOS에서 “Unable to find debugger” 또는 LLDB 오류

문제 5: Windows에서 “g++ not found” 또는 “gdb not found”

문제 6: C++20 기능에 빨간 밑줄 (std::format 등)

문제 7: “undefined reference to” 링크 에러

문제 8: IntelliSense가 느리거나 멈춤

문제 9: 디버깅 시 변수 값이 “optimized out”으로 표시

문제 10: Windows에서 한글 경로 문제

6. 실전 예제

프로젝트 구조

main.cpp

utils.h

utils.cpp

멀티파일 빌드

CMake 프로젝트와 연동

환경 확인 스크립트

VS Code C++ 관련 추천 확장

프로젝트별 확장 추천 (.vscode/extensions.json)

완전한 VS Code 설정 예시 (단일 파일)

실전 활용 팁

7. 생산성 향상 팁

필수 단축키

IntelliSense 재시작

멀티커서로 빠른 편집

파일/심볼 검색

조건부 브레이크포인트

8. 프로덕션 패턴

.vscode 폴더 Git 관리

팀 온보딩 체크리스트

CI/CD 빌드와 연동

대형 프로젝트: CMake + compile_commands.json

문제 해결 흐름도

9. 설정 체크리스트

설치 및 확장

IntelliSense (c_cpp_properties.json)

빌드 (tasks.json)

디버깅 (launch.json)

같이 보면 좋은 글 (내부 링크)

이 글에서 다루는 키워드 (관련 검색어)

마무리

핵심 요약

VS Code의 장점

다음 글

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

Q. 선행으로 읽으면 좋은 글은?

Q. 더 깊이 공부하려면?

Q. Visual Studio와 VS Code 중 뭘 써야 하나요?

관련 글