Dev Containers 팁 및 요령

이 문서는 Dev Containers 확장을 다양한 환경에서 설정하고 실행하는 데 도움이 되는 몇 가지 팁과 요령을 포함합니다.

Docker 설치를 위한 대안 방법

Dev Containers 확장과 Docker를 사용하는 데는 다음과 같은 몇 가지 방법이 있습니다.

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

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

AI 채팅 응답 사용자 지정

사용자 지정 지침을 사용하면 일반적인 가이드라인이나 규칙을 설명하여 특정 코딩 관행 및 기술 스택에 맞는 응답을 얻을 수 있습니다.

Dev containers에서 사용자 지정 지침을 사용하여 Copilot에 연결된 Dev container 유형(설치된 언어 또는 툴체인 종류 등)에 대한 더 많은 정보를 제공할 수 있습니다. 이는 몇 가지 방법으로 달성할 수 있습니다.

devcontainer.json에 "github.copilot.chat.codeGeneration.instructions"를 직접 추가
- Dev container 생성 및 연결 프로세스를 더욱 쉽게 만들기 위해 이미지 및 기능과 같은 Dev container 리소스를 게시하며, 이제 이러한 파일에 사용자 지정 지침을 포함했습니다.
- Python 기능의 사용자 지정 지침 예시는 여기에 있습니다.
copilot-instructions.md 파일을 로컬에서와 동일하게 사용

Windows용 Docker Desktop 팁

Docker Desktop for Windows는 대부분의 설정에서 잘 작동하지만, 문제가 발생할 수 있는 몇 가지 "주의할 점"이 있습니다. 다음은 이러한 문제들을 피하기 위한 몇 가지 팁입니다.

Windows 10 (2004 이상)에서 새로운 Docker WSL 2 백엔드 사용을 고려하십시오. Docker Desktop의 WSL 2 백엔드를 사용하고 있다면, WSL 내의 폴더뿐만 아니라 로컬 폴더도 열 수 있습니다. 컨테이너는 Windows와 WSL 내부에서 공유되며, 이 새로운 엔진은 파일 공유 문제에 덜 민감합니다. 자세한 내용은 빠른 시작을 참조하십시오.
"Windows의 Linux 컨테이너 (LCOW)" 모드에서 전환하십시오. 기본적으로 비활성화되어 있지만, 최신 버전의 Docker는 Windows의 Linux 컨테이너 (LCOW)를 지원하여 Windows 및 Linux 컨테이너를 동시에 사용할 수 있습니다. 그러나 이는 새로운 기능이므로 문제가 발생할 수 있으며 Dev Containers 확장은 현재 Linux 컨테이너만 지원합니다. Docker 작업 표시줄 항목을 마우스 오른쪽 버튼으로 클릭하고 컨텍스트 메뉴에서 **Linux 컨테이너로 전환...**을 선택하여 언제든지 LCOW 모드에서 전환할 수 있습니다.
방화벽이 Docker가 공유 드라이브를 설정하도록 허용하는지 확인하십시오. Docker는 두 개의 머신 로컬 IP 간에만 연결하면 되지만, 일부 방화벽 소프트웨어는 여전히 모든 드라이브 공유 또는 필요한 포트를 차단할 수 있습니다.

이전 버전의 Docker for Windows에 적용되었지만 이제는 해결되었을 팁입니다. 가능한 회귀로 인해 이상한 동작이 발생하는 경우, 이러한 팁은 과거에 문제를 해결했습니다.

드라이브를 공유할 때 AD 도메인 계정 또는 로컬 관리자 계정을 사용하십시오. AAD (이메일 기반) 계정은 사용하지 마십시오. AAD (이메일 기반) 계정은 Docker 이슈 #132 및 이슈 #1352에 문서화된 것처럼 알려진 문제가 있습니다. AAD 계정을 반드시 사용해야 하는 경우, 머신에 별도의 로컬 관리자 계정을 만들어 드라이브 공유 목적으로만 사용하십시오. 이 블로그 게시물의 단계를 따라 모든 것을 설정하십시오.
드라이브 공유 문제를 피하기 위해 영숫자 비밀번호를 사용하십시오. Windows에서 드라이브를 공유하라는 메시지가 표시되면, 머신에서 관리자 권한이 있는 계정의 사용자 이름과 비밀번호를 입력하라는 메시지가 표시됩니다. 잘못된 사용자 이름 또는 비밀번호에 대한 경고가 표시되면, 비밀번호에 특수 문자가 포함되어 있기 때문일 수 있습니다. 예를 들어, !, [ 및 ]는 문제가 발생하는 것으로 알려져 있습니다. 영숫자 문자로 비밀번호를 변경하여 해결하십시오. 자세한 내용은 Docker 볼륨 마운트 문제에 대한 이 이슈를 참조하십시오.
Docker에 로그인할 때 이메일이 아닌 Docker ID를 사용하십시오. Docker CLI는 Docker ID만 지원하므로 이메일을 사용하면 문제가 발생할 수 있습니다. 자세한 내용은 Docker 이슈 #935를 참조하십시오.

문제가 계속되면 Docker Desktop for Windows 문제 해결 가이드를 참조하십시오.

VS Code Dev Containers 확장은 소스 코드가 Docker와 공유된 폴더 또는 드라이브에 있는 경우에만 컨테이너에 자동으로 마운트할 수 있습니다. 공유되지 않은 위치에서 Dev container를 열면 컨테이너는 성공적으로 시작되지만 작업 영역은 비어 있게 됩니다.

이 단계는 Docker Desktop의 WSL 2 엔진에는 **필요하지 않습니다**.

Docker의 드라이브 및 폴더 공유 설정 변경 방법

Windows

Docker 작업 표시줄 항목을 마우스 오른쪽 버튼으로 클릭하고 **설정**을 선택합니다.
리소스 > 파일 공유로 이동하여 소스 코드가 있는 드라이브를 확인합니다.
로컬 방화벽이 공유 작업을 차단하고 있다는 메시지가 표시되면, 다음 단계를 위해 이 Docker KB 문서를 참조하십시오.

macOS

Docker 메뉴 표시줄 항목을 클릭하고 **기본 설정**을 선택합니다.
리소스 > 파일 공유로 이동합니다. 소스 코드가 포함된 폴더가 나열된 공유 폴더 중 하나 아래에 있는지 확인합니다.

컨테이너에서 Git 줄 끝 문제 해결 (수정된 파일 다수 발생)

Windows와 Linux는 기본 줄 끝 문자가 다르기 때문에, Git은 줄 끝 문자만 다른 수정된 파일이 많다고 보고할 수 있습니다. 이를 방지하기 위해 .gitattributes 파일을 사용하거나 Windows 측에서 전역적으로 줄 끝 변환을 비활성화할 수 있습니다.

일반적으로 저장소에 .gitattributes 파일을 추가하거나 수정하는 것이 이 문제를 해결하는 가장 안정적인 방법입니다. 이 파일을 소스 제어에 커밋하면 다른 사람들에게 도움이 되고 저장소별로 동작을 다르게 지정할 수 있습니다. 예를 들어, 저장소 루트에 .gitattributes 파일에 다음을 추가하면 Windows 배치 파일(CRLF 필요)을 제외한 모든 것이 LF로 강제됩니다.

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

이 기능은 **Git v2.10+**에서 작동하므로 문제가 발생하는 경우 최신 Git 클라이언트를 설치했는지 확인하십시오. 저장소에서 CRLF가 필요한 다른 파일 유형도 이와 동일한 파일에 추가할 수 있습니다.

여전히 Unix 스타일 줄 끝 (LF)을 항상 업로드하도록 하려면 input 옵션을 사용할 수 있습니다.

git config --global core.autocrlf input

줄 끝 변환을 완전히 비활성화하려면 대신 다음을 실행하십시오.

git config --global core.autocrlf false

마지막으로, 이러한 설정이 적용되려면 저장소를 다시 복제해야 할 수 있습니다.

Docker Compose 사용 시 컨테이너에 Git 설정 방지

이 문제를 해결하는 방법에 대한 정보는 메인 컨테이너 문서의 컨테이너와 Git 자격 증명 공유를 참조하십시오.

컨테이너에서 Git 푸시 또는 동기화 시 중단 문제 해결

SSH를 사용하여 Git 저장소를 복제하고 SSH 키에 암호가 있는 경우, 원격에서 실행할 때 VS Code의 풀 및 동기화 기능이 중단될 수 있습니다.

암호가 없는 SSH 키를 사용하거나, HTTPS를 사용하여 복제하거나, 문제 해결을 위해 명령줄에서 git push를 실행하십시오.

누락된 Linux 종속성 오류 해결

일부 확장은 특정 Docker 이미지에서 찾을 수 없는 라이브러리에 의존합니다. 이 문제를 해결하기 위한 몇 가지 옵션은 컨테이너 문서를 참조하십시오.

Docker Desktop에서 컨테이너 속도 향상

기본적으로 Docker Desktop은 컨테이너에 머신 용량의 일부만 제공합니다. 대부분의 경우 이것으로 충분하지만, 더 많은 용량이 필요한 작업을 수행하는 경우 메모리, CPU 또는 디스크 사용량을 늘릴 수 있습니다.

먼저, 더 이상 사용하지 않는 **실행 중인 모든 컨테이너를 중지**하십시오.

이 방법으로 문제가 해결되지 않으면 CPU 사용량이 실제로 문제인지 또는 다른 문제가 있는지 확인해 볼 수 있습니다. 이를 확인하는 쉬운 방법은 Resource Monitor 확장을 설치하는 것입니다. 컨테이너에 설치되면 상태 표시줄에서 컨테이너 용량에 대한 정보를 제공합니다.

Resource use Status bar

이 확장이 항상 설치되도록 하려면 settings.json에 다음을 추가하십시오.

"dev.containers.defaultExtensions": [
    "mutantdino.resourcemonitor"
]

컨테이너에 더 많은 머신 용량을 할당해야 한다고 판단되면 다음 단계를 따르십시오.

Docker 작업 표시줄 항목을 마우스 오른쪽 버튼으로 클릭하고 **설정** / **기본 설정**을 선택합니다.
고급으로 이동하여 CPU, 메모리 또는 스왑을 늘립니다.
macOS에서는 **디스크**로 이동하여 Docker가 머신에서 사용할 수 있는 디스크 양을 늘립니다. Windows에서는 다른 설정과 함께 고급 아래에 있습니다.

마지막으로, 컨테이너가 **디스크 집약적인 작업**을 수행하거나 단순히 더 빠른 응답 시간을 찾고 있다면, 팁은 컨테이너 디스크 성능 향상을 참조하십시오. VS Code의 기본값은 편의성과 보편적인 지원을 위해 최적화되어 있지만 최적화될 수 있습니다.

사용하지 않는 컨테이너 및 이미지 정리

Docker가 디스크 공간 부족 오류를 보고하는 경우, 일반적으로 사용하지 않는 컨테이너와 이미지를 정리하여 해결할 수 있습니다. 몇 가지 방법이 있습니다.

옵션 1: 원격 탐색기 사용

**원격 탐색기**를 선택하고 제거하려는 컨테이너를 마우스 오른쪽 버튼으로 클릭한 다음 **컨테이너 제거**를 선택하여 컨테이너를 삭제할 수 있습니다.

Remote Explorer screenshot

그러나 이렇게 하면 다운로드한 이미지는 정리되지 않아 시스템을 복잡하게 만들 수 있습니다.

옵션 2: 컨테이너 도구 확장 사용

VS Code에서 **로컬** 창을 엽니다 (**파일 > 새 창**).
아직 설치되지 않았다면, 확장 보기에서 컨테이너 도구 확장을 설치합니다.
그런 다음 컨테이너 탐색기로 이동하여 **컨테이너** 또는 **이미지** 노드를 확장하고, 마우스 오른쪽 버튼을 클릭하고 **컨테이너/이미지 제거**를 선택할 수 있습니다.

옵션 3: Docker CLI를 사용하여 컨테이너 삭제 선택

**로컬** 터미널/명령 프롬프트를 열거나 (VS Code에서 로컬 창 사용).
모든 컨테이너 목록을 보려면 docker ps -a를 입력합니다.
이 목록에서 docker rm <Container ID>를 입력하여 컨테이너를 제거합니다.
사용하지 않는 이미지를 제거하려면 docker image prune을 입력합니다.

docker ps가 삭제하려는 컨테이너를 식별하기에 충분한 정보를 제공하지 않으면 다음 명령을 통해 VS Code에서 관리하는 모든 개발 컨테이너와 이를 생성하는 데 사용된 폴더를 나열합니다.

docker ps -a --filter="label=vsch.quality" --format "table {{.ID}}\t{{.Status}}\t{{.Image}}\tvscode-{{.Label \"vsch.quality\"}}\t{{.Label \"vsch.local.folder\"}}"

옵션 4: Docker Compose 사용

**로컬** 터미널/명령 프롬프트를 열거나 (VS Code에서 로컬 창 사용).
docker-compose.yml 파일이 있는 디렉토리로 이동합니다.
docker-compose down을 입력하여 컨테이너를 중지하고 삭제합니다. 두 개 이상의 Docker Compose 파일이 있는 경우, -f 인수를 사용하여 추가 Docker Compose 파일을 지정할 수 있습니다.

옵션 4: 실행 중이 아닌 모든 컨테이너 및 이미지 삭제

**로컬** 터미널/명령 프롬프트를 열거나 (VS Code에서 로컬 창 사용).
docker system prune --all을 입력합니다.

Debian 8을 사용하는 이미지의 Dockerfile 빌드 실패 해결

Debian 8/Jessie 기반 이미지(예: 오래된 버전의 node:8 이미지)를 사용하는 컨테이너를 빌드할 때 다음과 같은 오류가 발생할 수 있습니다.

...
W: Failed to fetch http://deb.debian.org/debian/dists/jessie-updates/InRelease  Unable to find expected entry 'main/binary-amd64/Packages' in Release file (Wrong sources.list entry or malformed file)
E: Some index files failed to download. They have been ignored, or old ones used instead.
...

이것은 Debian 8이 "보관"되었기 때문에 발생하는 알려진 문제입니다. 이미지의 최신 버전은 일반적으로 이 문제를 해결하며, 종종 Debian 9/Stretch로 업그레이드하는 것을 통해 해결됩니다.

이 오류를 해결하는 두 가지 방법이 있습니다.

옵션 1: 이미지에 종속된 모든 컨테이너를 제거하고, 이미지를 제거한 다음, 다시 빌드하십시오. 그러면 문제가 없는 업데이트된 이미지가 다운로드될 것입니다. 자세한 내용은 사용하지 않는 컨테이너 및 이미지 정리를 참조하십시오.

옵션 2: 컨테이너나 이미지를 삭제하고 싶지 않다면, apt 또는 apt-get 명령 전에 Dockerfile에 이 줄을 추가하십시오. Jessie에 필요한 소스 목록을 추가합니다.

# Add archived sources to source list if base image uses Debian 8 / Jessie
RUN cat /etc/*-release | grep -q jessie && printf "deb http://archive.debian.org/debian/ jessie main\ndeb-src http://archive.debian.org/debian/ jessie main\ndeb http://security.debian.org jessie/updates main\ndeb-src http://security.debian.org jessie/updates main" > /etc/apt/sources.list

Docker CLI는 Docker ID만 지원하므로 이메일을 사용하여 로그인하면 문제가 발생할 수 있습니다. 자세한 내용은 Docker 이슈 #935를 참조하십시오.

해결 방법으로, 이메일 대신 Docker ID를 사용하여 Docker에 로그인하십시오.

macOS에서 Hyperkit의 높은 CPU 사용량

Mac용 Docker에는 높은 CPU 스파이크를 유발할 수 있는 알려진 문제가 있습니다. 특히 파일을 감시하고 빌드할 때 높은 CPU 사용량이 발생합니다. 개발 컨테이너에서는 거의 아무것도 하지 않고 있는데도 활동 모니터에서 com.docker.hyperkit에 대한 높은 CPU 사용량이 표시된다면 이 문제일 가능성이 높습니다. 업데이트 및 수정 사항은 Docker 이슈를 따르십시오.

SSH 터널을 사용하여 원격 Docker 호스트에 연결

원격 Docker 머신 또는 SSH 호스트에서 컨테이너 내부 개발 문서는 원격 Docker 호스트와 함께 작업할 때 VS Code를 설정하는 방법을 다룹니다. 이는 종종 settings.json의 컨테이너 도구 확장 containers.environment 속성을 ssh:// 또는 tcp:// URI로 설정하는 것만큼 간단합니다.

그러나 SSH 구성 복잡성 또는 기타 제한 사항으로 인해 환경에서 이 기능이 작동하지 않는 상황이 발생할 수 있습니다. 이 경우 SSH 터널을 대체 옵션으로 사용할 수 있습니다.

SSH 터널을 대체 옵션으로 사용

SSH 터널을 설정하고 원격 호스트의 Docker 소켓을 로컬 머신으로 포워딩할 수 있습니다.

다음 단계를 따르세요.

OpenSSH 호환 SSH 클라이언트를 설치하십시오.
사용자 또는 작업 영역 settings.json에서 컨테이너 도구 확장 containers.environment 속성을 다음과 같이 업데이트하십시오.
```
"containers.environment": {
    "DOCKER_HOST": "tcp://:23750"
}
```
로컬 터미널/PowerShell에서 다음 명령을 실행하십시오 (user@hostname을 원격 사용자 및 서버의 호스트 이름/IP로 바꾸십시오).
```
ssh -NL localhost:23750:/var/run/docker.sock user@hostname
```

이제 VS Code는 원격 호스트에서 **실행 중인 모든 컨테이너에 연결**할 수 있습니다. 또한 특수한 로컬 devcontainer.json 파일을 사용하여 원격 Dev container를 생성/연결할 수도 있습니다.

완료되면 터미널/PowerShell에서 Ctrl+C를 눌러 터널을 닫으십시오.

참고: ssh 명령이 실패하면 SSH 호스트에서 AllowStreamLocalForwarding을 활성화해야 할 수 있습니다.

SSH 호스트 (로컬 아님)에서 편집기(Vim, nano 또는 Pico 등)로 /etc/ssh/sshd_config를 엽니다.

AllowStreamLocalForwarding yes 설정을 추가합니다.

SSH 서버를 다시 시작합니다 (Ubuntu의 경우 sudo systemctl restart sshd 실행).

다시 시도하십시오.

사용자 프로필 유지

mounts 속성을 사용하여 Dev container에서 쉘 기록과 같은 사용자 프로필을 다시 빌드할 때마다 유지할 수 있습니다.

    "mounts": [
        "source=profile,target=/root,type=volume",
        "target=/root/.vscode-server,type=volume"
    ],

위 코드는 먼저 /root에 마운트된 profile이라는 명명된 볼륨을 생성하여 다시 빌드 후에도 유지됩니다. 다음으로 /root/.vscode-server에 마운트된 익명 볼륨을 생성하여 다시 빌드 시 파기되며, 이를 통해 VS Code가 확장 및 dotfiles를 다시 설치할 수 있습니다.

고급 컨테이너 구성 팁

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

확장 팁

많은 확장이 수정 없이 작동하지만, 일부 기능이 예상대로 작동하지 못하게 하는 몇 가지 문제가 있을 수 있습니다. 어떤 경우에는 다른 명령을 사용하여 문제를 해결할 수 있으며, 다른 경우에는 확장을 수정해야 할 수 있습니다. 원격 확장 팁 섹션에서는 일반적인 문제에 대한 빠른 참조와 해결 팁을 제공합니다. 또한 원격 확장을 지원하도록 확장을 수정하는 방법에 대한 자세한 가이드는 원격 개발 지원에 대한 메인 확장 문서를 참조할 수 있습니다.

질문 및 피드백

문제 보고

Dev Containers 확장으로 문제가 발생하는 경우, 문제를 진단하는 데 도움이 되도록 올바른 로그를 수집하는 것이 중요합니다. Dev Containers: Show Container Log를 사용하여 Dev Containers 확장 로그를 가져올 수 있습니다.

다른 확장 프로그램을 원격으로 사용하는 데 문제가 있는 경우 (예: 다른 확장 프로그램이 원격 컨텍스트에 제대로 로드되거나 설치되지 않는 경우), **원격 확장 호스트** 출력 채널 (**출력: 출력 보기로 포커스**)에서 로그를 가져와 드롭다운에서 **로그 (원격 확장 호스트)**를 선택하면 도움이 됩니다.

참고: **로그 (확장 호스트)**만 보이는 경우, 이것은 로컬 확장 호스트이며 원격 확장 호스트가 시작되지 않은 것입니다. 로그 채널은 로그 파일이 생성된 후에만 생성되므로, 원격 확장 호스트가 시작되지 않으면 원격 확장 호스트 로그 파일이 생성되지 않아 출력 보기에서 표시되지 않습니다. 이 정보도 이슈에 포함하는 것이 유용합니다.

원격 질문 및 피드백 리소스

다른 다양한 원격 리소스가 있습니다.

Stack Overflow에서 검색하십시오.
기능 요청을 추가하거나 문제 보고를 하십시오.

12/10/2025