윈도우에서 WSL2 설치부터 VS Code 연동, 최적화까지 환경 구축법

윈도우에서 WSL2를 설치하고 VS Code와 연동해 안정적이고 빠른 리눅스 개발환경을 만드는 과정입니다. 보안관점 가이드·점검포인트, 최적화(.wslconfig / wsl.conf), 트러블슈팅, AI 코드 도우미 활용 포함합니다.

빠른 시작(권장 순서)

1. 관리자 PowerShell 열기
   시작 → “PowerShell” → 우클릭 “관리자 권한으로 실행”.
2. WSL2 설치 & 기본버전 지정

   wsl --install
   wsl --set-default-version 2

   • 배포판을 지정하려면

     wsl --list --online
     wsl --install -d Ubuntu-22.04

3. 최초 실행 & 계정 생성
   시작 메뉴에서 “Ubuntu” 실행 → 사용자/비번 설정 → 패키지 업데이트

   sudo apt update && sudo apt full-upgrade -y

4. VS Code 설치 & WSL 확장 설치
   • VS Code 실행 → 확장(Blocks 아이콘) → “WSL” 또는 “Remote - WSL” 설치
   • 명령 팔레트(CTRL+SHIFT+P) → WSL: New Window 또는 Connect to WSL
   • WSL 터미널에서 현재 폴더를 VS Code로 열기

     code .

   • 하단 좌측 초록바에 WSL: Ubuntu-22.04 표기되면 연결 완료.

필수/추천 개발 패키지 설치 예시

# 필수 빌드/도구
sudo apt install -y build-essential git curl unzip ca-certificates pkg-config

# Python
sudo apt install -y python3 python3-pip python3-venv pipx
pipx ensurepath

# Node.js (nvm)
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 새 셸에서:
nvm install --lts
node -v && npm -v

# Git 기본 설정
git config --global user.name  "Your Name"
git config --global user.email "you@example.com"

# (선택) GitHub CLI
type -p gh >/dev/null || sudo apt install -y gh

성능 최적화: .wslconfig (Windows 측 자원 제한)

위치: %USERPROFILE%\.wslconfig (예: C:\Users\계정\.wslconfig)
변경 후 wsl --shutdown 해야 적용됩니다.

[wsl2]
memory=6GB               # WSL이 쓸 최대 RAM
processors=4             # 할당 CPU 코어 수
swap=4GB                 # 스왑 크기
localhostForwarding=true # Windows↔WSL 로컬 포트 포워딩

권장값 가이드

• 노트북(16GB RAM): memory=4~8GB, processors=2~6, swap=2~8GB
• 데스크톱(32GB+): memory=8~16GB, processors=4~12, swap=4~16GB
• 개발 규모/동시 작업(BE+FE+DB+Docker)에 따라 상향 조절

리눅스 측 파인튜닝: /etc/wsl.conf

위치: WSL 내부 /etc/wsl.conf
변경 후 Windows에서 wsl --shutdown → 재시작

[automount]
enabled = true
mountFsTab = false
options = "metadata,umask=022,fmask=011"
# metadata: DrvFs 권한 메타데이터 사용
# umask/fmask: 기본 권한을 개발에 맞게 조정

[network]
generateResolvConf = true
# (사내 DNS 고정 필요 시 false로 바꾸고 /etc/resolv.conf 수동관리)

[interop]
enabled = true
appendWindowsPath = false
# Windows PATH 과다 노출 방지(충돌/성능 이슈 완화)

성능 팁

• 작업 폴더는 /home/…(WSL ext4)에 두세요.
  /mnt/c에서 빌드/패키지 설치 시 I/O 느림 + 권한 이슈 발생 가능.
• 대용량 의존성 캐시(npm/pip 등)도 WSL 내부 디스크에 유지.
• 백신/실시간 검사에서 WSL VHDX 폴더 제외(사내 정책 허용 시) → I/O 향상.

300x250

VS Code + WSL 사용 패턴

1. WSL에서 프로젝트 클론

   cd ~
   git clone https://github.com/org/repo.git
   cd repo
   code .

2. 확장 설치(WSL 전용)
   Python, ESLint, GitLens 등 → 확장 패널에서 “Install in WSL: Ubuntu-22.04” 버튼으로 WSL 환경에 별도 설치.
3. 디버깅/터미널
   통합 터미널이 자동으로 WSL 쉘을 사용. 런/디버그 구성은 .vscode/launch.json.

Docker 선택지

• Docker Desktop + WSL2 백엔드(간편)
  • Docker Desktop 설치 → Settings → “Use the WSL 2 based engine” 체크 → 대상 배포판 Enable
• WSL 내부에 Docker Engine 직접 설치(가벼움)

  # Ubuntu 공식 문서에 따라 설치
  sudo groupadd docker 2>/dev/null || true
  sudo usermod -aG docker $USER
  newgrp docker
  docker run hello-world

• 내부 정책에 따라 선택. Desktop은 GUI·Kubernetes 연동 편리, Engine은 경량.

보안 가이드 점검포인트

1. 패치 레벨
   • sudo apt update && sudo apt full-upgrade -y 주기적 적용
   • 커널/WSL 업데이트: wsl --update, 상태 확인: wsl --status
2. 비밀정보 관리
   • 절대 코드/리포지토리에 키 하드코딩 금지
   • 환경변수/비밀관리자(예: 1Password/Bitwarden/GitHub Secrets) 사용
   • Windows와 공유되는 /mnt/c 경로에 민감자료 저장 자제
3. 포트 노출 통제
   • 리눅스에서 리슨 중인 서비스 확인

     ss -lntp

   • WSL2는 NAT 환경 + 로컬포워딩. 외부 노출 의도 없으면 Windows 방화벽 규칙으로 제한 유지
4. 권한/소유권
   • 프로젝트 권한 점검: find . -type f -perm -o+w 등으로 과도한 권한 탐지
   • DrvFs(윈도 드라이브) 접근 시 metadata 옵션으로 리눅스 권한 유지
5. 프록시/SSL 검증
   • 사내 프록시 사용 시 CA 루트 인증서 신뢰성 구성 → VS Code Server 설치/확장 다운로드 실패 방지
6. 감사·이력
   • Git 서명(commit signing)·원격 저장소 접근 기록, 패키지 해시 검증 사용
   • 업무망 정책과 사용자 교육(비인가 확장 설치 금지, 스니펫 주의)

AI 코드 도우미(예: Copilot or OpenAI 기반 확장)

대체로 GitHub Copilot 또는 OpenAI API를 사용하는 확장을 사용합니다.

• 설치
  • VS Code 확장 → “GitHub Copilot” 또는 OpenAI 기반 “Chat/Code” 확장 설치
• 인증
  • Copilot: GitHub 로그인/라이선스 인증
  • OpenAI 기반 확장: 환경변수 등록을 권장

    # WSL bash/zsh
    export OPENAI_API_KEY="발급_API_키"
    echo 'export OPENAI_API_KEY="발급_API_키"' >> ~/.bashrc

    # Windows PowerShell
    setx OPENAI_API_KEY "발급_API_키"

  • VS Code 재시작 후 확장에서 자동 인식
• 활용 예시
  • 주석으로 요구사항 작성 → 코드 제안/완성
  • “테스트 코드 생성”, “이 함수 리팩터” 등 자연어 프롬프트
• 보안 주의
  • 개인정보·비밀코드 외부 전송 금지 정책 준수(툴의 전송 범위 설정 확인)
  • 저장소별 사용 제한, 프라이빗 리포 기본값 off 검토

유용한 확인/관리 명령 모음

# Windows(관리자)
wsl --install                 # WSL 설치
wsl --list --online           # 설치 가능한 배포판 목록
wsl --list --verbose          # 설치된 배포판/버전
wsl --set-default-version 2   # 기본 버전 = 2
wsl --set-version <배포판> 2  # 특정 배포판을 2로 전환
wsl --status                  # 런타임/커널 상태
wsl --update                  # WSL 커널 업데이트
wsl --shutdown                # 모든 배포판 중지
wsl --export <배포판> D:\backup.tar   # 백업
wsl --import <이름> D:\WSL D:\backup.tar --version 2  # 복원/이관

트러블슈팅(자주 묻는 증상별)

1. VS Code가 “VS Code Server 설치 실패”
   • WSL 내 CA/시간 동기화 확인

     sudo apt install -y ca-certificates
     sudo update-ca-certificates
     timedatectl

   • 사내 프록시 환경변수 설정

     export http_proxy=http://proxy.company:8080
     export https_proxy=http://proxy.company:8080

   • 재시도 전 wsl --shutdown
2. 네트워크/DNS 이슈(패키지 설치 느림/실패)
   • 일시적으로 DNS 고정

     sudo bash -c 'echo "nameserver 1.1.1.1" > /etc/resolv.conf'
     # generateResolvConf=false 설정 시 chattr +i로 고정 가능(운영 주의)

3. 파일 I/O가 너무 느림
   • 작업 폴더를 /home/…로 이동
   • Windows 실시간 검사 예외(정책 허용 시)
   • .wslconfig 메모리/코어 상향
4. Docker가 root만 실행

   sudo usermod -aG docker $USER
   newgrp docker

5. 배포판이 꼬였을 때 최소 복구
   • 백업/복원

     wsl --export Ubuntu D:\ubuntu_backup.tar
     wsl --unregister Ubuntu
     wsl --import Ubuntu D:\WSL D:\ubuntu_backup.tar --version 2

운영 점검 체크리스트

• Windows: 가상화/WSL 기능 on, 최신 업데이트/재부팅
• .wslconfig로 메모리·CPU·스왑 상한 설정, wsl --shutdown 적용
• /etc/wsl.conf로 DrvFs 권한·PATH·DNS 정책 정합성
• 작업 디렉터리는 /home 유지, /mnt/c 빌드 금지
• VS Code 확장 “WSL” 및 필수 확장(WSL 전용 설치)
• 패키지/커널 최신화, 사내 프록시/CA 적용
• 포트/서비스 최소화, Windows 방화벽 규칙 점검
• 비밀정보는 환경변수/비밀관리자, 레포 하드코딩 금지
• AI 도우미 전송 정책 검토(사내용/외부전송 제한)
• 주기적 백업(wsl --export), 사고 시 복구 절차 문서화

배포용 스크립트 골격(예시)

신입 개발자 PC 초기세팅용으로 커스터마이즈하세요.

# Windows(관리자) - install_wsl2.ps1
wsl --install
wsl --set-default-version 2

# .wslconfig 작성
$cfg = @"
[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true
"@
$cfg | Out-File -Encoding utf8 "$env:USERPROFILE\.wslconfig"

wsl --shutdown

# WSL(Ubuntu) - bootstrap.sh
set -euo pipefail
sudo apt update && sudo apt full-upgrade -y
sudo apt install -y build-essential git curl unzip ca-certificates pkg-config \
                    python3 python3-pip python3-venv pipx
pipx ensurepath
# nvm
if ! command -v nvm >/dev/null; then
  curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
fi
source ~/.nvm/nvm.sh && nvm install --lts
git config --global core.autocrlf input
echo "✅ Base setup done"

이 가이드를 따르면 WSL2 설치 → VS Code 연동 → 자원 최적화 → 보안 점검 → 트러블슈팅까지 한 번에 정리됩니다.