WSL 环境搭建笔记

前言

希望将自己的环境迁移到 WSL 上面去，Windows 环境下 bug 有点多。。目前已经安装过 Docker Desktop ，和各类 AI CLI ，使用 Bitwarden 保存各类 SSH

安装

因为我已经安装了 Docker Desktop 了，所以我已经有 wsl 了。

wsl -l -v

  NAME              STATE           VERSION
* docker-desktop    Stopped         2

先进行下更新：

wsl --update

使用命令查看可可安装发行版：

wsl --list --online

这里我选择 Debian 安装

wsl --install -d Debian

之后会要求你输入用户名和密码（注意密码你输入不会有显示）。

安装完成后，再次检查可以看到多了一个

wsl -l -v

  NAME              STATE           VERSION
* docker-desktop    Stopped         2
  Debian            Running         2

迁移安装位置

之后我们需要进行迁移工作，因为 wsl 通常会安装到 Windows 用户目录下也就是 C盘，我们需要将其迁移到其他盘里防止过度占用空间。如果你不介意可以跳过。
这里我们使用微软官方推荐的 导出 -> 注销 -> 导入到指定目录 的方法进行迁移。
通过 wsl -l -v 命令我们知道名称为 Debian。

关机：

wsl --shutdown

导出：

wsl --export Debian E:\wsl\debian.tar

务必确认 debian.tar 已经正确生成！
注销原来的 Debian

wsl --unregister Debian

导入：

wsl --import Debian E:\wsl\debian E:\wsl\debian.tar --version 2

启动测试即可：

wsl -d Debian

在导入后默认登录用户可能会变成 root ，编辑（因为你已经是 root 状态了就不用 sudo 了）

nano /etc/wsl.conf

写入

[user]
default=你的用户名

重启

wsl --shutdown

安装 mise

这里直接通过脚本 mise.run 安装。

curl https://mise.run | sh

为 bash 启动 mise

echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

或者手动版：

nano ~/.bashrc

之后将下面的内容加入到最后一行保存

eval "$(~/.local/bin/mise activate bash)"

重新加载配置或者直接关闭 bash 重开

source ~/.bashrc

再次测试

mise --version

全局 node.js 使用最新版

mise use -g node@lts

全局配置查看方法

cat ~/.config/mise/config.toml

让 mise 兼容项目中的 .nvmrc

mise settings set idiomatic_version_file_enable_tools node

配置代理

两种方案，取决于你的 wsl 使用了什么网络模式

NAT 模式

这是 wsl 的默认网络模式，其拥有独立相对隔离的虚拟网段，成熟度更高。
这里需要确认你的代理软件能够允许局域网连接，且端口为 7890 。我这里是 tun 模式。

测试方案

这个是一次性的，wsl 重启就会失效，但是你可以用来测试代理是否有用。

WIN_HOST=$(ip route show default | awk '{print $3}')

export http_proxy="http://${WIN_HOST}:7890"
export https_proxy="http://${WIN_HOST}:7890"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$http_proxy"

export no_proxy="localhost,127.0.0.1,::1"
export NO_PROXY="$no_proxy"

永久方案

编辑 bashrc

nano ~/.bashrc

在最后一行写入下面的内容，这个效果是每次进入 bash 的时候都会执行代理操作，并自动开启代理。输入 proxy_off proxy_on 可开关管理代理。

# ============================
# WSL -> Windows proxy
# ============================

proxy_on() {
    local win_host
    local proxy_port=7890

    win_host=$(ip route show default | awk '/default/ {print $3; exit}')

    if [ -z "$win_host" ]; then
        echo "无法获取 WSL 默认网关。"
        return 1
    fi

    export http_proxy="http://${win_host}:${proxy_port}"
    export https_proxy="$http_proxy"
    export HTTP_PROXY="$http_proxy"
    export HTTPS_PROXY="$https_proxy"

    export no_proxy="localhost,127.0.0.1,::1"
    export NO_PROXY="$no_proxy"

    echo "代理已启用：$http_proxy"
}

proxy_off() {
    unset http_proxy
    unset https_proxy
    unset HTTP_PROXY
    unset HTTPS_PROXY
    unset no_proxy
    unset NO_PROXY

    echo "代理已关闭。"
}

proxy_status() {
    if [ -n "$https_proxy" ]; then
        echo "当前代理：$https_proxy"
    else
        echo "当前未设置代理环境变量。"
    fi
}
proxy_on

重启 bash 或者 命令

source ~/.bashrc

Mirrored 模式

这是一套新的网络架构模式，他是将 Windows 的网络接口和状态更直接的映射到 wsl 中， WSL 可以用 127.0.0.1 访问 Windows 上的服务，能够改善 Windows 与 WSL 之间的网络互通。属于较新的模式，兼容性问题和 bug 较多。需要 Windows 11 22H2 以上版本才可以使用。
好消息是你不需要再去 WSL 设置代理了，坏消息是你需要自行解决非常多的 bug 问题。
首先要手动切换到 Mirrored 模式，先去 Windows 系统下，没有就新建一个文件。

C:\Users\你的用户名\.wslconfig

写入

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true

或者在开始菜单中查找 WSL Settings 。

TUN 模式下因 MTU 过大无法联网

有可能使用该模式后发现在 WSL 内访问变得网络变得非常的慢甚至无法联网，Mirrored 模式下，WSL 和 Windows 之间通过 Hyper-V 虚拟交换机通信，其 MTU 为 1500。而 sing-box/mihomo 的 TUN 默认 MTU 是 9000。大包穿越虚拟交换机时被分片重组，导致严重的性能下降。在代理工具的 TUN 配置中将 MTU 改为 1500 。不同的软件改的方法不同，自己找。

Win下的docker-desktop启动失败，频繁重启

这个我没有碰到，但在教程里面看到说有碰到过的，目前无解，只能切换回 NAT 网络模式。或者卸载 docker desktop 在 WSL 中安装 docker engine。

codex mcp 工具 codex_apps 启动失败

推测原因是其不会走 tun 模式的代理，解决方法就是跟 NAT 模式一样也添加显示代理（好了，这下没有好消息了）。即在 ~/.bashrc 最后一行中添加，注意修改端口，这里注意因为你使用 mirrored 模式，所以网卡地址不再是 172 而直接是 127.0.0.1 。这只是一个简单的方案，不是上面的可开关复杂版。

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export WS_PROXY=http://127.0.0.1:7890
export WSS_PROXY=http://127.0.0.1:7890

添加完成后重启

source ~/.bashrc

安装 AI CLI

wsl 中安装的和 Windows 下安装的是可以共存的，但是他们的配置文件是不共存的，且不推荐使用软链接的方式同步。

npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code
npm install -g opencode-ai

登录前请务必确认你的网络没有问题了！尤其是 Claude ！否则号没了可别没地方哭！

在 Windows 上的配置文件一般都在

C:\Users\用户名\.codex
C:\Users\用户名\.claude
C:\Users\用户名\.gemini
C:\Users\用户名\.config\opencode

在 WSL 上 codex 的配置文件一般在

~/.codex
~/.claude
~/.gemini
~/.config/opencode

像 codex 这类如果你登录不上去，可以考虑去 win 下将你的用于登录信息直接拷贝过来，具体风险目前未知。

关于 MCP

我使用 mcp router 在 Windows 上运行作为 mcp 工具的聚合。
在 AI CLI 里面也可以直接 Windows 上的 mcp 来配置书写即可。以 codex 为例，其是写在 你的配置.config.toml 中的

[mcp_servers.mcp_router]
command = "npx"
args    = ["-y", "@mcp_router/cli@latest", "connect"]
startup_timeout_sec = 120

[mcp_servers.mcp_router.env]
MCPR_TOKEN = "mcpr_example"

关于 mcp 中的路径问题

mcp router 里面的 filesystem 需要你写入权限路径才可以使用。
假设 WSL 上的路径是

/home/用户名/project

在 mcp router 上你需要使用 Windows UNC 格式来写

\\wsl.localhost\Debian\home\用户名\project

SSH Agent

参见文章 《使用 npiperelay 和 socat 在 WSL 中复用 Windows SSH 密钥》

Git

基础设定：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

SSH 方面，因为我使用了 Bitwarden 作为 SSH-Agent ，所以在上面已经设置好了，就不需要设置了。
HTTPS 认证，我在 Windows 下安装了 Git for Windows，所以可以通过 Git Credential Manager 的方式来实现，这样不需要额外设置 token 。Git Credential Manager ，它专门处理 HTTPS Git 仓库的登录认证，并不通过密码，而是通过走浏览器 OAuth 的方式。

先确认你有 GCM，在 WSL 环境下操作，一般来说默认安装会安装在这里。

ls "/mnt/c/Program Files/Git/mingw64/bin/git-credential-manager.exe"

进行配置，注意空格需要转义。

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

设置凭据存储为 Windows Credential Manager：

git config --global credential.credentialStore wincredman

参考资料：

• https://linux.do/t/topic/1592293?u=archmagetony
• https://linux.do/t/topic/933176?u=archmagetony

文章封面(AI):