WSL2 首次配置笔记｜Windows 11
配置目标
将 WSL 配置为相对独立的 Linux 开发环境：
- 安装 WSL2 和 Ubuntu
- 使用 Windows 的网络和代理
- 启用镜像网络模式
- 不把 Windows 软件路径导入 Linux
- OpenCode、Codex、Python、Node 等工具都单独安装在 WSL 中
一、安装 WSL2 和 Ubuntu
1. 使用管理员 PowerShell 安装
右键开始菜单，打开：
1 | 终端（管理员） |
执行：
1 | wsl --install |
然后重启 Windows。
wsl --install 会启用 WSL 所需的 Windows 功能，并默认安装 Ubuntu，因此“安装 WSL”和“安装 Ubuntu”通常可以合并为一步。它不是进入 Windows 安全模式；正常的 Windows 11 直接运行命令即可。(Microsoft Learn)
2. 如果没有自动安装 Ubuntu
查看可安装的发行版：
1 | wsl --list --online |
安装 Ubuntu：
1 | wsl --install -d Ubuntu |
3. 更新并检查 WSL
1 | wsl --update |
预期结果类似：
1 | NAME STATE VERSION |
如果 Ubuntu 不是 WSL2：
1 | wsl --set-version Ubuntu 2 |
使用 wsl --install 新安装的发行版通常默认就是 WSL2。(Microsoft Learn)
二、首次启动 Ubuntu
从开始菜单打开：
1 | Ubuntu |
第一次启动时，需要设置：
1 | Linux 用户名 |
输入密码时，屏幕上不会显示星号或字符，这是 Linux 的正常行为。
进入 Ubuntu 后更新软件包：
1 | sudo apt update |
查看当前用户和系统：
1 | whoami |
以后看到这样的提示符：
1 | nangua@nangua:~$ |
就说明当前处于 Ubuntu/WSL，而不是 PowerShell。
如果前面带有：
1 | (base) nangua@nangua:~$ |
表示 WSL 里的 Conda 自动激活了 base 环境。可以关闭自动激活：
1 | conda config --set auto_activate_base false |
三、配置镜像网络和 Windows 代理
这一部分需要编辑 Windows 用户目录中的：
1 | %UserProfile%\.wslconfig |
.wslconfig 是 Windows 侧的全局 WSL2 配置，会作用于所有 WSL2 发行版。(Microsoft Learn)
1. 在 PowerShell 中打开配置文件
普通 PowerShell 或管理员 PowerShell均可：
1 | notepad $env:USERPROFILE\.wslconfig |
如果提示文件不存在，选择创建。
2. 写入配置
1 | [wsl2] |
配置含义：
1 | networkingMode=mirrored |
启用镜像网络模式，让 WSL 更好地兼容 VPN、IPv6、局域网以及 Windows 的 localhost。镜像网络模式适用于 Windows 11 22H2 及更高版本。(Microsoft Learn)
1 | autoProxy=true |
让 WSL读取 Windows 的 HTTP 代理信息。(Microsoft Learn)
1 | dnsTunneling=true |
让 WSL 的 DNS 请求通过 Windows 处理，通常能改善代理和 VPN 环境下的域名解析。(Microsoft Learn)
1 | firewall=true |
让 Windows 防火墙和 Hyper-V 防火墙规则继续管理 WSL 网络流量。(Microsoft Learn)
3. 重启 WSL
保存文件后，在 PowerShell 中执行：
1 | wsl --shutdown |
重新打开 Ubuntu。
WSL 配置不会在保存后立即应用，需要让 WSL 虚拟机完全停止并重新启动；wsl --shutdown 是最直接的方式。(Microsoft Learn)
4. 测试网络
在 Ubuntu 中执行：
1 | curl -I https://github.com |
查看代理变量：
1 | env | grep -i proxy |
镜像模式下，WSL 通常也可以通过下面的地址访问 Windows 上监听本机端口的服务：
1 | 127.0.0.1 |
例如 Windows 代理监听 7890：
1 | curl -x http://127.0.0.1:7890 -I https://github.com |
四、禁止 WSL 自动导入 Windows PATH
这一步的目的是避免 WSL 输入：
1 | opencode |
结果却调用了 Windows 中的 .exe、.cmd 或 npm 全局程序。
1. 在 Ubuntu 中编辑配置
注意：这次是在 Ubuntu/WSL 中执行：
1 | sudo nano /etc/wsl.conf |
写入：
1 | [interop] |
含义如下：
1 | enabled=true |
保留 WSL 启动 Windows 程序的能力。
1 | appendWindowsPath=false |
不再把 Windows 的路径自动加入 Linux 的 $PATH。该选项默认是 true，所以未配置时经常会出现 Linux 调用 Windows 工具的情况。(Microsoft Learn)
保存 nano：
1 | Ctrl + O |
2. 再次重启 WSL
退出 Ubuntu，然后在 PowerShell 中执行：
1 | wsl --shutdown |
重新打开 Ubuntu。
3. 验证 Windows PATH 是否消失
1 | echo "$PATH" | tr ':' '\n' |
正常情况下，不应再出现大量：
1 | /mnt/c/Windows/... |
也可以专门搜索：
1 | echo "$PATH" | tr ':' '\n' | grep '^/mnt/c' |
没有输出通常表示清理成功。
Windows 的磁盘仍然可以正常访问：
1 | cd /mnt/c |
关闭 appendWindowsPath 只是不再自动导入 Windows 命令路径，不会取消磁盘挂载。
五、安装 WSL 原生 OpenCode
在 Ubuntu 中执行：
1 | curl -fsSL https://opencode.ai/install | bash |
这是 OpenCode 官方提供的安装方式，官方也推荐 Windows 用户通过 WSL 使用 OpenCode。(OpenCode)
安装后检查：
1 | ls -l ~/.opencode/bin/opencode |
如果文件存在，但输入 opencode 提示找不到命令，将目录加入 Linux PATH：
1 | echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc |
验证：
1 | command -v opencode |
正确结果应类似：
1 | /home/nangua/.opencode/bin/opencode |
file 应显示 Linux ELF 程序，而不是 Windows PE 程序。
启动：
1 | opencode |
OpenCode 不带参数运行时会启动终端界面。(OpenCode)
六、最终配置文件汇总
Windows 文件
文件位置：
1 | C:\Users\你的用户名\.wslconfig |
内容：
1 | [wsl2] |
Ubuntu 文件
文件位置：
1 | /etc/wsl.conf |
内容：
1 | [interop] |
Ubuntu 用户环境
文件位置：
1 | ~/.bashrc |
OpenCode 路径：
1 | export PATH="$HOME/.opencode/bin:$PATH" |
七、最简配置流程
管理员 PowerShell
1 | wsl --install |
重启 Windows 后：
1 | wsl --update |
Windows PowerShell
1 | notepad $env:USERPROFILE\.wslconfig |
写入：
1 | [wsl2] |
Ubuntu
1 | sudo nano /etc/wsl.conf |
写入：
1 | [interop] |
PowerShell
1 | wsl --shutdown |
Ubuntu
1 | curl -fsSL https://opencode.ai/install | bash |
这样配置完成后，WSL 会使用 Windows 的网络和代理，但 opencode、python、node、codex 等命令优先使用 WSL 自己安装的 Linux 版本。Windows 和 Linux 各住各屋，不许再半夜互穿拖鞋。
