VSCode Dev Container는 프로젝트 폴더를 컨테이너 안에서 열어, 팀원마다 다른 로컬 설치 상태 때문에 생기는 문제를 줄이는 방법이다. Node.js 버전이 다르거나, Python 패키지가 꼬이거나, 맥·윈도우 환경 차이 때문에 실행 결과가 달라질 때 특히 효과가 크다. 프로젝트 안의 devcontainer.json 파일이 개발 도구, 런타임, 확장 기능, 포트, 초기 명령을 함께 정의해 주기 때문에 새 컴퓨터에서도 같은 환경을 빠르게 재현할 수 있다.
가장 많이 함께 찾는 표현은 VSCode Dev Container, devcontainer.json, Docker 개발환경, VSCode Docker, 개발환경 통일, Remote Containers 같은 조합이다. 실제로 시작할 때는 “무엇을 설치해야 하는지”, “Docker Compose도 되는지”, “왜 느린지”, “Rebuild는 언제 눌러야 하는지”가 가장 자주 막히는 지점이다.
VSCode Dev Container가 필요한 순간
로컬에 Node, Python, Java, 데이터베이스 클라이언트까지 직접 설치해 쓰면 처음엔 편해 보여도 프로젝트가 늘수록 충돌이 잦아진다. 어떤 프로젝트는 Node 20을 요구하고, 다른 프로젝트는 Python 3.11과 특정 시스템 패키지를 요구할 수 있다. Dev Container를 쓰면 이런 도구를 운영체제 전체에 흩뿌리지 않고 프로젝트 단위로 분리할 수 있다.
- 새 맥북이나 새 PC에서도 개발환경 복구가 빠르다
- 팀원 전원이 같은 버전의 도구를 쓸 수 있다
- 온보딩 문서를 길게 쓰지 않아도 된다
- “내 컴퓨터에서는 되는데요” 상황을 크게 줄일 수 있다
특히 프론트엔드와 백엔드, 데이터베이스, 테스트 도구가 함께 움직이는 프로젝트라면 효과가 더 크다. Docker와 VSCode가 연결되어 있으면 폴더를 열자마자 필요한 런타임과 확장을 자동으로 맞출 수 있기 때문이다.
시작 전에 필요한 준비물
기본 준비는 세 가지다. VSCode, Docker Desktop, 그리고 프로젝트 루트의 .devcontainer 폴더다. Docker Desktop이 실행 중이 아니면 Dev Container는 열리지 않는다. 또한 컨테이너 안에서 Git을 쓰려면 로컬 Git 기본 설정도 미리 끝내 두는 편이 좋다.
| 준비 항목 | 왜 필요한가 |
|---|---|
| VSCode | 폴더를 컨테이너 안에서 열고 확장 기능을 연결하기 위해 필요 |
| Docker Desktop | 개발용 컨테이너를 만들고 실행하는 엔진 역할 |
| .devcontainer/devcontainer.json | 개발환경 규칙을 프로젝트와 함께 저장하는 핵심 설정 파일 |
가장 쉬운 devcontainer.json 예시
처음에는 복잡한 멀티 컨테이너보다 단일 컨테이너부터 시작하는 편이 안정적이다. 예를 들어 Node.js 프로젝트라면 아래처럼 많이 시작한다.
{
"name": "Node Dev Container",
"image": "mcr.microsoft.com/devcontainers/javascript-node:1-20-bullseye",
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
]
}
},
"forwardPorts": [3000],
"postCreateCommand": "npm install"
}
핵심만 보면 어렵지 않다. image는 베이스 개발환경이고, extensions는 컨테이너 안에서 같이 쓸 VSCode 확장 기능이다. forwardPorts는 로컬 브라우저에서 접근할 포트이며, postCreateCommand는 컨테이너가 처음 만들어진 뒤 실행할 명령이다.
Python 프로젝트라면 무엇이 달라질까
Python은 인터프리터 경로와 패키지 설치 위치가 중요하다. 그래서 Python 이미지를 사용하고, postCreateCommand에 pip install 또는 uv sync 같은 초기 명령을 넣는 식으로 시작한다. 데이터 분석이나 웹 백엔드 프로젝트는 requirements.txt, pyproject.toml, .venv 처리 방식을 팀 단위로 미리 정해 두면 훨씬 덜 흔들린다.
Docker Compose를 함께 쓰는 경우
웹 앱만 있는 프로젝트보다, API 서버와 DB를 함께 띄워야 하는 경우가 더 많다. 이때는 docker-compose.yml 또는 Compose 기반 설정을 함께 쓰면 된다. 앱 컨테이너 하나만 여는 대신, 데이터베이스 같은 보조 서비스까지 같이 구성할 수 있어 실제 개발 환경과 더 비슷해진다.
다만 처음부터 서비스가 여러 개면 로그가 길어지고 원인 파악이 어려워진다. 입문 단계에서는 “앱 컨테이너 1개”로 먼저 성공한 뒤, 그 다음에 PostgreSQL이나 Redis를 추가하는 순서가 가장 안정적이다.
초보가 가장 자주 막히는 오류 6가지
- Docker가 꺼져 있음 — VSCode는 정상인데 컨테이너 빌드가 시작조차 안 되는 경우가 많다.
- Reopen in Container 대신 일반 열기 상태 — 로컬 터미널에서 명령이 실행되어 혼동이 생긴다.
- 이미지 빌드 캐시 꼬임 — 설정을 바꿨는데 반영이 안 되면 Rebuild Container가 필요하다.
- 포트 미노출 — 서버는 떴는데 브라우저 접속이 안 되면 forwardPorts를 확인한다.
- 권한 문제 — 볼륨 마운트나 파일 생성 권한 때문에 npm, pip 설치가 실패할 수 있다.
- 맥에서 디스크 I/O 느림 — 의존성 설치가 느리면 마운트 방식과 저장 위치를 점검해야 한다.
특히 설정을 바꾼 뒤에도 문제가 그대로라면 “다시 열기”보다 Rebuild Container가 필요한 경우가 많다. devcontainer.json, Dockerfile, Compose 파일을 수정했다면 재생성이 필요한지 먼저 떠올리면 시간을 많이 아낄 수 있다.
Dev Container를 더 편하게 쓰는 실전 팁
- 프로젝트별 런타임 버전을 컨테이너에 고정해 두면 로컬 오염이 줄어든다
- 확장 기능은 자주 쓰는 것만 넣어 빌드와 초기화 시간을 줄인다
- Git 설정과 SSH 인증은 로컬에서 먼저 안정화해 두는 편이 좋다
- 팀 문서에는 “열기 → Reopen in Container → 첫 빌드 시간” 정도만 짧게 남겨도 충분하다
처음부터 완벽한 템플릿을 만들 필요는 없다. 자주 쓰는 언어 하나로 시작해서, 필요한 도구와 포트, 확장 기능만 추가하는 방식이 가장 덜 헷갈린다. Node 프로젝트, Python 프로젝트를 각각 하나씩 만들어 두면 이후 새 저장소에도 재활용하기 쉽다.
처음 적용할 때 가장 무난한 추천 순서
가장 실패가 적은 순서는 이렇다. 먼저 Docker Desktop이 안정적으로 설치되어 있는지 확인하고, VSCode에 Dev Containers 관련 기능이 정상 동작하는지 본다. 그다음 단일 컨테이너 예제로 한 번 성공한 뒤, Node 또는 Python 의존성 설치를 붙이고, 마지막으로 Compose와 DB를 추가한다. 이 순서대로 가면 어디서 꼬였는지 원인을 찾기 쉽다.
결국 Dev Container의 핵심은 “새 컴퓨터에서도 같은 개발환경이 바로 열리는 상태”를 만드는 것이다. 한 번만 제대로 잡아 두면 개인 작업뿐 아니라 팀 협업, 인수인계, 프로젝트 재시작 때 체감 차이가 크게 난다.
0 댓글