VS Code 개발 환경 최적화 세팅

이 글에서 다루는 내용

VS Code를 설치한 직후부터 실무에서 바로 쓸 수 있는 상태로 만드는 전 과정을 정리합니다. 필수 확장, WSL·Remote SSH 연동, settings.json 핵심 항목, 자주 쓰는 단축키, 디버거 구성까지 한 번에 다룹니다. 이 글은 Windows+WSL 사용자를 기준으로 하지만 macOS/Linux 네이티브에서도 대부분 동일하게 적용됩니다.

VS Code의 진짜 강점은 "에디터"가 아니라 "원격 어디서나 동일한 편집 환경"을 제공한다는 데 있습니다. 로컬, WSL 안, 원격 서버, Docker 컨테이너에서 같은 UI로 동일한 단축키와 확장을 쓸 수 있습니다. 처음에 이 구조를 한 번 잡아두면, 새 프로젝트마다 환경을 다시 만드는 부담이 크게 줄어듭니다.

---

1. 설치와 기본 확장

1-1. 설치

code.visualstudio.com에서 OS에 맞는 버전을 받아 설치합니다. Windows 사용자는 설치 시 "PATH에 추가", "마우스 오른쪽 메뉴에 열기" 옵션을 꼭 켜두는 것이 편합니다. 설치 후 셸에서 code .로 현재 폴더를 바로 열 수 있어야 이후 작업 흐름이 매끄러워집니다.

1-2. VS Code의 구조 이해

VS Code는 UI 레이어와 Extension Host(확장이 실제 동작하는 프로세스)가 분리돼 있습니다. WSL이나 Remote SSH로 접속하면 UI는 로컬에서, Extension Host는 원격에서 따로 돕니다. 그래서 같은 확장이라도 "로컬에 설치"와 "원격에 설치"를 별도로 해야 동작합니다. 이 구조를 알고 있으면 "확장이 안 보인다"는 상황에서 당황하지 않습니다.

VS Code 구조 — UI는 로컬, Extension Host는 어디든 내 PC (UI) 에디터 화면 단축키·테마 파일 트리·터미널 UI JSON-RPC Extension Host (작업 위치에 따라) Local 로컬 폴더 WSL Ubuntu 안 Remote SSH 서버 안 확장은 Extension Host가 있는 곳에 설치해야 동작합니다 (Local/WSL/SSH 각각 별도).

1-3. 필수 확장 5개

확장	용도
Python	Python 인터프리터, 디버거, 가상환경 자동 인식
Pylance	Python 정적 분석, 자동완성
WSL	WSL 안의 폴더를 VS Code로 직접 편집
Remote - SSH	원격 서버를 로컬처럼 편집
GitLens	Git blame, history 시각화

1-4. 취향에 따라 추가

• Docker: 컨테이너/이미지 관리, Dockerfile 자동완성
• Markdown All in One: 블로그 작성, TOC 자동 생성
• ESLint / Prettier: JS/TS 포매팅
• Error Lens: 오류를 인라인으로 표시 (한눈에 잡기 좋음)
• Indent Rainbow: 들여쓰기 시각화, Python처럼 들여쓰기로 블록을 표현하는 언어에 특히 유용

---

2. WSL 연동

2-1. 첫 연결

WSL 확장을 설치한 뒤 WSL 터미널에서 아래를 실행합니다.

cd ~/dev/my-project
code .

몇 초 후 Windows 쪽 VS Code가 열리고, 하단 왼쪽 상태바에 WSL: Ubuntu 표시가 뜨면 연결 성공입니다. 이 상태에서 통합 터미널을 열면 자동으로 WSL 셸이 됩니다.

2-2. 파일 성능

WSL 안에서 ~/dev/… 경로를 편집할 때와 /mnt/c/… 경로를 편집할 때 속도 차이가 큽니다. 가능한 한 Linux 홈 디렉터리 안에서만 작업하세요. 빌드·테스트 도구가 수천 개의 파일을 동시에 스캔하는 상황에서 체감 차이가 가장 큽니다.

⚠️ Windows 탐색기에서 \\wsl$\Ubuntu\home\user\dev로도 접근 가능하지만, VS Code에서 code .로 여는 흐름이 가장 안정적입니다.

2-3. 클립보드와 폰트

WSL 모드에서도 Ctrl+C/Ctrl+V는 Windows 클립보드와 자연스럽게 연결됩니다. 한글 폰트가 깨져 보일 경우 "editor.fontFamily"와 "terminal.integrated.fontFamily"에 한글 지원 모노스페이스(D2Coding, 나눔고딕코딩 등)를 추가하면 됩니다.

---

3. settings.json 최소 구성

명령 팔레트(Ctrl+Shift+P) → "Preferences: Open User Settings (JSON)"를 열고 아래를 베이스로 둡니다. 한 번 잡아두면 어느 머신에서든 같은 환경을 유지할 수 있습니다.

{
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "editor.rulers": [80, 120],
  "editor.minimap.enabled": false,
  "editor.bracketPairColorization.enabled": true,

  "files.autoSave": "onFocusChange",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,

  "terminal.integrated.defaultProfile.windows": "Ubuntu (WSL)",
  "terminal.integrated.fontSize": 13,

  "workbench.colorTheme": "Default Dark Modern",
  "workbench.editor.enablePreview": false,

  "python.analysis.typeCheckingMode": "basic",
  "python.terminal.activateEnvironment": true
}

핵심 포인트는 저장 시 자동 포매팅과 미리보기 비활성화(탭이 더블클릭 없이도 고정)입니다. 둘 다 체감 생산성이 크게 오르는 옵션입니다. 또한 Settings Sync를 켜두면 깃허브·MS 계정을 통해 다른 PC와 동일한 설정·확장이 자동 동기화돼, 노트북을 바꿔도 손에 익은 환경이 그대로 따라옵니다.

---

4. Remote - SSH로 원격 서버 작업

4-1. 설정

F1 → Remote-SSH: Open SSH Configuration File을 선택하고 ~/.ssh/config에 호스트를 등록합니다.

Host my-server
    HostName 203.0.113.10
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519

명령 팔레트에서 Remote-SSH: Connect to Host…를 고르면 새 창에서 원격 환경이 열립니다. 처음 연결할 때만 비밀번호 또는 키 인증을 묻고, 이후로는 즉시 접속됩니다.

4-2. 주의점

• 초기 연결 시 원격에 .vscode-server가 설치됩니다. 용량이 수백 MB이므로 프리 티어 인스턴스에서는 여유 공간을 확인하세요.
• 네트워크 끊김 시 자동 재연결을 위해 ~/.ssh/config에 ServerAliveInterval 60을 추가하면 안정적입니다.
• 여러 서버를 자주 쓴다면 ProxyJump로 점프 서버 경유 접속도 같은 파일에 정의할 수 있습니다.

---

5. 단축키 치트시트

단축키	동작
Ctrl+P	파일 빠른 열기
Ctrl+Shift+P	명령 팔레트
Ctrl+`	통합 터미널 토글
Ctrl+B	사이드바 토글
Ctrl+/	주석 토글
Alt+↑/↓	현재 줄 이동
Shift+Alt+↓	현재 줄 복제
F2	심볼 이름 일괄 변경
F12	정의로 이동
Ctrl+Shift+F	전체 검색

💡 자주 쓰는 단축키는 벽에 붙여놓는 것 이상의 효과가 없습니다. 대신 매일 2개씩 고정해 1주일이면 몸에 익습니다. 특히 Ctrl+P(파일 열기)와 F2(이름 변경)는 마우스 사용량을 가장 크게 줄여주는 두 단축키입니다.

---

6. Python 디버거 구성 예시

.vscode/launch.json 파일에 아래를 넣으면 F5 한 번으로 디버깅이 됩니다. FastAPI·Django·Flask 모두 모듈만 바꿔서 적용할 수 있습니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "FastAPI: uvicorn",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": ["app.main:app", "--reload"],
      "jinja": true
    }
  ]
}

디버거를 띄우면 변수 보기·콜 스택·중단점 한 번에 잡힌 상태가 됩니다. print 디버깅에 비해 처음에는 시간이 더 걸리지만, 익숙해지면 복잡한 버그는 디버거 쪽이 훨씬 빠릅니다.

---

트러블슈팅

문제 1: WSL로 열었는데 Python 인터프리터가 잡히지 않음

Ctrl+Shift+P → "Python: Select Interpreter"에서 .venv/bin/python을 수동 선택합니다. 이후 python.terminal.activateEnvironment가 true라면 터미널에서도 자동으로 활성화됩니다.

문제 2: 한글 폰트가 깨짐

"editor.fontFamily": "D2Coding, Consolas, monospace"처럼 한글 지원 폰트를 첫 번째로 지정합니다. D2Coding, 나눔고딕코딩이 무난합니다.

문제 3: Remote-SSH에서 EACCES: permission denied

서버 홈 디렉터리 권한이 700이어야 .vscode-server가 설치됩니다.

chmod 700 ~

문제 4: 확장이 동작하지 않음

대부분 "Local"과 "WSL"에 각각 설치해야 합니다. 확장 목록 위쪽의 "Install in WSL: Ubuntu" 버튼을 확인합니다. Remote SSH도 마찬가지로 원격에 별도 설치가 필요합니다.

---

마무리

VS Code는 확장이 수천 개지만, 실제로 필요한 것은 손에 꼽힙니다. 이 글의 설정 파일과 확장 5종, Remote-SSH만 몸에 익혀도 대부분의 프로젝트에서 충분합니다. 익숙해진 뒤에는 작업 영역(workspace) 파일로 프로젝트별 설정을 따로 두는 패턴까지 자연스럽게 확장할 수 있습니다. 다음 편에서는 Git과 결합한 실전 워크플로를 다룹니다.

• 공식 문서: https://code.visualstudio.com/docs

관련 글

이전 글 · WSL2 설치와 Ubuntu 초기 세팅 가이드
다음 글 · Git 초보 탈출 — 실무에서 쓰는 명령어 정리

함께 읽으면 좋은 글

• Python 가상환경(venv) 완벽 정리
• Python 가상환경 Anaconda 완벽 정리