Windows 11 单路径搭建：winget · WSL2 · Git · SSH。让一台新 PC 达到可 git push 的状态。

Windows 开发有两种风格：（a）在 WSL2/Linux 内完成所有工作；（b）用 PowerShell + Git Bash 原生运行。本指南两者都配，让你按项目自由选择。Node/Go/Python？WSL2 大幅胜出。.NET、游戏、Tauri、Win32 API？原生方案才是正解。

我认为 Windows 开发环境的关键决策不是「用什么工具」，而是「什么工作跑在哪里」。以前开发者常常只选一种风格；如今两者并配，由于不同技术栈对运行环境的依赖不同，按项目自由切换才是最合理的方案。

目标环境：Windows 11（22H2 或更新版本），需要 winget 可用。Windows 10 大体适用，winget 细节略有差异。

TL;DR

四项 Windows 11 系统设置（显示扩展名/隐藏文件、剪贴板历史、虚拟桌面快捷键）
winget 一行安装八个必备工具（Git、GH CLI、Windows Terminal、PowerShell 7、VS Code、mise、ripgrep、fzf）
WSL2 + Ubuntu 24.04：wsl --install -d Ubuntu-24.04
Git 全局配置 + SSH ed25519 → 注册到 GitHub → gh auth login

前置条件

Windows 11 22H2+ — 用 winver 确认。这是第一个内置 winget 的版本。
管理员权限 — WSL2 安装和部分系统级 winget 包需要。
网络 + Microsoft 账号（Windows 11 家庭版实际上必须）。
硬件虚拟化 — BIOS/UEFI 中已启用 Intel VT-x 或 AMD-V（WSL2 必须）。通常默认开启。

用 systeminfo | findstr /C:"Hyper-V" 验证——每一行「Hyper-V Requirements」都应显示 Yes。

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
Stop-Process -Name explorer -Force

1.2 剪贴板历史（Win + V）

非常实用，默认关闭。Settings → System → Clipboard → Clipboard history 开启。

1.3 虚拟桌面

Ctrl + Win + ←/→ — 切换桌面。内置功能，但很多人不知道。相当于 macOS 的左右滑动切换空间。

1.4 PowerToys（可选，强烈推荐）

微软官方生产力套件。一行 winget 命令：

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

亮点：FancyZones（窗口平铺，相当于 Rectangle）、PowerToys Run（Alt + Space，相当于 Raycast）、Keyboard Manager（按键重映射）。

2. winget — 确认包管理器

winget 随 Windows 11 预装。非常旧的版本可能需要更新。

winget --version
# v1.x.x  ← 有这个输出？搞定

没有或版本过旧？微软应用商店 → 搜索「App Installer」→ 更新。winget 就在这个包里。

自动化脚本（可选）

想用一个脚本代替逐步操作？务必下载 → 验证 SHA-256 → 检查内容 → 运行。

setup-windows.ps1

# 1. 下载
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
# expected: 75A9A5CC7B8804CF0808971A648B7174DADE3A5F32F2DB9C80A9783242EEEEBD
# (lowercase: 75a9a5cc7b8804cf0808971a648b7174dade3a5f32f2db9c80a9783242eeeebd)
 
# 3. 检查内容
notepad setup-windows.ps1
 
# 4. 运行（仅本次会话放开执行策略）
PowerShell -ExecutionPolicy Bypass -File .\setup-windows.ps1

脚本是幂等的——部分失败后重新运行是安全的。它自动完成 winget 安装 + Git 配置 + SSH 密钥创建。WSL2 安装和 GitHub 密钥注册仍需手动操作。

如果你更倾向于逐步手动操作，请继续阅读以下内容。

3. winget 必备工具 — 10 分钟

3.1 一行安装八个必备工具

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

包名	用途
`Git.Git`	Git for Windows（含 Git Bash）
`GitHub.cli`	`gh`
`Microsoft.WindowsTerminal`	标签页终端——比默认控制台强大得多
`Microsoft.PowerShell`	PowerShell 7（默认是 5.1；7 大幅改进）
`Microsoft.VisualStudioCode`	VS Code
`jdx.mise`	运行时版本管理器（Node · Python · …）
`BurntSushi.ripgrep.MSVC`	`rg`——比 grep 更快
`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 是你的主要工具。Node、Python、Docker——在 WSL2 内都顺畅得多。

4.1 安装

在管理员 PowerShell（右键 → 「以管理员身份运行」）中：

wsl --install -d Ubuntu-24.04

这一行命令：

启用 WSL 功能
启用虚拟机平台
将 WSL2 设为默认版本
下载并安装 Ubuntu 24.04

重启一次。重启后 Ubuntu 启动并提示设置用户名/密码。

4.2 初始清理

在 Ubuntu 内：

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

在当前 Ubuntu 文件夹中打开 Windows VS Code（自动安装 WSL Remote 扩展）：

code .

通过 \\wsl$\Ubuntu-24.04\home\<user> 在 Explorer 中访问 WSL 文件。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 接受）
# 密码短语：可选

启动 ssh-agent + 添加密钥（管理员 PowerShell）：

# 自动启动服务
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名称）」→ 粘贴密钥 → Add SSH key。

5.4 gh CLI 认证

gh auth login
# GitHub.com → HTTPS → Y（用 GitHub 凭据认证 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 单独注册（每台机器的每个环境各用独立密钥，方便审计）
cat ~/.ssh/id_ed25519.pub

提示：可以将 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 缺失或版本过旧。微软应用商店 → 搜索「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                                # 密钥是否在 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 + ,）→ 对应 profile → Appearance → Font face → 选择 Cascadia Mono 或 D2Coding（任何支持完整韩文覆盖的字体）。

8. 下一步

本指南到此让 Windows 11 能够 git push。之后：

进阶 WSL2 — Docker Desktop ↔ WSL2 集成、内存上限（%USERPROFILE%\.wslconfig）— WSL 调优
开发工具 — 语言运行时（Node · Python）、编辑器扩展
AI agent 环境 — Claude Code 配置 — /ai-agents/claude-code
同时使用 Mac — 输入设备共享、文件同步 — /multi-os/input-sharing

参考资料

更新日志

2026-05-12 — 初版英文翻译（devAlice M3 i18n seed）

Windows 11 开发者环境搭建 — 开箱后的第一个小时