컨테이너 내부에서 개발하기

Visual Studio Code Dev Containers 확장을 사용하면 컨테이너를 모든 기능을 갖춘 개발 환경으로 사용할 수 있습니다. 이를 통해 컨테이너 안(또는 컨테이너로 마운트된)의 모든 폴더를 열고 Visual Studio Code의 모든 기능을 활용할 수 있습니다. 프로젝트의 devcontainer.json 파일은 VS Code에 정의된 도구 및 런타임 스택으로 개발 컨테이너를 액세스(또는 생성)하는 방법을 알려줍니다. 이 컨테이너는 애플리케이션을 실행하거나 코드베이스 작업에 필요한 도구, 라이브러리 또는 런타임을 분리하는 데 사용할 수 있습니다.

작업 공간 파일은 로컬 파일 시스템에서 마운트되거나 컨테이너로 복사되거나 복제됩니다. 확장은 컨테이너 내부에서 설치 및 실행되며, 도구, 플랫폼 및 파일 시스템에 완전히 액세스할 수 있습니다. 이는 다른 컨테이너에 연결하는 것만으로 전체 개발 환경을 원활하게 전환할 수 있다는 것을 의미합니다.

Container Architecture

이를 통해 VS Code는 **로컬 품질의 개발 환경**을 제공하며, 도구(또는 코드)의 위치에 관계없이 전체 IntelliSense(완성), 코드 탐색 및 디버깅을 지원합니다.

Dev Containers 확장은 두 가지 주요 운영 모델을 지원합니다.

컨테이너를 전체 개발 환경으로 사용할 수 있습니다.
실행 중인 컨테이너에 연결하여 검사할 수 있습니다.

참고: Dev Containers 확장은 개방형 Dev Containers 사양을 지원하며, 이를 통해 모든 도구에서 일관된 개발 환경을 구성할 수 있습니다. 자세한 내용은 dev container FAQ 및 사양 사이트 containers.dev에서 확인할 수 있습니다.

시작하기

참고: 소개 Dev Containers 튜토리얼에서 dev containers를 빠르게 시작하는 방법을 배울 수 있습니다.

시스템 요구 사항

로컬 / 원격 호스트

Dev Containers 확장을 사용하여 Docker를 몇 가지 방법으로 사용할 수 있습니다.

로컬에 설치된 Docker.
원격 환경에 설치된 Docker.
로컬 또는 원격에 설치된 기타 Docker 호환 CLI.
- 다른 CLI도 작동할 수 있지만 공식적으로 지원되지는 않습니다. Kubernetes 클러스터에 연결하려면 제대로 구성된 kubectl CLI만 있으면 됩니다.

자세한 내용은 대체 Docker 옵션 문서에서 확인할 수 있습니다.

로컬 또는 원격 호스트에서 Docker를 구성하는 몇 가지 특정 방법을 아래에 설명합니다.

Windows: Windows 10 Pro/Enterprise에서 Docker Desktop 2.0 이상. Windows 10 Home(2004+)은 Docker Desktop 2.3 이상 및 WSL 2 백엔드가 필요합니다. (Docker Toolbox는 지원되지 않습니다. Windows 컨테이너 이미지는 지원되지 않습니다.)
macOS: Docker Desktop 2.0 이상.
Linux: Docker CE/EE 18.06 이상 및 Docker Compose 1.21 이상. (Ubuntu snap 패키지는 지원되지 않습니다.)
원격 호스트: 1GB RAM이 필요하지만 최소 2GB RAM 및 2코어 CPU가 권장됩니다.

컨테이너:

x86_64 / ARMv7l (AArch32) / ARMv8l (AArch64) Debian 9+, Ubuntu 16.04+, CentOS / RHEL 7+
x86_64 Alpine Linux 3.9+

기타 glibc 기반 Linux 컨테이너는 필요한 Linux 사전 요구 사항이 있는 경우 작동할 수 있습니다.

설치

시작하려면 다음 단계를 따르십시오.

운영 체제에 맞는 Docker를 설치하고 구성합니다. 아래 경로 중 하나 또는 원격 호스트의 Docker 또는 Docker 호환 CLI와 같은 대체 Docker 옵션을 사용합니다.

Windows / macOS:
1. Docker Desktop for Windows/Mac을 설치합니다.
2. Windows에서 WSL 2를 사용하는 경우 Docker Desktop의 WSL 2 백엔드가 활성화되어 있는지 확인하려면: Docker 작업 표시줄 항목을 마우스 오른쪽 버튼으로 클릭하고 **설정**을 선택합니다. **Use the WSL 2 based engine**을 선택하고 **Resources > WSL Integration**에서 배포판이 활성화되어 있는지 확인합니다.
3. WSL 2 백엔드를 사용하지 않는 경우 Docker 작업 표시줄 항목을 마우스 오른쪽 버튼으로 클릭하고 **설정**을 선택한 후 **Resources > File Sharing**에서 소스 코드가 저장된 모든 위치를 업데이트합니다. 문제 해결에 대한 자세한 내용은 팁 및 요령을 참조하십시오.
Linux:
1. 해당 배포판에 맞는 Docker CE/EE의 공식 설치 지침을 따릅니다. Docker Compose를 사용하는 경우 Docker Compose 지침도 따릅니다.
2. 터미널을 사용하여 다음을 실행하여 사용자를 docker 그룹에 추가합니다: sudo usermod -aG docker $USER
3. 변경 사항을 적용하려면 로그아웃했다가 다시 로그인합니다.
Visual Studio Code 또는 Visual Studio Code Insiders를 설치합니다.
Dev Containers 확장을 설치합니다. VS Code에서 다른 원격 확장을 사용하려는 경우 Remote Development 확장 팩을 설치하는 것이 좋습니다.

Git을 사용하시나요?

고려할 두 가지 팁입니다.

로컬 Windows 환경과 컨테이너 내부에서 동일한 리포지토리를 작업하는 경우 일관된 줄 끝 문자를 설정해야 합니다. 자세한 내용은 팁 및 요령을 참조하십시오.
Git 자격 증명 관리자를 사용하여 복제하는 경우 컨테이너가 이미 자격 증명에 액세스할 수 있어야 합니다! SSH 키를 사용하는 경우 공유를 선택할 수도 있습니다. 자세한 내용은 컨테이너와 Git 자격 증명 공유를 참조하십시오.

빠른 시작 선택

이 문서는 3가지 빠른 시작을 포함합니다. 워크플로우와 관심사에 가장 적합한 것을 선택하여 시작하는 것을 권장합니다.

간단한 샘플 리포지토리에서 개발 컨테이너를 사용해보고 싶으신가요? 빠른 시작 1: 개발 컨테이너 사용해 보기를 확인하세요.
기존에 로컬로 복제한 프로젝트에 개발 컨테이너를 추가하고 싶으신가요? 빠른 시작 2: 컨테이너에서 기존 폴더 열기를 확인하세요.
PR 검토 또는 로컬 작업에 영향을 주지 않고 브랜치를 조사하기 위해 리포지토리의 격리된 복사본으로 작업하고 싶으신가요? 빠른 시작 3: 격리된 컨테이너 볼륨에서 Git 리포지토리 또는 PR 열기를 확인하세요.

빠른 시작: 개발 컨테이너 사용해 보기

시작하는 가장 쉬운 방법은 샘플 개발 컨테이너를 사용해 보는 것입니다. 컨테이너 튜토리얼은 Docker 및 Dev Containers 확장을 설정하는 과정을 안내하며 샘플을 선택할 수 있도록 합니다.

Select a sample from the list

참고: 이미 VS Code와 Docker가 설치되어 있다면 dev container에서 열기를 사용할 수 있습니다. 이 기능에 대한 자세한 내용과 리포지토리에 추가하는 방법에 대해서는 dev container 만들기 가이드를 참조하십시오.

빠른 시작: 컨테이너에서 기존 폴더 열기

이 빠른 시작에서는 기존 프로젝트에 대한 개발 컨테이너를 설정하여 기존 파일 시스템의 소스 코드를 사용하여 전체 개발 환경으로 사용하는 방법을 다룹니다. 다음 단계를 따르십시오.

VS Code를 시작하고 명령 팔레트(F1) 또는 빠른 작업 상태 표시줄 항목에서 **Dev Containers: Open Folder in Container...** 명령을 실행한 다음 컨테이너 설정을 원하는 프로젝트 폴더를 선택합니다.

팁: 폴더를 열기 전에 컨테이너의 내용이나 설정을 편집하려면 대신 **Dev Containers: Add Dev Container Configuration Files...** 명령을 실행할 수 있습니다.
이제 개발 컨테이너의 시작점을 선택합니다. 필터링 가능한 목록에서 **Dev Container Template**을 선택하거나, 선택한 폴더에 이미 있는 Dockerfile 또는 Docker Compose 파일을 사용할 수 있습니다.

참고: Alpine Linux 컨테이너를 사용할 때 일부 확장 프로그램은 네이티브 코드 내의 glibc 종속성으로 인해 작동하지 않을 수 있습니다.

목록은 열리는 폴더의 내용에 따라 자동으로 정렬됩니다.

추가 기능으로 개발 컨테이너를 사용자 지정할 수 있습니다. 자세한 내용은 아래에서 확인할 수 있습니다.

표시되는 개발 컨테이너 템플릿은 Dev Container 사양의 일부인 자체 및 커뮤니티 인덱스에서 제공됩니다. 사명의 일부로 템플릿 세트를 devcontainers/templates 리포지토리에 호스팅합니다. 해당 리포지토리의 src 폴더를 탐색하여 각 템플릿의 내용을 확인할 수 있습니다.

자체 개발 컨테이너 템플릿을 게시하고 배포하기 위해 dev container CLI를 사용할 수도 있습니다.
컨테이너의 시작점을 선택한 후 VS Code는 개발 컨테이너 구성 파일을 프로젝트에 추가합니다(.devcontainer/devcontainer.json).
VS Code 창이 다시 로드되고 개발 컨테이너 빌드가 시작됩니다. 진행률 알림에 상태 업데이트가 표시됩니다. 개발 컨테이너는 처음 열 때만 빌드하면 됩니다. 첫 번째 빌드가 성공적으로 완료된 후 폴더를 열면 훨씬 빠르게 열립니다.
빌드가 완료되면 VS Code가 자동으로 컨테이너에 연결됩니다.

이제 로컬에서 프로젝트를 열 때와 마찬가지로 VS Code에서 프로젝트와 상호 작용할 수 있습니다. 앞으로 프로젝트 폴더를 열면 VS Code가 개발 컨테이너 구성을 자동으로 인식하고 재사용합니다.

팁: 원격 Docker 호스트를 사용하고 싶으신가요? 정보는 컨테이너에서 원격 SSH 호스트의 폴더 열기 섹션을 참조하세요.

로컬 파일 시스템을 컨테이너로 바인드 마운트하는 이 접근 방식을 사용하는 것은 편리하지만 Windows 및 macOS에서는 성능 오버헤드가 발생할 수 있습니다. 디스크 성능을 개선하기 위한 몇 가지 기법이 있으며, 대신 격리된 컨테이너 볼륨에서 리포지토리를 컨테이너로 열기를 사용할 수도 있습니다.

Windows에서 WSL 2 폴더를 컨테이너로 열기

Windows Subsystem for Linux v2(WSL 2)를 사용하고 Docker Desktop의 WSL 2 백엔드를 활성화한 경우 WSL 내부에 저장된 소스 코드와 작업할 수 있습니다!

WSL 2 엔진이 활성화되면 다음 중 하나를 수행할 수 있습니다.

WSL 확장을 사용하여 이미 열려 있는 폴더에서 **Dev Containers: Reopen in Container** 명령을 사용합니다.
명령 팔레트(F1)에서 **Dev Containers: Open Folder in Container...**를 선택하고 로컬 \\wsl$ 공유(Windows 측)를 통해 WSL 폴더를 선택합니다.

나머지 빠른 시작은 그대로 적용됩니다! WSL 확장에 대한 자세한 내용은 해당 문서를 참조하세요.

컨테이너에서 원격 SSH 호스트의 폴더 열기

Linux 또는 macOS SSH 호스트를 사용하는 경우 Remote - SSH 확장과 Dev Containers 확장을 함께 사용할 수 있습니다. 로컬에 Docker 클라이언트를 설치할 필요도 없습니다.

이를 위해

Remote - SSH 확장에 대한 설치 및 SSH 호스트 설정 단계를 따르십시오.
선택 사항: 비밀번호를 여러 번 입력할 필요가 없도록 서버에 대한 SSH 키 기반 인증을 설정하십시오.
SSH 호스트에 Docker를 설치하십시오. 로컬에 Docker를 설치할 필요는 없습니다.
Remote - SSH 확장에 대한 빠른 시작을 따라 호스트에 연결하고 폴더를 엽니다.
명령 팔레트(F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P))에서 **Dev Containers: Reopen in Container** 명령을 사용하십시오.

나머지 Dev Containers 빠른 시작은 그대로 적용됩니다. Remote - SSH 확장에 대한 자세한 내용은 해당 문서를 참조하세요. 또한 이 모델이 요구 사항을 충족하지 않는 경우 다른 옵션은 원격 Docker 호스트에서 개발 문서를 참조할 수 있습니다.

컨테이너에서 원격 터널 호스트의 폴더 열기

Remote - Tunnels 확장과 Dev Containers 확장을 함께 사용하여 원격 호스트의 폴더를 컨테이너 안으로 열 수 있습니다. 로컬에 Docker 클라이언트를 설치할 필요도 없습니다. 이는 위 SSH 호스트 시나리오와 유사하지만 Remote - Tunnels를 사용합니다.

이를 위해

Remote - Tunnels 확장의 시작하기 지침을 따르십시오.
터널 호스트에 Docker를 설치하십시오. 로컬에 Docker를 설치할 필요는 없습니다.
Remote - Tunnels 확장에 대한 단계를 따라 터널 호스트에 연결하고 폴더를 엽니다.
명령 팔레트(F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P))에서 **Dev Containers: Reopen in Container** 명령을 사용하십시오.

나머지 Dev Containers 빠른 시작은 그대로 적용됩니다. Remote - Tunnels 확장에 대한 자세한 내용은 해당 문서를 참조하세요. 또한 이 모델이 요구 사항을 충족하지 않는 경우 다른 옵션은 원격 Docker 호스트에서 개발 문서를 참조할 수 있습니다.

컨테이너에서 기존 작업 공간 열기

작업 공간이 .code-workspace 파일이 있는 폴더 또는 해당 폴더 자체의 **하위 폴더에 대한 상대 경로만 참조하는 경우** VS Code 다중 루트 작업 공간을 **단일 컨테이너**로 열기 위해 유사한 프로세스를 따를 수도 있습니다.

다음 중 하나를 수행할 수 있습니다.

Dev Containers: Open Workspace in Container... 명령을 사용합니다.
컨테이너에서 .code-workspace 파일이 포함된 폴더를 연 후 **File > Open Workspace...**를 사용합니다.

연결 후 .devcontainer 폴더가 아직 표시되지 않는 경우 작업 공간에 **.devcontainer 폴더를 추가**하여 해당 내용을 쉽게 편집할 수 있습니다.

또한 동일한 VS Code 창에서 동일한 작업 공간에 대해 여러 컨테이너를 사용할 수는 없지만, 별도의 창에서 Docker Compose로 관리되는 여러 컨테이너를 한 번에 사용할 수 있다는 점에 유의하십시오.

빠른 시작: 격리된 컨테이너 볼륨에서 Git 리포지토리 또는 GitHub PR 열기

로컬로 복제된 리포지토리를 컨테이너로 열 수 있지만, PR 검토 또는 다른 브랜치 조사를 위해 작업에 영향을 주지 않고 격리된 복사본으로 작업하고 싶을 수 있습니다.

Repository Containers는 로컬 파일 시스템에 바인딩하는 대신 격리된 로컬 Docker 볼륨을 사용합니다. 파일 트리를 오염시키지 않는 것 외에도 로컬 볼륨은 Windows 및 macOS에서 성능이 향상된다는 이점이 있습니다. (이러한 유형의 볼륨을 다른 시나리오에서 사용하는 방법에 대한 자세한 내용은 고급 구성 디스크 성능 향상 문서를 참조하십시오.)

예를 들어, 다음 단계를 따라 Repository Container에서 "try" 리포지토리 중 하나를 엽니다.

VS Code를 시작하고 명령 팔레트(F1)에서 **Dev Containers: Clone Repository in Container Volume...** 명령을 실행합니다.
나타나는 입력 상자에 microsoft/vscode-remote-try-node(또는 다른 "try" 리포지토리), Git URI, GitHub 브랜치 URL 또는 GitHub PR URL을 입력하고 Enter를 누릅니다.

팁: 비공개 리포지토리를 선택하는 경우 자격 증명 관리자를 설정하거나 SSH 키를 SSH 에이전트에 추가하는 것이 좋습니다. 자세한 내용은 컨테이너와 Git 자격 증명 공유를 참조하십시오.
리포지토리에 .devcontainer/devcontainer.json 파일이 없는 경우, 필터링 가능한 목록 또는 기존 Dockerfile 또는 Docker Compose 파일(존재하는 경우)에서 시작점을 선택하라는 메시지가 표시됩니다.

참고: Alpine Linux 컨테이너를 사용할 때 일부 확장 프로그램은 네이티브 코드 내의 glibc 종속성으로 인해 작동하지 않을 수 있습니다.

목록은 열리는 폴더의 내용에 따라 자동으로 정렬됩니다. 표시되는 개발 컨테이너 템플릿은 Dev Container 사양의 일부인 자체 및 커뮤니티 인덱스에서 제공됩니다. 사명의 일부로 템플릿 세트를 devcontainers/templates 리포지토리에 호스팅합니다. 해당 리포지토리의 src 폴더를 탐색하여 각 템플릿의 내용을 확인할 수 있습니다.
VS Code 창(인스턴스)이 다시 로드되고 소스 코드를 복제하며 개발 컨테이너 빌드가 시작됩니다. 진행률 알림에 상태 업데이트가 표시됩니다.

2단계에서 GitHub 풀 요청 URL을 붙여넣은 경우 PR이 자동으로 체크아웃되고 GitHub Pull Requests 확장이 컨테이너에 설치됩니다. 이 확장은 PR 탐색기, 인라인 PR 댓글 상호 작용 및 상태 표시줄 가시성과 같은 추가 PR 관련 기능을 제공합니다.
빌드가 완료되면 VS Code가 자동으로 컨테이너에 연결됩니다. 이제 이 독립적인 환경에서 로컬로 코드를 복제한 것처럼 리포지토리 소스 코드와 작업할 수 있습니다.

참고: Docker 빌드 오류와 같은 이유로 컨테이너가 시작되지 않는 경우 나타나는 대화 상자에서 **Reopen in Recovery Container**를 선택하여 "복구 컨테이너"로 들어가 Dockerfile 또는 다른 내용을 편집할 수 있습니다. 이렇게 하면 복제된 리포지토리의 Docker 볼륨이 최소 컨테이너에서 열리고 생성 로그가 표시됩니다. 수정이 완료되면 **Reopen in Container**를 사용하여 다시 시도합니다.

팁: 원격 Docker 호스트를 사용하고 싶으신가요? 정보는 컨테이너에서 원격 SSH 호스트의 폴더 열기 섹션을 참조하세요.

작업 공간 신뢰

Visual Studio Code는 보안을 중요하게 생각하며 출처나 원본 작성자와 관계없이 안전하게 코드를 검색하고 편집할 수 있도록 지원합니다. 작업 공간 신뢰 기능을 사용하면 프로젝트 폴더에서 자동 코드 실행을 허용하거나 제한할지 여부를 결정할 수 있습니다.

Dev Containers 확장은 작업 공간 신뢰를 채택했습니다. 소스 코드를 열고 상호 작용하는 방식에 따라 편집하거나 실행하는 코드를 신뢰할지 여부를 다양한 시점에 결정하도록 요청받게 됩니다.

폴더를 컨테이너에서 다시 열기

기존 프로젝트에 대한 개발 컨테이너 설정에는 로컬(또는 WSL) 폴더를 신뢰해야 합니다. 창이 다시 로드되기 전에 로컬(또는 WSL) 폴더를 신뢰할지 묻는 메시지가 표시됩니다.

이 흐름에는 몇 가지 예외가 있습니다.

최근 항목을 클릭할 때.
**Open Folder in Container** 명령을 사용하면 창이 다시 로드된 후 신뢰가 이미 부여되지 않은 경우 신뢰를 묻습니다.

기존 컨테이너에 연결

기존 컨테이너에 연결할 때 연결이 컨테이너를 신뢰한다는 것을 확인하라는 메시지가 표시됩니다. 이 확인은 한 번만 수행됩니다.

Workspace trust prompt when attaching to container

볼륨에 리포지토리 복제

컨테이너 볼륨에 리포지토리 복제 시 리포지토리를 복제하는 것이 해당 리포지토리를 신뢰하는 것임을 확인하라는 메시지가 표시됩니다. 이 확인은 한 번만 수행됩니다.

Workspace trust prompt when cloning in container volume

볼륨 검사

볼륨 검사는 제한 모드에서 시작되며, 컨테이너 내부의 폴더를 신뢰할 수 있습니다.

원격으로 실행되는 Docker 데몬

이는 **Docker 데몬이 실행되는 머신을 신뢰**한다는 것을 의미합니다. 추가 확인 프롬프트는 없습니다(로컬/WSL 사례에 대해 위에 나열된 프롬프트만 해당).

devcontainer.json 파일 만들기

VS Code의 컨테이너 구성은 devcontainer.json 파일에 저장됩니다. 이 파일은 디버그 구성의 launch.json 파일과 유사하지만, 개발 컨테이너를 시작(또는 연결)하는 데 사용됩니다. 컨테이너가 실행될 때 설치할 확장 프로그램이나 환경을 준비하기 위한 생성 후 명령을 지정할 수도 있습니다. 개발 컨테이너 구성은 .devcontainer/devcontainer.json 아래에 있거나 프로젝트 루트의 .devcontainer.json 파일(점 접두사 유의)로 저장됩니다.

명령 팔레트(F1)에서 **Dev Containers: Add Dev Container Configuration Files...** 명령을 선택하면 프로젝트에 필요한 파일이 시작점으로 추가되며, 필요에 따라 추가로 사용자 지정할 수 있습니다. 이 명령을 사용하면 폴더 내용에 기반한 미리 정의된 컨테이너 구성 목록에서 선택하거나, 기존 Dockerfile을 재사용하거나, 기존 Docker Compose 파일을 재사용할 수 있습니다.

Select a node Dev Container Template

수동으로 devcontainer.json을 만들고 이미지, Dockerfile 또는 Docker Compose 파일 세트를 시작점으로 사용할 수도 있습니다. 다음은 미리 빌드된 Development Container 이미지 중 하나를 사용하는 간단한 예입니다.

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node",
  "forwardPorts": [3000],
  "customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
      // Add the IDs of extensions you want installed when the container is created.
      "extensions": ["streetsidesoftware.code-spell-checker"]
    }
  }
}

참고: 기본 이미지에 있는 내용을 기반으로 컨테이너에 추가 구성이 이미 추가됩니다. 예를 들어 위에서 streetsidesoftware.code-spell-checker 확장을 추가했으며, 컨테이너에는 "dbaeumer.vscode-eslint"도 포함됩니다. 이는 mcr.microsoft.com/devcontainers/typescript-node의 일부이기 때문입니다. 이는 devcontainer.json을 사용하여 사전 빌드할 때 자동으로 발생하며, 이에 대한 자세한 내용은 사전 빌드 섹션에서 확인할 수 있습니다.

devcontainer.json 파일을 만드는 방법에 대한 자세한 내용은 개발 컨테이너 만들기를 참조하십시오.

개발 컨테이너 기능

개발 컨테이너 "기능"은 설치 코드와 개발 컨테이너 구성의 자체 포함적이고 공유 가능한 단위입니다. 이름은 하나를 참조하면 자신 또는 협업자가 사용할 수 있는 도구, 런타임 또는 라이브러리 "기능"을 개발 컨테이너에 빠르고 쉽게 추가할 수 있다는 아이디어에서 비롯되었습니다.

Dev Containers: Add Dev Container Configuration Files를 사용하면 Git 또는 Azure CLI 설치와 같이 기존 개발 컨테이너 구성을 사용자 지정하는 스크립트 목록이 표시됩니다.

Dev container Features list drop down

컨테이너에서 다시 빌드하고 다시 열면 선택한 기능이 devcontainer.json에서 사용할 수 있습니다.

"features": {
    "ghcr.io/devcontainers/features/github-cli:1": {
        "version": "latest"
    }
}

devcontainer.json의 "features" 속성을 직접 편집할 때 IntelliSense가 제공됩니다.

Intellisense when modifying terraform Feature

Dev Containers: Configure Container Features 명령을 사용하여 기존 구성을 업데이트할 수 있습니다.

VS Code UI에서 소싱된 기능은 이제 중앙 인덱스에서 제공되며, 여러분도 기여할 수 있습니다. 현재 목록은 Dev Containers 사양 사이트에서 확인하고, 기능 게시 및 배포 방법을 배우세요.

"항상 설치됨" 기능

개발 컨테이너에 확장을 "항상 설치"하도록 설정하는 것과 유사하게, dev.containers.defaultFeatures 사용자 설정을 사용하여 항상 설치하고 싶은 기능들을 설정할 수 있습니다.

"dev.containers.defaultFeatures": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
},

자체 기능 만들기

자체 개발 컨테이너 기능을 만들고 게시하는 것도 쉽습니다. 게시된 기능은 지원되는 공개 또는 비공개 컨테이너 레지스트리에서 OCI 아티팩트로 저장 및 공유될 수 있습니다. 현재 게시된 기능 목록은 containers.dev에서 확인할 수 있습니다.

기능은 최소한 devcontainer-feature.json 및 install.sh 진입점 스크립트가 포함된 폴더 내의 자체 포함된 단위입니다.

+-- feature
|    +-- devcontainer-feature.json
|    +-- install.sh
|    +-- (other files)

feature/starter 리포지토리에서 개발 컨테이너 CLI를 사용하여 자체 공개 또는 비공개 기능을 게시하는 방법에 대한 지침을 확인하세요.

기능 사양 및 배포

기능은 오픈 소스 개발 컨테이너 사양의 핵심 부분입니다. 기능이 작동하는 방식 및 배포에 대한 자세한 내용을 검토할 수 있습니다.

개발 컨테이너 이미지 사전 빌드

개발 컨테이너를 열 때마다 컨테이너 이미지를 생성하고 빌드하는 대신 필요한 도구가 포함된 이미지를 미리 빌드하는 것이 좋습니다. 미리 빌드된 이미지를 사용하면 컨테이너 시작 속도가 빨라지고 구성이 단순해지며, 도구의 특정 버전을 고정하여 공급망 보안을 개선하고 잠재적인 문제를 방지할 수 있습니다. GitHub Actions와 같은 DevOps 또는 CI(지속적 통합) 서비스를 사용하여 빌드를 예약함으로써 이미지 사전 빌드를 자동화할 수 있습니다.

더 나아가 미리 빌드된 이미지에는 개발 컨테이너 메타데이터가 포함될 수 있으므로 이미지를 참조할 때 설정이 자동으로 적용됩니다.

Dev Containers 확장의 최신 기능( 개발 컨테이너 기능 포함)과 동기화되어 있으므로 Dev Container CLI(또는 사양을 지원하는 GitHub Action과 같은 기타 유틸리티)를 사용하여 이미지를 사전 빌드하는 것이 좋습니다. 이미지를 빌드한 후에는 컨테이너 레지스트리(예: Azure Container Registry, GitHub Container Registry 또는 Docker Hub)에 푸시하고 직접 참조할 수 있습니다.

devcontainers/ci 리포지토리의 GitHub Action을 사용하여 워크플로우에서 개발 컨테이너를 재사용할 수 있습니다.

이미지 사전 빌드에 대한 자세한 내용은 dev container CLI 문서로 이동하십시오.

메타데이터 상속

개발 컨테이너 구성 및 기능 메타데이터를 미리 빌드된 이미지에 이미지 레이블을 통해 포함할 수 있습니다. 이렇게 하면 이미지가 자체 포함되어 직접 참조, 참조된 Dockerfile의 FROM 또는 Docker Compose 파일에서 설정이 자동으로 적용됩니다. 이는 개발 컨테이너 구성과 이미지 내용이 동기화되지 않는 것을 방지하는 데 도움이 되며, 간단한 이미지 참조를 통해 여러 리포지토리에 대한 동일한 구성 업데이트를 푸시할 수 있습니다.

이 메타데이터 레이블은 Dev Container CLI(또는 사양을 지원하는 GitHub Action 또는 Azure DevOps 작업과 같은 기타 유틸리티)를 사용하여 사전 빌드할 때 **자동으로 추가**되며, devcontainer.json 및 참조된 모든 개발 컨테이너 기능의 설정을 포함합니다.

이를 통해 이미지를 사전 빌드하는 데 사용되는 **더 복잡한** devcontainer.json과 하나 이상의 리포지토리에서 **훨씬 더 단순한** devcontainer.json을 가질 수 있습니다. 이미지의 내용은 컨테이너를 생성할 때 이 단순화된 devcontainer.json 내용과 병합됩니다 (병합 논리에 대한 정보는 사양으로 이동). 그러나 가장 간단한 형태로는 설정을 적용하기 위해 devcontainer.json에서 이미지를 직접 참조할 수 있습니다.

{
  "image": "mcr.microsoft.com/devcontainers/go:1"
}

참고로 수동으로 이미지 레이블에 메타데이터를 추가하도록 선택할 수도 있습니다. 이러한 속성은 개발 컨테이너 CLI를 사용하여 빌드하지 않은 경우에도 적용되며 (CLI에 의해 업데이트될 수도 있음) 예를 들어 다음 Dockerfile 스니펫을 고려하십시오.

LABEL devcontainer.metadata='[{ \
  "capAdd": [ "SYS_PTRACE" ], \
  "remoteUser": "devcontainer", \
  "postCreateCommand": "yarn install" \
}]'

볼륨 검사

가끔 Docker 명명된 볼륨을 검사하거나 변경하려는 상황에 직면할 수 있습니다. devcontainer.json 파일을 만들거나 수정하지 않고 VS Code를 사용하여 이러한 내용으로 작업할 수 있습니다. 명령 팔레트(F1)에서 **Dev Containers: Explore a Volume in a Dev Container...**를 선택하십시오.

원격 탐색기에서도 볼륨을 검사할 수 있습니다. 드롭다운에서 컨테이너가 선택되었는지 확인한 다음, **Dev Volumes** 섹션이 표시됩니다. 볼륨을 마우스 오른쪽 버튼으로 클릭하여 생성 시점, 볼륨에 복제된 리포지토리, 마운트 지점과 같은 생성 정보를 검사할 수 있습니다. 개발 컨테이너에서 탐색할 수도 있습니다.

Right-click dev volumes in Remote Explorer

Container Tools 확장이 설치된 경우 **Container Explorer**의 **Volumes** 섹션에서 볼륨을 마우스 오른쪽 버튼으로 클릭하고 **Explore in a Development Container**를 선택할 수 있습니다.

Explore in dev container in Container Tools context menu

확장 관리

VS Code는 확장을 두 가지 위치 중 하나에서 실행합니다: 로컬 UI/클라이언트 측 또는 컨테이너 내부. 테마 및 스니펫과 같이 VS Code UI에 영향을 주는 확장은 로컬에 설치되는 반면, 대부분의 확장은 특정 컨테이너 내부에 상주합니다. 이를 통해 주어진 작업에 필요한 확장만 컨테이너에 설치하고 새 컨테이너에 연결하는 것만으로 전체 툴체인을 원활하게 전환할 수 있습니다.

확장 보기에 있는 확장을 설치하면 올바른 위치에 자동으로 설치됩니다. 카테고리 그룹화에 따라 확장이 설치된 위치를 알 수 있습니다. **Local - Installed** 카테고리와 컨테이너용 카테고리가 있습니다.

Workspace Extension Category

Local Extension Category

참고: 확장 작성자이고 확장이 제대로 작동하지 않거나 잘못된 위치에 설치되는 경우 자세한 내용은 원격 개발 지원을 참조하십시오.

원격에서 실행되어야 하는 로컬 확장은 **Local - Installed** 카테고리에 **Disabled(비활성화됨)**로 표시됩니다. **Install(설치)**을 선택하여 원격 호스트에 확장을 설치하십시오.

Disabled Extensions w/Install Button

Dev Container에서 로컬로 설치된 모든 확장을 설치하려면 확장 보기로 이동하여 로컬 설치된 확장 제목 표시줄 오른쪽의 클라우드 버튼을 사용하여 Dev Container에 로컬 확장 설치: {Name}을 선택합니다. 그러면 컨테이너에 설치할 로컬로 설치된 확장을 선택할 수 있는 드롭다운이 표시됩니다.

Install all extensions

그러나 일부 확장에는 컨테이너에 추가 소프트웨어를 설치해야 할 수 있습니다. 문제가 발생하면 자세한 내용은 확장 문서를 참조하십시오.

devcontainer.json에 확장 추가

확장 ID 목록을 추가하기 위해 devcontainer.json 파일을 직접 편집할 수 있지만, 확장 보기에서 확장을 마우스 오른쪽 버튼으로 클릭하고 devcontainer.json에 추가를 선택할 수도 있습니다.

Add to devcontainer.json menu

확장 제외

기본 이미지 또는 기능이 dev 컨테이너에 설치하기를 원하지 않는 확장을 구성하는 경우 마이너스 기호로 확장을 나열하여 제외할 수 있습니다. 예를 들어

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
  "customizations": {
    "vscode": {
      "extensions": ["-dbaeumer.vscode-eslint"]
    }
  }
}

"항상 설치됨" 확장

모든 컨테이너에 항상 설치하기를 원하는 확장이 있는 경우 사용자 설정의 dev.containers.defaultExtensions을 업데이트할 수 있습니다. 예를 들어, GitLens 및 Resource Monitor 확장을 설치하고 싶다면 다음과 같이 확장 ID를 지정합니다.

"dev.containers.defaultExtensions": [
    "eamodio.gitlens",
    "mutantdino.resourcemonitor"
]

고급: 확장을 로컬 또는 원격으로 실행하도록 강제

확장은 일반적으로 로컬 또는 원격으로 실행되도록 설계 및 테스트되며 둘 다 실행되지는 않습니다. 그러나 확장이 지원하는 경우 settings.json 파일에서 특정 위치에서 실행되도록 강제할 수 있습니다.

예를 들어, 아래 설정은 Container Tools 확장을 로컬로 실행하고 Remote - SSH: Editing Configuration Files 확장을 기본값 대신 원격으로 실행하도록 강제합니다.

"remote.extensionKind": {
    "ms-azuretools.vscode-containers": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

"workspace" 대신 "ui" 값을 사용하면 확장이 로컬 UI/클라이언트 측에서 실행되도록 강제됩니다. 일반적으로 확장 문서에서 달리 명시하지 않는 한 테스트 목적으로만 사용해야 합니다. **확장이 작동하지 않을 수 있습니다**. 자세한 내용은 선호하는 확장 위치 섹션을 참조하십시오.

포트 전달 또는 게시

컨테이너는 별도의 환경이므로 컨테이너 내부의 서버, 서비스 또는 기타 리소스에 액세스하려면 포트를 호스트로 "포워딩"하거나 "게시"해야 합니다. 컨테이너가 이러한 포트를 항상 노출하도록 구성하거나 임시로 포워딩할 수 있습니다.

포트 항상 포워딩

컨테이너에서 폴더를 열거나 첨부할 때 devcontainer.json의 forwardPorts 속성을 사용하여 항상 포워딩하기를 원하는 포트 목록을 지정할 수 있습니다.

"forwardPorts": [3000, 3001]

창을 새로 고치거나 다시 열기만 하면 VS Code가 컨테이너에 연결될 때 설정이 적용됩니다.

포트 임시 포워딩

devcontainer.json에 추가하지 않았거나 Docker Compose 파일에 게시하지 않은 포트에 액세스해야 하는 경우, 명령 팔레트(F1)에서 포트 포워딩 명령을 실행하여 세션 기간 동안 새 포트를 **임시로 포워딩**할 수 있습니다.

Forward port input

포트를 선택한 후 알림에 컨테이너의 포트에 액세스하는 데 사용해야 하는 localhost 포트가 표시됩니다. 예를 들어, 포트 3000에서 수신 대기 중인 HTTP 서버를 포워딩한 경우 알림에 localhost의 포트 4123으로 매핑되었다고 표시될 수 있습니다. 그런 다음 https://:4123을 사용하여 이 원격 HTTP 서버에 연결할 수 있습니다.

이 정보는 나중에 액세스해야 하는 경우 원격 탐색기의 포워딩된 포트 섹션에서도 사용할 수 있습니다.

포워딩된 포트를 VS Code가 기억하도록 하려면 설정 편집기(⌘, (Windows, Linux Ctrl+,))에서 원격: 포워딩된 포트 복원을 선택하거나 settings.json에 "remote.restoreForwardedPorts": true를 설정하십시오.

Restore forwarded ports setting

포트 게시

Docker에는 컨테이너가 생성될 때 포트를 "게시"하는 개념이 있습니다. 게시된 포트는 로컬 네트워크에 제공하는 포트와 매우 유사하게 작동합니다. 애플리케이션이 localhost에서 오는 호출만 허용하는 경우, 로컬 컴퓨터가 네트워크 호출에 대해 거부하는 것처럼 게시된 포트의 연결도 거부합니다. 반면에 포워딩된 포트는 실제로 애플리케이션에 localhost처럼 보입니다. 각 포트는 상황에 따라 유용할 수 있습니다.

포트를 게시하려면 다음을 수행할 수 있습니다.

appPort 속성 사용: devcontainer.json에서 이미지 또는 Dockerfile을 참조하는 경우 appPort 속성을 사용하여 호스트에 포트를 게시할 수 있습니다.
```
"appPort": [ 3000, "8921:5000" ]
```
Docker Compose 포트 매핑 사용: 포트 매핑을 docker-compose.yml 파일에 쉽게 추가하여 추가 포트를 게시할 수 있습니다.
```
ports:
- "3000"
- "8921:5000"
```

각 경우에 설정이 적용되려면 컨테이너를 다시 빌드해야 합니다. 컨테이너에 연결되어 있을 때 명령 팔레트(F1)에서 Dev Containers: 컨테이너 다시 빌드 명령을 실행하여 이를 수행할 수 있습니다.

터미널 열기

VS Code에서 컨테이너의 터미널을 여는 것은 간단합니다. 컨테이너에서 폴더를 연 후 VS Code에서 여는 **모든 터미널 창**(터미널 > 새 터미널)은 로컬이 아닌 컨테이너에서 자동으로 실행됩니다.

또한 이 동일한 터미널 창에서 code 명령줄을 사용하여 새 파일 또는 폴더를 컨테이너에 열기와 같은 여러 작업을 수행할 수 있습니다. 명령줄에서 사용할 수 있는 옵션을 알아보려면 code --help를 입력하십시오.

Using the code CLI

컨테이너에서 디버깅

컨테이너에서 폴더를 연 후에는 로컬에서 애플리케이션을 실행할 때와 동일한 방식으로 VS Code 디버거를 사용할 수 있습니다. 예를 들어, launch.json에서 실행 구성을 선택하고 디버깅을 시작하면(F5), 애플리케이션이 원격 호스트에서 시작되고 디버거가 연결됩니다.

.vscode/launch.json에서 VS Code의 디버깅 기능을 구성하는 자세한 내용은 디버깅 문서를 참조하십시오.

컨테이너별 설정

VS Code의 로컬 사용자 설정도 dev 컨테이너에 연결될 때 재사용됩니다. 이렇게 하면 사용자 경험이 일관되게 유지되지만, 로컬 컴퓨터와 각 컨테이너 간에 일부 설정을 다르게 하고 싶을 수 있습니다. 다행히 컨테이너에 연결된 후에는 명령 팔레트(F1)에서 환경 설정: 원격 설정 열기 명령을 실행하거나 설정 편집기에서 원격 탭을 선택하여 컨테이너별 설정을 지정할 수 있습니다. 이러한 설정은 컨테이너에 연결할 때 적용되는 모든 로컬 설정을 재정의합니다.

Container specific settings tab

기본 컨테이너별 설정

devcontainer.json에서 settings 속성을 사용하여 컨테이너별 설정의 기본값을 포함할 수 있습니다. 이러한 값은 컨테이너가 생성된 후 컨테이너 내부의 컨테이너별 설정 파일에 자동으로 배치됩니다.

예를 들어, .devcontainer/devcontainer.json에 이를 추가하면 Java 홈 경로가 설정됩니다.

// Configure tool-specific properties.
"customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
        "settings": {
            "java.home": "/docker-java-home"
        }
    }
}

이것은 기본값만 설정하므로 컨테이너가 생성된 후에도 필요한 대로 설정을 변경할 수 있습니다.

컨테이너 관리

기본적으로 Dev Containers 확장은 폴더를 열 때 devcontainer.json에 언급된 컨테이너를 자동으로 시작합니다. VS Code를 닫으면 확장은 연결된 컨테이너를 자동으로 종료합니다. devcontainer.json에 "shutdownAction": "none"을 추가하여 이 동작을 변경할 수 있습니다.

명령줄을 사용하여 컨테이너를 관리할 수 있지만, 원격 탐색기를 사용할 수도 있습니다. 컨테이너를 중지하려면 드롭다운(있는 경우)에서 컨테이너를 선택하고 실행 중인 컨테이너를 마우스 오른쪽 버튼으로 클릭한 다음 컨테이너 중지를 선택합니다. 또한 종료된 컨테이너를 시작하고, 컨테이너를 제거하고, 최근 폴더를 제거할 수 있습니다. 세부 정보 보기에서 포트를 포워딩하고 이미 포워딩된 포트를 브라우저에서 열 수 있습니다.

Containers Explorer screenshot

사용하지 않는 이미지 정리 또는 컨테이너 대량 삭제에 대해서는 다른 옵션에 대해 사용하지 않는 컨테이너 및 이미지 정리를 참조하십시오.

점 파일 리포지토리로 개인화

Dotfiles는 파일 이름이 점(.)으로 시작하고 일반적으로 다양한 응용 프로그램에 대한 구성 정보를 포함하는 파일입니다. 개발 컨테이너는 다양한 유형의 응용 프로그램을 포함할 수 있으므로 이러한 파일을 저장해 두면 컨테이너가 시작되고 실행되면 쉽게 복사할 수 있습니다.

이를 수행하는 일반적인 방법은 이러한 dotfiles를 GitHub 리포지토리에 저장한 다음 유틸리티를 사용하여 복제하고 적용하는 것입니다. Dev Containers 확장은 자체 컨테이너와 함께 이를 사용하는 데 대한 기본 지원을 제공합니다. 이 아이디어가 처음이라면, 존재하는 다양한 dotfiles 부트스트랩 리포지토리를 살펴보십시오.

사용하려면 dotfiles GitHub 리포지토리를 VS Code의 사용자 설정(⌘, (Windows, Linux Ctrl+,))에 다음과 같이 추가합니다.

Settings for dotfiles

또는 settings.json에서

{
  "dotfiles.repository": "your-github-id/your-dotfiles-repo",
  "dotfiles.targetPath": "~/dotfiles",
  "dotfiles.installCommand": "install.sh"
}

이 시점부터 dotfiles 리포지토리는 컨테이너가 생성될 때마다 사용됩니다.

알려진 제한 사항

Dev Containers 제한 사항

Windows 컨테이너 이미지는 **지원되지 않습니다**.
멀티 루트 작업 영역의 모든 루트/폴더는 하위 수준에 구성 파일이 있는지 여부에 관계없이 동일한 컨테이너에서 열립니다.
Linux의 비공식 Ubuntu Docker **snap** 패키지는 **지원되지 않습니다**. 배포판에 대한 공식 Docker 설치 지침을 따르십시오.
Windows의 Docker Toolbox는 지원되지 않습니다.
SSH를 사용하여 Git 저장소를 복제하고 SSH 키에 암호가 있는 경우, 원격에서 실행할 때 VS Code의 끌어오기 및 동기화 기능이 멈출 수 있습니다. 암호 없는 SSH 키를 사용하거나 HTTPS를 사용하여 복제하거나, 명령줄에서 git push를 실행하여 이 문제를 해결하십시오.
로컬 프록시 설정은 컨테이너 내에서 재사용되지 않으므로 적절한 프록시 정보(예: 적절한 프록시 정보가 포함된 전역 HTTP_PROXY 또는 HTTPS_PROXY 환경 변수)가 구성되지 않으면 확장이 작동하지 않을 수 있습니다.
Windows의 OpenSSH 버전과 8.8 이하 버전의 ssh-agent가 실행되고 SSH 클라이언트(모든 플랫폼)가 8.9 이상의 버전으로 실행될 때 호환성 문제가 있습니다. 해결 방법은 winget 또는 Win32-OpenSSH/releases의 설치 프로그램을 사용하여 Windows의 OpenSSH를 8.9 이상으로 업그레이드하는 것입니다. (ssh-add -l은 올바르게 작동하지만 ssh <ssh-server>는 <ssh-server>: Permission denied (publickey)와 함께 실패합니다. 이 문제는 SSH를 사용하여 리포지토리에 연결할 때 Git에도 영향을 미칩니다.)

컨테이너와 관련된 활성 문제 목록은 여기를 참조하십시오.

Docker 제한 사항

더 많은 정보는 Windows 또는 Mac에 대한 Docker 문제 해결 가이드를 참조하십시오.

컨테이너 도구 확장 제한 사항

WSL, 원격 - 터널 또는 원격 - SSH 창에서 컨테이너 도구 또는 Kubernetes 확장을 사용하는 경우, 컨테이너 탐색기 또는 Kubernetes 보기에서 **Visual Studio Code 연결** 컨텍스트 메뉴 작업을 사용하면 사용 가능한 컨테이너 중에서 다시 선택하라는 메시지가 표시됩니다.

확장 제한 사항

이 시점에서 대부분의 확장은 수정 없이 Dev Containers에서 작동합니다. 그러나 특정 기능에 따라 변경이 필요할 수 있습니다. 확장 문제를 겪는 경우, 문제를 보고할 때 확장 작성자에게 언급할 수 있는 일반적인 문제 및 해결 방법 요약은 여기를 참조하십시오.

또한 Alpine 지원은 가능하지만, 확장 내부의 네이티브 코드에 있는 glibc 종속성으로 인해 컨테이너에 설치된 일부 확장이 작동하지 않을 수 있습니다. 자세한 내용은 Linux와 함께 원격 개발 문서를 참조하십시오.

고급 컨테이너 구성

다음 주제에 대한 정보는 고급 컨테이너 구성 문서를 참조하십시오.

devcontainer.json 참조

개발 컨테이너를 사용자 지정하고 실행 중인 컨테이너에 연결하는 방법을 제어하는 데 도움이 되는 파일 스키마를 검토할 수 있는 완전한 devcontainer.json 참조가 있습니다.

질문 또는 피드백

팁 및 요령 또는 FAQ를 참조하십시오.
Stack Overflow에서 검색하십시오.
기능 요청을 추가하거나 문제 보고를 하십시오.
다른 사람들이 사용할 수 있는 Dev Container 템플릿 또는 기능을 만드십시오.
개발 컨테이너 사양에 대한 검토 및 피드백 제공
문서 또는 VS Code 자체에 기여하십시오.
자세한 내용은 CONTRIBUTING 가이드를 참조하십시오.

문제 해결

파일을 쓸 수 없음 (권한 없음 (FileSystemError))

다음 구성에서 dev 컨테이너를 실행할 때 이 문제가 발생할 수 있습니다.

Docker Desktop에서 WSL(Windows Subsystem for Linux) 백엔드로 실행
향상된 컨테이너 격리(ECI) 활성화

잠재적인 해결 방법은 이슈 #8278을 확인하십시오.

다음 단계

실행 중인 컨테이너에 연결 - 이미 실행 중인 Docker 컨테이너에 연결합니다.
개발 컨테이너 만들기 - 작업 환경을 위한 사용자 지정 컨테이너를 만듭니다.
고급 컨테이너 - 고급 컨테이너 시나리오에 대한 솔루션을 찾습니다.
devcontainer.json 참조 - devcontainer.json 스키마를 검토합니다.

12/10/2025