윈도우 개발 환경 오류 5단계 총정리 가이드 (Git·WSL2·Docker·VS Code)

윈도우 개발 환경 오류 원인과 핵심 요약

윈도우에서 리눅스 기반 개발 도구(Git, WSL2, Docker, VS Code)를 쓸 때 발생하는 오류는 대부분 호스트 윈도우와 가상화 계층(Hyper-V · WSL2) 사이의 네트워크·가상 머신 충돌이거나, 윈도우 내장 실행 파일과 개발 도구 내장 실행 파일(OpenSSH, PowerShell 프로필)의 경로 불일치 때문입니다. 아래 표에서 지금 막힌 도구를 선택하면 원인을 바로 짚어낼 수 있습니다.

WSL2와 Docker Desktop은 메인보드 BIOS의 **CPU 가상화(Intel VT-x / AMD SVM)**와 윈도우 기능의 **가상 머신 플랫폼(Virtual Machine Platform)**이 둘 다 켜져 있어야 동작합니다. 가상화 계층이 멈췄을 때는 앱 재설치보다 wsl --shutdown 한 줄이 훨씬 빠르고 안전합니다.

---

증상별 바로가기

지금 막힌 개발 도구	대표 오류 메시지 및 증상	바로 갈 곳
Git · GitHub / GitLab	git@github.com: Permission denied (publickey), 다중 계정 SSH 충돌	해결 방법 1
WSL2 설치 · 업데이트	wsl --install 실패, 0x80370102, 0x800701bc, 가상 머신 플랫폼 오류	해결 방법 2
WSL2 네트워크 · DNS	Temporary failure in name resolution, WSL 내부 apt·npm 인터넷 먹통	해결 방법 3
Docker Desktop	Starting the Docker Engine... 무한 로딩, Docker Desktop stopped	해결 방법 4
VS Code · Cursor	단축키(Ctrl + `)를 눌러도 터미널 창이 열리지 않거나 바로 닫힘(종료 코드)	해결 방법 5

---

해결 방법 1: Git SSH Permission denied (publickey) 인증 오류 해결하기

git clone이나 git push를 실행할 때 Permission denied (publickey)가 뜬다면 내 PC의 SSH 클라이언트가 GitHub에 등록된 공개키와 짝이 맞는 개인키를 제시하지 못했다는 뜻입니다.

1. 먼저 PowerShell에서 어떤 키가 제시되고 있는지 디버그 모드로 연결을 시험합니다.

   ssh -vT git@github.com

2. 출력에서 Offering public key 줄이 아예 없다면 키를 생성(ssh-keygen -t ed25519)하거나 윈도우 ssh-agent 서비스를 켜서 키를 등록해야 합니다.

3. 회사 계정과 개인 계정을 한 PC에서 함께 써서 엉뚱한 키가 먼저 제시된다면 ~/.ssh/config 파일에 호스트 별명과 IdentitiesOnly yes를 지정합니다.

4. 터미널에서는 성공하는데 VS Code나 Cursor 안에서만 실패한다면 Git이 윈도우 기본 OpenSSH를 쓰도록 아래 명령을 실행합니다. 단계별 전체 설정은 Git Permission denied (publickey) SSH 키 오류 5단계 해결 가이드에 정리되어 있습니다.

   git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

---

해결 방법 2: WSL2 설치와 업데이트 가상화 오류 해결하기

새 PC에서 wsl --install이나 wsl --update를 실행했을 때 설치가 멈추거나 가상화 관련 오류 코드가 뜨는 경우입니다. Microsoft Learn 공식 WSL 문제 해결 문서 기준 주요 오류 코드별 원인은 아래 표와 같습니다.

WSL 오류 코드	핵심 원인	우선 조치
WslRegisterDistribution failed: 0x80370102	BIOS에서 CPU 가상화(SVM / VT-x) 비활성화 또는 hypervisorlaunchtype 꺼짐	BIOS 가상화 켜기 및 bcdedit /set hypervisorlaunchtype auto 실행
0x800701bc	WSL2 리눅스 커널 패키지 버전 구형 또는 미설치	wsl --update 실행 후 wsl --set-default-version 2 지정
0x80370114 / 설치 멈춤	윈도우 하위 시스템 기능 미체크 또는 다른 드라이브로 새 앱 저장 위치 변경됨	Windows 기능 켜기/끄기에서 가상 머신 플랫폼 체크 및 C 드라이브 저장 확인

1. 작업 관리자 > 성능 > CPU 탭 오른쪽 아래에서 가상화: 사용으로 표시되는지 먼저 확인합니다.

2. **터미널(관리자)**에서 하이퍼바이저 자동 시작을 켜고 WSL 커널을 최신으로 업데이트합니다.

   bcdedit /set hypervisorlaunchtype auto
   wsl --update

3. 설정 후 반드시 윈도우를 재부팅합니다. 오류 코드별 상세 복구 절차는 wsl –install –update 실패 오류 코드별 해결 가이드에서 확인하세요.

---

해결 방법 3: WSL2 인터넷 먹통과 DNS (resolv.conf) 오류 해결하기

호스트 윈도우에서는 웹서핑이 잘 되는데 WSL2 우분투 터미널 안에서만 sudo apt update, git clone, pip install이 Temporary failure in name resolution으로 막히는 현상입니다.

1. 먼저 WSL 터미널에서 IP 통신(ping -c 3 8.8.8.8)과 도메인 통신(ping -c 3 google.com)을 비교합니다. IP는 되는데 도메인만 실패한다면 100% DNS 해석 문제입니다.

2. 윈도우 11 최신 버전(22H2 이상)과 최신 WSL을 쓰고 있다면 사용자 폴더(C:\Users\사용자이름\.wslconfig)에 미러링 네트워크와 DNS 터널링을 켜는 것이 가장 깔끔합니다.

   [wsl2]
   networkingMode=mirrored
   dnsTunneling=true

3. 구형 윈도우 버전이거나 사내 VPN과 충돌한다면 WSL 내부 /etc/wsl.conf에서 generateResolvConf = false로 자동 생성을 막고 /etc/resolv.conf에 직접 DNS 서버를 지정합니다. 두 가지 방법의 상세 절차와 되돌리는 법은 WSL2 인터넷 DNS 안 됨 resolv.conf 5단계 해결 가이드를 참고하세요.

---

해결 방법 4: Docker Desktop 엔진 무한 로딩 복구하기

Docker Desktop을 켰는데 Starting the Docker Engine... 화면에서 영원히 넘어가지 않거나 Docker Desktop stopped...가 뜨는 경우입니다.

1. Docker 프로세스와 WSL2 가상 머신이 뒤엉킨 상태가 가장 흔하므로, PowerShell에서 아래 명령으로 WSL과 배포판 상태를 먼저 확인하고 완전히 내립니다.

   wsl -l -v
   wsl --shutdown

2. 작업 관리자에서 Docker Desktop.exe와 com.docker.backend.exe가 남아 있다면 모두 끝낸 뒤 Docker Desktop을 다시 켭니다.

3. 만약 wsl -l -v 자체가 먹통이거나 docker-desktop-data 배포판이 손상됐다면 우측 상단 벌레 모양(Troubleshoot) 메뉴에서 Clean / Purge data를 실행해 컨테이너 볼륨을 초기화합니다. 단계별 점검 순서와 로밍 설정 파일 정리법은 Docker Desktop Starting the Docker Engine 무한 로딩 해결 가이드에 자세히 나와 있습니다.

Clean / Purge data를 실행하면 로컬 Docker 내부에 저장된 이미지와 컨테이너 볼륨이 모두 삭제됩니다. 데이터베이스 컨테이너에 백업하지 않은 로컬 데이터가 있다면 먼저 WSL 명령어로 컨테이너 파일 시스템을 확인하세요.

---

해결 방법 5: VS Code 통합 터미널 실행 불가 오류 해결하기

VS Code나 Cursor에서 새 터미널을 열었을 때 빈 화면만 멈춰 있거나 The terminal process terminated with exit code 메시지와 함께 즉시 닫히는 경우입니다.

1. Ctrl + Shift + P를 눌러 명령 팔레트를 열고 Terminal: Select Default Profile을 실행해 기본 셸을 **Command Prompt(cmd)**나 Git Bash로 바꾼 뒤 새 터미널이 열리는지 시험합니다.
2. 다른 셸은 열리는데 PowerShell만 안 열린다면 PowerShell 실행 정책이나 시작 프로필($PROFILE) 스크립트 문법 오류가 원인입니다.
3. 모든 셸에서 똑같이 창이 깨지거나 안 열린다면 settings.json에서 깨진 terminal.integrated.defaultProfile.windows 경로를 지우고, GPU 렌더러 충돌을 막기 위해 "terminal.integrated.gpuAcceleration": "off"를 추가합니다. 종료 코드별 원인과 설정 초기화 방법은 VS Code 터미널이 열리지 않음 5단계 해결 가이드에서 다루고 있습니다.

---

문제 해결이 안 될 경우 추가 점검 사항

• 사내 보안 프로그램 및 SSL 인증서 검사(MITM): 회사망에서 자체 루트 인증서로 HTTPS 트래픽을 검사하는 환경에서는 git, pip, npm, docker pull이 모두 SSL 인증서 검증 오류(SSL CERTIFICATE_VERIFY_FAILED 등)로 막힐 수 있습니다. 이 경우 각 도구에 사내 루트 CA 인증서 경로를 등록해야 합니다.
• 서드파티 가상화 도구와의 충돌: 구형 버전의 VirtualBox나 안드로이드 앱플레이어(블루스택·LD플레이어 구버전)가 Hyper-V를 강제로 끄는 스크립트를 실행하면 재부팅 후 WSL2와 Docker가 동시에 작동 불능이 됩니다.
• C 드라이브 여유 공간 확인: WSL2의 가상 디스크(ext4.vhdx)와 Docker 이미지 레이어는 자동으로 용량이 늘어나기만 하고 줄어들지 않아 C 드라이브를 수십 GB씩 차지합니다. docker system prune으로 미사용 이미지를 주기적으로 정리하세요.