Docker와 VS Code Dev Container를 활용한 완벽한 개발 환경 구축 가이드

06 Apr 2026

‘제 PC에서는 잘 되는데요?’ 이 말은 개발자 협업 시 가장 흔하게 발생하는 골치 아픈 문제 중 하나입니다. 개발자마다 다른 운영체제, 설치된 라이브러리 버전의 미세한 차이, 각종 환경 변수 설정 등은 예측 불가능한 버그를 낳고 프로젝트 전체의 발목을 잡기도 합니다. 이러한 문제를 ‘환경의 비일관성’이라고 부릅니다.

이 문제를 해결하기 위해 등장한 개념이 바로 컨테이너 기술, 그리고 그 중심에는 Docker가 있습니다. Docker는 어플리케이션과 그에 필요한 모든 종속성을 하나의 격리된 ‘컨테이너’로 패키징하여, 어떤 환경에서든 동일하게 실행될 수 있도록 보장합니다. 더 이상 개발 환경과 운영 환경의 차이로 인해 고통받을 필요가 없어진 것입니다.

여기서 한 걸음 더 나아가, Visual Studio Code의 Dev Container 기능은 Docker 컨테이너를 단순한 실행 환경이 아닌, 완벽한 ‘개발 환경’으로 탈바꿈시킵니다. VS Code 에디터 자체를 컨테이너 내부에 연결하여, 마치 로컬 환경에서 개발하는 것처럼 편리하게 코드 작성, 디버깅, 터미널 사용이 가능해집니다. 이 포스트에서는 Docker와 VS Code Dev Container를 활용하여 누구나, 어떤 OS에서든 동일하고 재현 가능한 개발 환경을 구축하는 방법을 단계별로 상세히 알아보겠습니다.

왜 개발 환경 격리가 중요한가요?

프로젝트에 새로운 팀원이 합류했다고 가정해 보겠습니다. 이 팀원은 프로젝트에 필요한 언어 런타임(Python, Node.js 등), 데이터베이스, 각종 라이브러리를 자신의 노트북에 설치해야 합니다. 이 과정에서 다음과 같은 문제들이 발생할 수 있습니다.

운영체제(OS)의 차이: Windows, macOS, Linux 사용자는 설치 과정과 명령어, 경로 등에서 미세한 차이를 겪습니다.
의존성 충돌(Dependency Hell): 프로젝트 A는 Python 3.8을 요구하고, 프로젝트 B는 3.10을 요구하는 경우처럼, 시스템 전역에 설치된 라이브러리 버전이 충돌할 수 있습니다.
‘설정의 늪’: 수많은 환경 변수와 설정 파일을 일일이 수동으로 맞춰야 하므로 시간이 오래 걸리고 실수가 발생하기 쉽습니다.

이러한 문제들은 결국 ‘내 PC에서는 되는데, 다른 사람 PC에서는 안 되는’ 상황을 초래하며, 불필요한 디버깅 시간과 팀 전체의 생산성 저하로 이어집니다. 개발 환경의 격리 및 표준화는 이러한 문제를 근본적으로 해결하기 위한 필수적인 첫걸음입니다.

Docker 컨테이너: 일관성의 시작

Docker는 어플리케이션 구동에 필요한 모든 것(코드, 런타임, 시스템 도구, 라이브러리 등)을 이미지(Image) 라는 패키지로 만듭니다. 그리고 이 이미지를 실행하면 컨테이너(Container) 라는 격리된 프로세스가 됩니다.

가장 큰 장점은 이식성(Portability) 입니다. Docker가 설치된 곳이라면 어디서든 동일한 이미지를 통해 동일한 컨테이너를 실행할 수 있습니다. 개발자의 노트북, 테스트 서버, 실제 운영(프로덕션) 서버 모두에서 동일한 환경이 보장되는 것입니다. Dockerfile이라는 간단한 텍스트 파일에 필요한 환경을 코드로 정의하므로, 환경 설정 자체가 버전 관리의 대상이 되어 투명하고 재현 가능해집니다.

VS Code Dev Container: 개발 경험의 혁신

Docker는 훌륭한 실행 환경을 제공하지만, 개발 과정 자체는 여전히 개발자의 로컬 머신에서 이루어집니다. 소스 코드는 로컬에 있고, 에디터도 로컬에서 실행됩니다. VS Code의 Dev Container(Development Container) 확장 기능은 이러한 경계를 허물어 버립니다.

Dev Container를 사용하면 VS Code는 지정된 Docker 컨테이너 내부에 연결하여, 해당 컨테이너 자체를 완전한 기능을 갖춘 개발 환경으로 사용하게 됩니다.

코드 자동 완성, 린팅, 디버깅: VS Code의 모든 강력한 기능들이 컨테이너 내부에서 직접 동작합니다.
터미널: VS Code 내장 터미널을 열면, 호스트 머신이 아닌 컨테이너의 셸에 직접 접근하게 됩니다.
확장 기능: 개발에 필요한 VS Code 확장 기능들도 컨테이너 내부에 격리하여 설치하고 실행할 수 있습니다.

즉, 개발자는 자신의 PC에 프로젝트와 관련된 어떤 도구나 라이브러리도 설치할 필요 없이, 오직 Docker와 VS Code만으로 모든 개발을 컨테이너 안에서 완결할 수 있습니다.

실전! Dev Container 환경 구축하기

이제 실제로 간단한 Node.js 프로젝트를 위한 Dev Container 환경을 구축해 보겠습니다.

사전 준비물

먼저 아래의 도구들이 설치되어 있어야 합니다.

Docker Desktop: 운영체제에 맞는 버전을 설치합니다. Docker 엔진을 GUI로 쉽게 관리할 수 있게 해줍니다. (Docker Desktop 다운로드)
Visual Studio Code: 최신 버전의 VS Code를 설치합니다. (VS Code 다운로드)
Dev Containers 확장 기능: VS Code 마켓플레이스에서 ms-vscode-remote.remote-containers를 검색하여 설치합니다.

1단계: 프로젝트 폴더 생성 및 VS Code 실행

먼저, 프로젝트를 위한 빈 폴더를 하나 생성하고 해당 폴더를 VS Code로 엽니다.

mkdir my-dev-container-project
cd my-dev-container-project
code .

2단계: Dev Container 설정 파일 추가

VS Code가 열리면, F1 키를 누르거나 Ctrl+Shift+P(macOS: Cmd+Shift+P)를 눌러 커맨드 팔레트를 엽니다. 그리고 Dev Containers: Add Dev Container Configuration Files...를 입력하고 선택합니다.

Dev Container 설정 추가

그러면 다양한 언어와 프레임워크 템플릿 목록이 나타납니다. 여기서는 Node.js & TypeScript를 선택하겠습니다. 그 후 버전을 선택하라는 메시지가 나오면 원하는 버전을 선택합니다. (예: 18) 추가로 설치할 기능(features)을 선택하라는 창이 나오면 일단 OK를 눌러 넘어갑니다.

3단계: 생성된 파일 분석 (.devcontainer 폴더)

위 단계를 완료하면 프로젝트 루트에 .devcontainer라는 폴더가 생성되고, 그 안에 devcontainer.json 파일과 Dockerfile이 만들어집니다.

devcontainer.json

이 파일은 Dev Container의 핵심 설정 파일입니다.

// .devcontainer/devcontainer.json
{
	"name": "Node.js & TypeScript",
	// Dockerfile을 사용하여 이미지를 빌드하도록 설정
	"build": {
		"dockerfile": "Dockerfile"
	},

	// VS Code 관련 커스터마이징
	"customizations": {
		"vscode": {
			"settings": {},
			// 컨테이너에 설치할 VS Code 확장 기능 목록
			"extensions": [
				"dbaeumer.vscode-eslint"
			]
		}
	},

	// 컨테이너 생성 후 실행할 명령어
	// "postCreateCommand": "npm install",

	// 호스트와 컨테이너 간 포트 포워딩 설정
	"forwardPorts": [3000],

	// 컨테이너에 접속할 유저
	"remoteUser": "node"
}

build.dockerfile: 어떤 Dockerfile을 사용해서 환경을 구축할지 지정합니다.
customizations.vscode.extensions: 이 컨테이너 환경에서 자동으로 설치하고 활성화할 VS Code 확장 기능의 ID 목록입니다.
forwardPorts: 컨테이너 내부의 포트를 로컬 머신의 포트로 연결합니다. 웹 서버 개발 시 유용합니다.
postCreateCommand: 컨테이너가 처음 생성된 후 자동으로 실행할 셸 명령어를 지정할 수 있습니다. (예: npm install)

Dockerfile

이 파일은 Docker 이미지를 어떻게 만들지 정의하는 스크립트입니다.

# .devcontainer/Dockerfile
# 공식 Node.js 이미지를 기반으로 시작
FROM mcr.microsoft.com/devcontainers/typescript-node:0-18

# [Optional] 시스템 패키지 설치 등 추가 설정 가능
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>

이 Dockerfile은 Microsoft에서 제공하는 사전 빌드된 Node.js 개발용 이미지를 기반으로 합니다. 필요하다면 apt-get 등의 명령어를 사용하여 추가적인 시스템 라이브러리를 설치할 수도 있습니다.

4단계: 컨테이너에서 프로젝트 재오픈

설정 파일 생성이 완료되면 VS Code 우측 하단에 “Reopen in Container”라는 알림창이 나타납니다. 이 버튼을 클릭합니다.

만약 알림창을 놓쳤다면, F1 키를 눌러 커맨드 팔레트를 열고 Dev Containers: Reopen in Container를 실행해도 됩니다.

이제 VS Code는 Dockerfile을 기반으로 Docker 이미지를 빌드하고, 해당 이미지로부터 컨테이너를 실행한 뒤, 그 컨테이너 내부로 VS Code 백엔드 서버를 설치하고 연결하는 작업을 자동으로 수행합니다. 이 과정은 처음 실행 시 몇 분 정도 소요될 수 있습니다.

5단계: 개발 시작 및 환경 확인

모든 과정이 끝나면 VS Code 창이 다시 열립니다. 이제 여러분은 컨테이너 안에서 개발할 준비가 되었습니다.

VS Code의 내장 터미널(Ctrl+ ``)을 열어봅시다. 그리고 Node.js 버전을 확인해 보세요.

node -v
# 출력: v18.x.x (Dockerfile에서 지정한 버전)

이제 이 터미널에서 실행하는 모든 명령어(npm install, npm start 등)는 호스트 머신이 아닌, 완벽하게 격리된 Docker 컨테이너 내부에서 실행됩니다. 이제 팀원 누구든지 이 프로젝트를 Git에서 클론받고 “Reopen in Container”만 클릭하면, 단 몇 분 만에 여러분과 100% 동일한 개발 환경을 갖추게 됩니다.

Jiwon Min Developer