Windows 11 개발자 초기 셋업 — 새 PC를 받았을 때 첫 1시간

Windows로 개발한다면 보통 두 갈래다 — (a) WSL2 안에서 Linux로 다 끝낸다, (b) PowerShell + Git Bash로 네이티브 Windows에서 한다. 이 가이드는 둘 다 깔아두고 케이스별로 골라 쓰는 셋업을 목표로 한다. 본업이 Node/Go/Python이라면 WSL2가 압도적으로 편하고, .NET·게임·Tauri·Win32 API는 네이티브가 답이다.

대상은 Windows 11 (22H2 이상) + winget 사용 가능 환경. Windows 10은 동일하게 동작하나 winget 일부 동작이 다를 수 있다.

TL;DR

1. Windows 11 시스템 설정 4개 (Explorer 확장자·숨김 파일, 클립보드 히스토리, 가상 데스크톱 단축키)
2. winget으로 필수 도구 8개 한 줄 설치 (Git, GH CLI, Windows Terminal, PowerShell 7, VS Code, mise, ripgrep, fzf)
3. WSL2 + Ubuntu 24.04 설치 — wsl --install -d Ubuntu-24.04
4. Git 글로벌 설정 + SSH ed25519 키 → GitHub 등록 → gh auth login

사전 조건

• Windows 11 22H2 이상 — winver 명령으로 버전 확인. winget이 기본 포함된 첫 빌드
• 관리자 권한 — WSL2 설치, 일부 winget 패키지 시스템 설치 시 필요
• 인터넷 연결 + Microsoft 계정 (Windows 11 Home은 사실상 필수)
• 하드웨어 가상화 — BIOS/UEFI에서 Intel VT-x 또는 AMD-V 활성화 (WSL2 필수). 보통 기본 ON

확인 방법: systeminfo | findstr /C:"Hyper-V" — "Hyper-V Requirements"가 모두 Yes면 OK.

1. Windows 11 시스템 설정 — 5분

1.1 Explorer — 숨김 파일·확장자·전체 경로 표시

Win + E로 Explorer를 열고 View → Show → File name extensions + Hidden items 둘 다 체크. 또는 PowerShell에서 한 번에:

# 확장자 + 숨김 파일 표시
Set-ItemProperty -Path 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced' -Name HideFileExt -Value 0
Set-ItemProperty -Path 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced' -Name Hidden -Value 1
# Explorer 재시작으로 즉시 반영
Stop-Process -Name explorer -Force

1.2 클립보드 히스토리 (Win + V)

매우 유용한데 기본 비활성화. Settings → System → Clipboard → Clipboard history ON.

1.3 가상 데스크톱 단축키

Ctrl + Win + ←/→ — 가상 데스크톱 전환. 기본 동작이지만 처음 쓰는 사람은 모른다. macOS의 swipe-between-spaces 대응.

1.4 PowerToys (선택, 강력 권장)

마이크로소프트 공식 생산성 도구 모음. winget으로 한 줄:

winget install Microsoft.PowerToys --source winget --silent

핵심: FancyZones(창 분할 — Rectangle 대응), PowerToys Run(Alt + Space — Raycast 대응), Keyboard Manager(키 재매핑).

2. winget — 패키지 매니저 확인

Windows 11은 winget이 기본 포함이지만, 너무 오래된 빌드면 업그레이드가 필요할 수 있다.

winget --version
# v1.x.x  ← 출력되면 OK

없거나 오래됐다면 Microsoft Store에서 "App Installer"를 업데이트한다. winget은 그 안에 들어있다.

자동화 스크립트 (선택)

수동 따라가는 대신 한 번에 실행하고 싶다면 — 단, 외부 스크립트는 항상 다운로드 → SHA-256 검증 → 코드 검사 → 실행 순서로.

# 1. 다운로드 (PowerShell)
Invoke-WebRequest -Uri https://devalice.jaceclub.com/assets/windows/initial-setup/setup-windows.ps1 -OutFile setup-windows.ps1
 
# 2. SHA-256 검증
Get-FileHash setup-windows.ps1 -Algorithm SHA256
# 기대값: 75a9a5cc7b8804cf0808971a648b7174dade3a5f32f2db9c80a9783242eeeebd
 
# 3. 코드 검사
notepad setup-windows.ps1
 
# 4. 실행 (현재 세션에 한해 실행 정책 완화)
PowerShell -ExecutionPolicy Bypass -File .\setup-windows.ps1

스크립트는 idempotent — 중간에 실패하거나 부분 진행 후 재실행해도 안전. 본문 3~5단계 중 winget 설치·Git 설정·SSH 키 생성까지 자동, WSL2 설치와 GitHub 등록은 수동 단계로 안내.

직접 이해하며 따라가고 싶다면 아래로.

3. winget 필수 도구 — 10분

3.1 핵심 8개 한 줄로

winget install --silent --accept-source-agreements --accept-package-agreements `
  Git.Git `
  GitHub.cli `
  Microsoft.WindowsTerminal `
  Microsoft.PowerShell `
  Microsoft.VisualStudioCode `
  jdx.mise `
  BurntSushi.ripgrep.MSVC `
  junegunn.fzf

일부 패키지는 처음 설치 시 PATH 갱신을 위해 새 터미널 창을 열어야 한다.

3.2 검증

git --version
gh --version
pwsh --version       # PowerShell 7
code --version
mise --version
rg --version

3.3 Windows Terminal을 기본 터미널로

Settings → Privacy & security → For developers → Terminal → Windows Terminal 선택. 이제 어디서든 콘솔이 뜨면 Windows Terminal로 열린다.

4. WSL2 + Ubuntu — 10분

본격 Linux 워크플로를 쓸 거면 WSL2가 1순위. Node·Python·Docker 모두 WSL2 안에서가 훨씬 매끄럽다.

4.1 설치

관리자 PowerShell(우클릭 → "Run as administrator")에서:

wsl --install -d Ubuntu-24.04

이 한 줄이:

1. WSL 기능 활성화
2. 가상 머신 플랫폼 활성화
3. WSL2를 기본 버전으로 설정
4. Ubuntu 24.04 다운로드·설치

설치 끝나면 재부팅 한 번 필요. 재부팅 후 Ubuntu가 자동 실행되며 사용자명·비밀번호를 묻는다.

4.2 첫 실행 후 정리

Ubuntu 셸 안에서:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl unzip

VS Code와 통합하려면 Ubuntu 안에서:

code .   # WSL Remote 확장이 자동 설치되며 VS Code가 WSL 모드로 열린다

WSL 폴더는 Explorer에서 \\wsl$\Ubuntu-24.04\home\<user>로 접근 가능. 다만 Linux 파일 I/O 성능은 WSL 안 경로(/home/...)에서 작업할 때 가장 빠르다. Windows 측 경로(/mnt/c/...)에 코드를 두면 느려진다.

4.3 WSL 상태 확인

PowerShell에서:

wsl --status
wsl --list --verbose
# NAME            STATE           VERSION
# Ubuntu-24.04    Running         2

5. Git 글로벌 + SSH 키 — 10분

WSL과 Windows는 각각 별도 git 설정을 가진다. 둘 다 셋업하는 것을 권장.

5.1 Windows 측 Git 설정 (PowerShell)

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.autocrlf true   # Windows 줄바꿈 자동 변환
git config --global core.editor "code --wait"

5.2 SSH 키 생성 — ed25519

ssh-keygen -t ed25519 -C "you@example.com"
# 저장 위치: 기본값 ($env:USERPROFILE\.ssh\id_ed25519) Enter
# Passphrase: 선택

ssh-agent 서비스 시작 + 키 등록 (관리자 PowerShell):

# Service를 자동 시작으로
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent
 
# 키 추가
ssh-add $env:USERPROFILE\.ssh\id_ed25519

5.3 GitHub에 공개키 등록

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

브라우저에서 https://github.com/settings/ssh/new → Title: "Windows 11 (PC명)" → Key 붙여넣기 → Add SSH key.

5.4 gh CLI 인증

gh auth login
# GitHub.com → HTTPS → Y (Git 인증 사용) → Login with a web browser

5.5 WSL 측 Git 설정 (선택, WSL을 메인으로 쓴다면)

Ubuntu 셸 안에서 동일한 명령을 다시:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
ssh-keygen -t ed25519 -C "you@example.com"
# 공개키 출력 → GitHub에 별도로 등록 (Windows 키와 분리 권장 — 머신 식별 명확)
cat ~/.ssh/id_ed25519.pub

팁: WSL과 Windows에서 SSH 키를 공유하고 싶다면, Windows 키(%USERPROFILE%\.ssh)를 WSL의 ~/.ssh에 심볼릭 링크하는 방법이 있다. 단, 권한 처리에서 종종 사고가 나므로 키를 따로 두는 편이 안전하다.

6. 검증 — 모든 게 잘 깔렸나?

PowerShell에서:

Write-Host "--- Versions ---"
[System.Environment]::OSVersion.Version
git --version
gh --version | Select-Object -First 1
pwsh --version
wsl --list --verbose
 
Write-Host "--- GitHub auth ---"
ssh -T git@github.com 2>&1 | Select-Object -First 1
gh auth status 2>&1 | Select-Object -First 3

기대 출력:

--- Versions ---
Major  Minor  Build
-----  -----  -----
   10      0  22631   (Windows 11 22H2 이상)
git version 2.x.x.windows.x
gh version 2.x.x
PowerShell 7.x.x
NAME            STATE           VERSION
Ubuntu-24.04    Running         2
--- GitHub auth ---
Hi <your-username>! You've successfully authenticated, ...
github.com
  ✓ Logged in to github.com account <your-username>

WSL 측까지 검증하려면 Ubuntu 셸에서:

git --version
ssh -T git@github.com 2>&1 | head -1

7. 트러블슈팅

wsl --install이 "0x80070003" 또는 가상화 에러

BIOS에서 VT-x/AMD-V가 꺼져 있다. 메인보드 매뉴얼대로 BIOS 진입 → CPU Configuration → Virtualization Technology → Enabled → 저장 후 재부팅.

winget이 "command not found"

App Installer가 안 깔려 있거나 매우 오래된 버전. Microsoft Store에서 "App Installer" 검색 → 업데이트/설치.

PowerShell 스크립트 실행 정책 차단

.\setup-windows.ps1 : File ... cannot be loaded because running scripts is disabled on this system.

현재 세션에 한해서만 우회:

PowerShell -ExecutionPolicy Bypass -File .\setup-windows.ps1

영구 변경하려면 (사용자 권한):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Git push 시 "Permission denied (publickey)"

ssh-add -l                                # 키가 ssh-agent에 있는지
ssh -vT git@github.com 2>&1 | Select -Last 20

• ssh-agent 서비스가 중지됐을 수 있음 → Start-Service ssh-agent
• 공개키가 GitHub에 등록 안 됐을 수 있음 → https://github.com/settings/keys 확인

WSL 안에서 시간이 미래/과거로 어긋남

대기 모드 후 종종 발생. WSL 안에서:

sudo hwclock -s

winget이 어떤 패키지를 "found multiple packages" 에러로 거부

ID 충돌. --id 옵션을 명시:

winget install --id Git.Git --exact

Windows Terminal에서 한글이 깨짐

Settings (Ctrl + ,) → 해당 프로필 → Appearance → Font face → Cascadia Mono 또는 D2Coding 같은 한글 지원 폰트.

8. 다음 단계

이 가이드는 "Windows 11에서 git push할 수 있는 최소 셋업"까지였다. 그다음은:

• WSL2 고급 활용 — Docker Desktop ↔ WSL2 통합, 메모리 제한 (%USERPROFILE%\.wslconfig) — /windows/wsl-tuning (준비 중)
• 개발 도구 — 언어 런타임(Node·Python), 에디터 확장 — /windows/developer-tools (준비 중)
• AI Agent 환경 — Claude Code 셋업은 /ai-agents/claude-code 참조
• Mac과 동시 사용 — 입력 공유·파일 동기화 — /multi-os/input-sharing (준비 중)

참고 링크

• winget 공식
• WSL 공식 문서
• PowerToys
• GitHub SSH 키 등록 가이드

변경 이력

• 2026-05-11 — 초안 (devAlice M0 세 번째 시드 컨텐츠)