夜雨聆风
适用环境：Windows 11 推荐 Linux：Ubuntu 24.04 LTS 目标：安装 WSL2，并配置成可以正常进行 Git、Python、Node.js、Java、Android 等开发的 Linux 环境。
1. WSL2 是什么
WSL 全称：
Windows Subsystem for Linux即：
适用于 Linux 的 Windows 子系统WSL2 可以让你直接在 Windows 中运行一个完整的 Linux 环境，例如：
Windows 11├── PowerShell├── Windows Terminal├── VS Code├── Android Studio│└── WSL2 └── Ubuntu 24.04 ├── bash / zsh ├── git ├── ssh ├── gcc ├── python ├── node ├── java └── docker相比传统虚拟机，WSL2 最大的优势是：
不需要单独安装 VMware / VirtualBox Windows 和 Linux 可以直接访问彼此的文件 Windows Terminal 可以直接进入 Linux VS Code 可以直接连接 WSL Windows 可以直接运行 Linux 命令 Linux 可以直接启动 Windows 程序 支持完整 Linux 内核 支持 Docker 支持 systemd
对于开发环境来说，通常推荐直接使用 WSL2，不建议再使用 WSL1。
2. 系统要求
推荐：
Windows 11也支持较新的 Windows 10。
微软当前的一键安装方式要求：
Windows 10 2004 / Build 19041 或更高或者：
Windows 11如果是 Windows 11，基本不需要考虑系统版本问题。
3. 检查 Windows 版本
按：
Win + R输入：
winver回车。
如果看到：
Windows 11即可继续。
4. 检查 CPU 虚拟化
WSL2 依赖 CPU 虚拟化。
打开：
任务管理器快捷键：
Ctrl + Shift + Esc进入：
性能→ CPU查看右下角：
虚拟化：已启用正常应该看到：
虚拟化：已启用如果显示：
虚拟化：已禁用需要进入 BIOS 开启。
Intel CPU 一般叫：
Intel Virtualization TechnologyVT-xAMD CPU 一般叫：
SVM ModeAMD-V开启后保存 BIOS 设置并重新进入 Windows。
5. 打开管理员 PowerShell
在开始菜单搜索：
PowerShell或者：
Terminal右键：
以管理员身份运行后面的 WSL 安装命令建议都在：
管理员 PowerShell中执行。
6. 查看当前 WSL 状态
执行：
wsl --status如果还没有安装 WSL，可能提示：
Windows Subsystem for Linux has no installed distributions或者提示安装 WSL。
都属于正常情况。
7. 查看可以安装的 Linux
执行：
wsl --list --online也可以写成：
wsl -l -o通常会看到类似：
NAME FRIENDLY NAMEUbuntu UbuntuUbuntu-24.04 Ubuntu 24.04 LTSUbuntu-22.04 Ubuntu 22.04 LTSDebian Debian GNU/Linuxkali-linux Kali Linux RollingopenSUSE-Tumbleweed openSUSE Tumbleweed开发环境推荐：
Ubuntu-24.04原因：
LTS 长期支持版本 软件资料最多 WSL 支持成熟 Python / Node / Java / Docker / Android 开发方便 Ubuntu 社区资料丰富
8. 安装 WSL2
1. 方式一：最简单安装
管理员 PowerShell：
wsl --install这个命令通常会自动：
安装 WSL 启用所需 Windows 功能 安装 WSL2 安装默认 Ubuntu 配置 WSL2
执行完成后：
重新启动 Windows9. 推荐：明确安装 Ubuntu 24.04
如果希望明确安装 Ubuntu 24.04：
wsl --install -d Ubuntu-24.04然后重新启动：
Windows推荐直接使用这个命令。
10. 如果 Microsoft Store 无法下载
部分公司网络、代理环境或者 Microsoft Store 有问题时，安装可能卡在：
0.0%可以改用：
wsl --install --web-download -d Ubuntu-24.04这里：
--web-download表示不通过 Microsoft Store 下载 Linux 发行版。
11. 重启电脑
安装结束以后建议直接：
重新启动 Windows不要只关闭 PowerShell。
12. 第一次启动 Ubuntu
重启以后，在开始菜单搜索：
Ubuntu 24.04打开。
或者在 PowerShell 执行：
wsl也可以指定：
wsl -d Ubuntu-24.04第一次启动会进行初始化。
可能看到：
Installing, this may take a few minutes...等待初始化完成。
13. 创建 Linux 用户
第一次启动 Ubuntu 时，会要求：
Enter new UNIX username:例如：
zyz输入：
zyz然后要求设置密码：
New password:输入密码。
注意：
Linux 输入密码时：
屏幕不会显示任何字符不会显示：
*也不会显示：
●这是正常现象。
输入完成直接回车。
然后再次输入：
Retype new password:创建完成。
14. Linux 用户名不要使用 root
建议：
zyz或者：
dev不要直接使用：
root日常开发使用普通用户。
需要管理员权限时使用：
sudo例如：
sudo apt update15. 检查 WSL 是否为 WSL2
回到 Windows PowerShell：
wsl -l -v例如：
NAME STATE VERSION* Ubuntu-24.04 Running 2重点看：
VERSION必须是：
2这说明：
Ubuntu-24.04 正在使用 WSL216. 如果 VERSION 显示 1
执行：
wsl --set-version Ubuntu-24.04 2然后再次检查：
wsl -l -v应该变成：
Ubuntu-24.04 Running 217. 设置以后新安装的 Linux 默认使用 WSL2
执行：
wsl --set-default-version 2以后再安装：
DebianUbuntuKali默认都会使用：
WSL218. 更新 WSL
建议安装完成后执行：
wsl --update检查版本：
wsl --version例如可能看到：
WSL version: 2.x.xKernel version: 6.x.xWSLg version: ...Windows version: ...只要能够正常显示版本即可。
19. 检查 WSL 状态
执行：
wsl --status可以查看：
默认发行版默认 WSL 版本内核版本20. 更新 Ubuntu 软件源
进入 Ubuntu：
wsl执行：
sudo apt update然后：
sudo apt upgrade -y第一次可能下载较多软件包。
21. 安装基本开发工具
推荐：
sudo apt install -y \ build-essential \ git \ curl \ wget \ unzip \ zip \ vim \ nano \ tree \ htop \ jq \ ca-certificates安装完成检查：
git --version例如：
git version 2.x.x检查 gcc：
gcc --version检查 curl：
curl --version22. 查看 Ubuntu 版本
执行：
cat /etc/os-release应该看到类似：
NAME="Ubuntu"VERSION="24.04.x LTS"也可以：
lsb_release -a如果命令不存在：
sudo apt install lsb-release23. 查看 Linux 内核
执行：
uname -a一般可以看到：
microsoft-standard-WSL2说明运行在：
WSL224. Windows 如何进入 WSL 文件
Windows 文件资源管理器地址栏输入：
\\wsl$可以看到：
Ubuntu-24.04例如 Linux：
/home/zyz/CodeWindows 可以通过：
\\wsl$\Ubuntu-24.04\home\zyz\Code访问。
Windows 11 新版资源管理器通常左侧也会直接显示：
Linux25. WSL 如何访问 Windows 文件
Windows：
C:\在 WSL 中：
/mnt/c/例如：
Windows：
C:\Users\zyz\DownloadsWSL：
/mnt/c/Users/zyz/DownloadsD 盘：
D:\对应：
/mnt/d/例如：
cd /mnt/d/Code26. 一个非常重要的开发建议
如果代码主要使用 Linux 工具开发：
GitNode.jsPythonJavaDockerCodexClaude Code建议把项目放在：
/home/用户名/例如：
/home/zyz/Code推荐：
mkdir -p ~/Codecd ~/Code不要长期把 WSL 项目放：
/mnt/c/Code或者：
/mnt/d/Code原因是 Linux 项目放在 WSL 自己的 ext4 文件系统里通常：
文件 IO 更快 Git 更快 npm 更快 node_modules 更快 Python venv 更稳定 Linux 文件权限更正常 符号链接兼容性更好 不容易出现 .git/index.lock等 Windows/WSL 文件系统冲突
推荐目录：
/home/zyz/Code/github/home/zyz/Code/gitea/home/zyz/Code/gitlab例如：
mkdir -p ~/Code/githubmkdir -p ~/Code/giteamkdir -p ~/Code/gitlab27. Windows 如何打开 WSL 当前目录
在 WSL：
explorer.exe .例如：
cd ~/Codeexplorer.exe .会直接打开 Windows 文件资源管理器。
28. WSL 如何调用 Windows 程序
WSL 可以直接执行：
notepad.exe例如：
notepad.exe test.txt也可以：
explorer.exe .PowerShell：
powershell.exe新版 PowerShell：
pwsh.exeGit for Windows 等程序也可以通过完整路径调用。
29. Windows 如何执行 Linux 命令
PowerShell 中：
wsl ls例如：
wsl pwd执行：
wsl uname -a也可以：
wsl bash -c "ls -lah"30. 安装 Windows Terminal
Windows 11 通常已经安装：
Windows Terminal如果没有，可以从 Microsoft Store 安装：
Windows Terminal安装 Ubuntu 后，Terminal 通常自动增加：
Ubuntu 24.04配置。
以后直接：
Windows Terminal→ Ubuntu 24.04即可进入 WSL。
31. 设置 Ubuntu 为 Windows Terminal 默认终端
打开：
Windows Terminal进入：
设置→ 启动→ 默认配置文件选择：
Ubuntu 24.04以后打开 Terminal 就直接进入 Linux。
如果平时 Windows PowerShell 用得比较多，则可以继续保持：
PowerShell作为默认终端。
32. 安装 zsh
Ubuntu 默认 Shell 是：
bash如果喜欢 zsh：
sudo apt install zsh -y查看位置：
which zsh通常：
/usr/bin/zsh切换默认 shell：
chsh -s $(which zsh)然后退出 WSL：
exitPowerShell：
wsl --shutdown重新进入：
wsl检查：
echo$SHELL应该显示：
/usr/bin/zsh33. Git 基础配置
进入 WSL：
git config --global user.name "你的名字"例如：
git config --global user.name "zyz"设置邮箱：
git config --global user.email "you@example.com"查看：
git config --global --list34. 配置 Git 默认分支
推荐：
git config --global init.defaultBranch main如果公司项目仍使用：
master则根据公司规范配置。
35. 配置 Git 换行符
WSL 是 Linux 环境。
推荐：
git config --global core.autocrlf input这样提交时：
CRLF → LF但检出时不会强制转为 Windows CRLF。
对于跨平台开发通常比较合适。
36. 配置 SSH
进入：
cd ~创建：
mkdir -p ~/.ssh权限：
chmod 700 ~/.ssh如果准备在 WSL 单独生成 SSH key：
ssh-keygen -t ed25519一路回车即可。
默认生成：
~/.ssh/id_ed25519~/.ssh/id_ed25519.pub查看公钥：
cat ~/.ssh/id_ed25519.pub复制到：
GitHubGitLabGitea即可。
37. SSH 权限
Linux 对 SSH 文件权限比较严格。
目录：
chmod 700 ~/.ssh私钥：
chmod 600 ~/.ssh/id_ed25519公钥：
chmod 644 ~/.ssh/id_ed25519.pub配置：
chmod 600 ~/.ssh/config否则可能出现：
Bad owner or permissions on ~/.ssh/config38. 测试 GitHub SSH
执行：
ssh -T git@github.com第一次可能提示：
Are you sure you want to continue connecting (yes/no/[fingerprint])?输入：
yes成功后一般会提示认证成功。
39. 安装 Python
Ubuntu 24.04 默认通常已经有 Python 3。
检查：
python3 --version安装基础工具：
sudo apt install -y python3 python3-pip python3-venv创建虚拟环境：
python3 -m venv .venv激活：
source .venv/bin/activate退出：
deactivate40. 安装 Node.js
不建议简单使用：
sudo apt install nodejs因为 Ubuntu 软件源里的 Node.js 版本可能不是你需要的版本。
推荐使用：
nvm管理 Node.js。
安装完 nvm 后可以：
nvm install --lts然后：
node --versionnpm --versionnvm 的好处：
Node 18Node 20Node 22Node 24可以自由切换。
41. 安装 Java
如果开发需要 Java 17：
sudo apt install openjdk-17-jdk -y检查：
java -version查看 javac：
javac -version如果需要 Java 21：
sudo apt install openjdk-21-jdk -y42. VS Code 使用 WSL
Windows 安装：
Visual Studio Code然后安装扩展：
WSL进入 WSL 项目：
cd ~/Code/my-project执行：
code .第一次会自动安装：
VS Code Server以后 VS Code 左下角应该显示：
WSL: Ubuntu-24.04此时：
VS Code UI运行在 Windows。
但是：
GitPythonNodeTerminal编译器运行在 Linux。
这是比较推荐的开发模式。
43. VS Code 项目建议
推荐：
Windows└── VS CodeWSL└── /home/zyz/Code/project不要为了让 Windows 软件看到项目，就把代码放到：
C:\CodeWindows VS Code 可以直接打开：
\\wsl$\Ubuntu-24.04\home\zyz\Code更推荐通过：
code .启动。
44. 检查 systemd
执行：
systemctl --version然后：
systemctl status现代 WSL 已支持：
systemd可以运行：
PostgreSQLRedisDockerNginxsystemd service等 Linux 服务。
45. WSL 网络
WSL 中可以访问互联网：
curl https://www.baidu.com或者：
curl https://github.com检查 IP：
ip addr查看：
hostname -I46. Windows 访问 WSL Web 服务
假设 WSL 中启动：
python3 -m http.server 8000Windows 浏览器通常可以直接访问：
http://localhost:8000例如 FastAPI：
uvicorn main:app --host 0.0.0.0 --port 8000Windows：
http://localhost:8000即可访问。
47. WSL 访问 Windows 服务
如果 Windows 程序监听：
127.0.0.1:8080新版本 WSL 在很多情况下可以直接：
curl http://localhost:8080如果访问失败，则需要根据 WSL 网络模式进一步配置。
48. 查看安装了哪些 WSL
Windows PowerShell：
wsl -l详细查看：
wsl -l -v例如：
NAME STATE VERSION* Ubuntu-24.04 Running 249. 查看所有 WSL，包括停止状态
wsl --list --verbose缩写：
wsl -l -v50. 关闭 WSL
退出当前 Linux：
exit这只是退出 Shell。
如果需要完全关闭整个 WSL：
wsl --shutdown再次：
wsl会重新启动。
51. 停止单个 Linux
例如：
wsl --terminate Ubuntu-24.04缩写：
wsl -t Ubuntu-24.0452. 设置默认 Linux
如果安装多个：
Ubuntu-24.04DebianKali可以设置：
wsl --set-default Ubuntu-24.04以后：
wsl默认进入 Ubuntu 24.04。
53. 进入指定 Linux
wsl -d Ubuntu-24.04例如：
wsl -d Debian54. 使用指定 Linux 用户
例如：
wsl -d Ubuntu-24.04 -u root直接以 root 进入。
一般只用于维护。
不要作为日常开发方式。
55. 查看 WSL 帮助
执行：
wsl --help可以查看全部 WSL 命令。
56. WSL 更新
定期可以：
wsl --update更新后：
wsl --shutdown重新打开。
57. 推荐开发目录结构
例如：
/home/zyz/├── Code/│ ├── github/│ ├── gitlab/│ ├── gitea/│ └── company/│├── Downloads/├── Scripts/└── .ssh/创建：
mkdir -p ~/Code/githubmkdir -p ~/Code/gitlabmkdir -p ~/Code/giteamkdir -p ~/Scripts58. 推荐最终开发架构
比较推荐：
Windows 11│├── Windows Terminal├── PowerShell 7├── Edge / Chrome├── VS Code├── Android Studio├── adb.exe│└── WSL2 └── Ubuntu 24.04 │ ├── ~/Code │ ├── github │ ├── gitlab │ └── gitea │ ├── Git ├── SSH ├── Python ├── Node.js ├── Java ├── GCC ├── Docker └── Codex / Claude Code这种架构的原则是：
GUI 软件 → Windows开发运行环境 → WSL代码 → WSL 文件系统59. 常见问题：wsl --install 无反应
先执行：
wsl --update然后：
wsl --shutdown重新：
wsl --install -d Ubuntu-24.04如果下载卡住：
wsl --install --web-download -d Ubuntu-24.0460. 常见问题：提示 Virtual Machine Platform
管理员 PowerShell：
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重新启动 Windows。
61. 常见问题：手动启用 WSL Windows 功能
如果自动安装方式失败，可以执行：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart然后：
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart重新启动：
Windows然后：
wsl --set-default-version 2最后：
wsl --install -d Ubuntu-24.0462. 常见问题：0x80370102
如果提示类似：
0x80370102通常检查：
CPU 虚拟化Virtual Machine PlatformBIOS VT-x / AMD-V任务管理器：
性能→ CPU→ 虚拟化必须为：
已启用63. 常见问题：忘记 Ubuntu 密码
PowerShell：
wsl -d Ubuntu-24.04 -u root进入后：
passwd zyz例如：
passwd zyz重新设置密码。
然后：
exit正常重新进入：
wsl64. 常见问题：WSL 出现奇怪问题
最简单的第一步：
wsl --shutdown然后重新打开：
wsl很多：
网络挂载systemd文件锁问题可以通过完全重启 WSL 恢复。
65. 不要随便执行 wsl --unregister
下面这个命令非常危险：
wsl --unregister Ubuntu-24.04它的含义不是：
退出登录而是：
删除整个 Ubuntu里面包括：
/home代码数据库配置文件SSH环境都会被删除。
因此：
除非确定要彻底删除整个 Linux 环境，否则不要执行
wsl --unregister。
66. 如果真的需要删除 Ubuntu
首先备份重要代码。
然后：
wsl --shutdown确认：
wsl -l -v再执行：
wsl --unregister Ubuntu-24.04之后可以重新安装：
wsl --install -d Ubuntu-24.0467. 安装完成后的最终检查
Windows PowerShell：
wsl --version然后：
wsl --status然后：
wsl -l -v应该确认：
Ubuntu-24.04VERSION = 2进入 Linux：
wsl检查：
cat /etc/os-release检查内核：
uname -a检查网络：
curl https://github.com检查 Git：
git --version检查 sudo：
sudowhoami如果返回：
root说明 sudo 正常。
68. 最精简安装流程
如果不想看前面所有说明，Windows 11 实际安装 WSL2 只需要：
2. 第一步
管理员 PowerShell：
wsl --install -d Ubuntu-24.043. 第二步
重启 Windows。
4. 第三步
打开：
Ubuntu 24.04创建：
Linux 用户名Linux 密码5. 第四步
PowerShell：
wsl -l -v确认：
VERSION = 26. 第五步
Ubuntu：
sudo apt updatesudo apt upgrade -y7. 第六步
安装开发工具：
sudo apt install -y build-essential git curl wget unzip zip vim tree htop jq8. 第七步
创建代码目录：
mkdir -p ~/Codecd ~/Code到这里，一个标准的：
Windows 11 + WSL2 + Ubuntu 24.04开发环境就已经安装完成。
69. 推荐的一套 WSL2 开发原则
最后建议记住下面几条：
使用 WSL2，不要主动使用 WSL1。 推荐使用 Ubuntu 24.04 LTS。 Linux 项目尽量放在： /home/用户名/Code不要长期把大型项目放： /mnt/c/mnt/dLinux 的 Git、SSH、Python、Node、Java 尽量在 WSL 内单独配置。 Windows 负责 GUI，WSL 负责开发运行环境。 VS Code 使用 WSL Remote 模式。 修改 WSL 配置后出现异常，可以先： wsl --shutdown定期更新： wsl --update不要随便执行： wsl --unregister
70. 推荐安装完成后的下一步
WSL2 安装完成以后，可以继续配置：
WSL2├── zsh├── Powerlevel10k├── Git├── SSH├── GitHub / GitLab / Gitea├── Python├── uv├── Node.js / nvm├── Java 17 / 21├── Docker├── VS Code├── Codex CLI└── Android 开发环境如果主要用途是软件开发，建议按照这个顺序配置：
WSL2↓Ubuntu↓Git + SSH↓zsh↓开发语言环境↓VS Code↓Docker↓AI CLI / Codex