VS Code 원격 개발, SSH와 WSL과 Dev Containers

개발 환경이 내 노트북이 아니라 다른 곳에 있는 경우가 늘었다. 회사 서버, WSL, 도커 컨테이너 같은 곳이다. 그때마다 터미널로 접속해 vim을 쓰거나, 파일을 로컬로 내려받아 고치고 다시 올리는 방식은 번거롭다. VS Code의 원격 개발 기능은 에디터는 내 컴퓨터에서 돌리고 실제 작업은 원격에서 하게 해준다. 이 글은 그 구조가 어떻게 동작하는지와, 세 가지 방식을 언제 골라 쓰는지를 다룬다.

화면만 로컬이고 나머지는 전부 원격에서 돈다

먼저 구조를 이해하는 게 중요하다. 이걸 알아야 왜 어떤 확장은 원격에 다시 깔아야 하는지가 납득된다.

공식 문서의 설명은 이렇다. 확장이 "원격 OS에 VS Code Server를 설치하며, 이 서버는 기존 VS Code 설치와 독립적이다". 그리고 사용자 인터페이스는 내 컴퓨터에서 돌고 명령은 원격에서 실행된다.

이 구조의 결과가 몇 가지 있다. 터미널을 열면 원격 셸이 뜬다. 디버거도 원격에서 돈다. 파일 탐색기에 보이는 것은 원격 파일이다. 소스 코드를 로컬로 내려받을 필요가 없다.

확장은 두 부류로 나뉜다. 테마나 키맵처럼 화면만 건드리는 것은 로컬에서 돌고, 언어 서버나 린터처럼 코드를 읽어야 하는 것은 원격에 설치된다. 확장 목록에서 "Install in SSH: 서버명" 같은 버튼이 뜨는 이유가 그것이다. 문서도 "대부분의 VS Code 확장은 원격 환경에서 수정 없이 동작한다"고 밝히고 있다.

네 가지 방식이 있고 쓰는 상황이 다르다

Remote Development 확장 팩에는 네 개가 들어 있다. 문서의 설명을 그대로 옮기면 이렇다.

Remote - SSH는 "SSH를 사용해 원격 머신/VM의 폴더를 열어 어느 위치에나 접속"한다. 회사 개발 서버나 클라우드 인스턴스에 붙을 때 쓴다. 가장 많이 쓰게 되는 방식이다.

Dev Containers는 "별도의 툴체인이나 컨테이너 기반 애플리케이션을 컨테이너 안에서(또는 마운트해서) 작업"한다. 프로젝트마다 언어 버전이 다를 때, 그 환경을 저장소에 정의해 두고 누구나 같은 환경에서 개발하게 만드는 용도다.

WSL은 "Windows Subsystem for Linux에서 리눅스 기반 개발 경험"을 제공한다. 윈도우를 쓰면서 리눅스에서 빌드해야 하는 경우다.

Remote - Tunnels는 "SSH 설정 없이 보안 터널을 통해 원격 머신에 접속"한다. 방화벽 때문에 SSH 포트를 열 수 없는 환경에서 대안이 된다.

고르는 기준은 단순하다. 접속할 곳이 이미 있고 SSH가 열려 있으면 Remote-SSH, 환경 자체를 코드로 정의하고 싶으면 Dev Containers, 윈도우에서 리눅스 도구가 필요하면 WSL, SSH를 못 쓰면 Tunnels다.

WSL 이 윈도우 사용자에게 주는 실질적 이득

윈도우에서 개발하는 사람에게 WSL 연동은 성능 차이가 크다. 이유는 파일 시스템에 있다.

윈도우 쪽 경로(C:\project)를 WSL에서 접근하면 파일 시스템 경계를 넘나들기 때문에 느리다. npm install처럼 작은 파일을 수만 개 만드는 작업에서 차이가 극명하다. 반대로 리눅스 쪽 경로(~/project)에 프로젝트를 두고 VS Code의 WSL 확장으로 열면, 파일 접근이 전부 리눅스 안에서 일어나므로 빠르다.

WSL 터미널에서 이렇게 열면 된다.

cd ~/project
code .

이러면 VS Code가 WSL 모드로 뜬다. 왼쪽 아래에 WSL: Ubuntu 같은 표시가 보이면 제대로 붙은 것이다. 이 표시는 원격 종류를 가리지 않고 항상 나오므로, 지금 로컬인지 원격인지 헷갈릴 때 여길 보면 된다.

설정이 세 벌로 나뉜다는 점을 기억해야 한다

원격 개발에서 사람들이 가장 많이 헤매는 지점이 설정이다. 앞선 설정 글에서 다룬 우선순위를 다시 보면, 사용자 설정과 워크스페이스 설정 사이에 원격 설정이 끼어 있다.

즉 로컬에서 바꾼 사용자 설정이 원격 창에서 그대로 적용되지 않을 수 있다. 원격 창에서 설정을 열면 Remote 탭이 따로 보이고, 거기 있는 값이 로컬 사용자 설정을 덮어쓴다.

확장도 마찬가지다. 로컬에 깔았다고 원격에서 자동으로 동작하지 않는다. 원격에서 필요한 확장은 원격에 따로 설치된다. 이걸 매번 손으로 하지 않으려면 .vscode/extensions.json에 추천 목록을 넣어두는 것이 좋다. Dev Containers를 쓴다면 devcontainer.json에 확장 목록을 박아둘 수 있어서 더 확실하다.

터미널도 원격 셸이므로, 로컬에 깔린 도구는 없다. git, node, python이 원격에 설치돼 있어야 한다. 로컬에서는 되던 명령이 원격 창에서 "command not found"가 나면 대개 이 경우다.

포트 포워딩이 원격 개발을 쓸 만하게 만든다

원격 서버에서 개발 서버를 띄웠는데 브라우저로 어떻게 보느냐는 질문이 바로 나온다. VS Code는 이걸 자동으로 처리한다.

원격 터미널에서 서버를 실행하면 VS Code가 열린 포트를 감지해 로컬로 연결해 준다. 알림이 뜨고, 브라우저에서 localhost:3000으로 접속하면 원격의 3000번 포트로 이어진다. 방화벽 설정이나 SSH 터널 명령을 따로 칠 필요가 없다.

자동 감지가 안 되는 포트는 패널의 PORTS 탭에서 직접 추가한다. 포트 번호를 넣으면 포워딩이 시작되고, 라벨을 붙여 구분할 수도 있다.

여기서 주의할 점 하나. 포워딩된 포트는 기본적으로 내 컴퓨터에서만 접근된다. 다른 사람에게 보여주려고 공개 범위를 바꾸는 옵션이 있는데, 사내 서버의 개발 중인 화면을 외부에 여는 셈이므로 필요할 때만 켜고 바로 닫는 것이 맞다.

Dev Containers 는 환경 자체를 저장소에 넣는다

Dev Containers를 쓰는 이유는 "내 컴퓨터에서는 되는데" 문제를 구조적으로 없애는 데 있다. 환경 정의를 .devcontainer/devcontainer.json에 두고 커밋한다.

{
  "name": "api-server",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "postCreateCommand": "pip install -r requirements.txt",
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python", "charliermarsh.ruff"],
      "settings": { "python.defaultInterpreterPath": "/usr/local/bin/python" }
    }
  },
  "forwardPorts": [8000]
}

저장소를 클론하고 VS Code로 열면 컨테이너를 만들겠냐고 묻는다. 수락하면 이미지를 받아 컨테이너를 띄우고, 확장을 설치하고, postCreateCommand를 실행한 뒤 그 안에서 개발이 시작된다. 파이썬 버전이나 시스템 패키지를 각자 맞출 필요가 없다.

비용도 있다. 첫 실행에 시간이 걸리고, 도커가 깔려 있어야 하고, 컨테이너가 디스크를 쓴다. 혼자 하는 작은 프로젝트라면 과하다. 사람이 여럿이고 환경 설정 때문에 반나절씩 날리는 팀이라면 그 비용이 금방 회수된다.

원격 개발이 답이 아닌 경우

편리하지만 만능은 아니다. 나는 두 가지 상황에서는 원격을 피한다.

첫째, 네트워크가 불안정할 때다. 원격 개발은 키 입력과 화면 갱신이 네트워크를 타는 구조가 아니라 대부분 로컬에서 처리되지만, 파일 목록·자동완성·저장은 원격과 오간다. 연결이 끊기면 작업 중인 파일을 저장하지 못하는 상황이 생긴다. 기차나 비행기에서는 로컬 작업이 안전하다.

둘째, GUI가 필요한 작업이다. 브라우저를 띄워 확인해야 하는 프런트엔드 작업은 포트 포워딩으로 어느 정도 해결되지만, 설정이 늘어나고 디버깅이 복잡해진다. 로컬에서 돌릴 수 있으면 로컬이 단순하다.

그리고 원격 서버에 VS Code Server가 설치된다는 점도 알고 있어야 한다. 홈 디렉터리에 수백 메가바이트를 쓰고 프로세스가 상주한다. 공용 서버에서 여러 사람이 동시에 붙으면 서버 부담이 된다. 회사 서버라면 팀과 합의하고 쓰는 편이 좋다.

정리하면 이렇다. 환경을 원격에 두어야 할 분명한 이유(빌드 도구, 데이터 접근, 성능)가 있으면 원격이 크게 편하고, 그냥 습관적으로 쓰면 복잡도만 늘어난다.

참고 자료

• Remote Development — Visual Studio Code Docs — 확장 팩 네 종류, VS Code Server 구조, 확장의 로컬/원격 실행 구분
• User and workspace settings — Visual Studio Code Docs — 원격 설정이 끼어드는 우선순위 단계
• Managing Extensions — Visual Studio Code Docs — .vscode/extensions.json 으로 원격에 필요한 확장을 알리는 방법