尽管 Windows 系统在日常工作与学习中被广泛使用，但当前主流的 AI 编程工具（如 Claude Code CLI、CodeX CLI、OpenCode CLI 等）通常对 macOS 或 Linux 环境具有更好的原生支持。因此，对于 Windows 开发者而言，WSL（Windows Subsystem for Linux）已成为构建现代开发环境的必要组件。

然而，WSL 默认将 Linux 发行版安装在系统盘（C 盘）。随着开发依赖和项目文件的不断增加，极易导致系统盘空间告急。为解决这一问题，本文档提供了一套完整的 Windows 11 WSL 部署方案，通过手动导入镜像的方式，将 Ubuntu 子系统安装至自定义的非系统盘目录（例如将其部署至 D:\WSL\ubuntu，并命名为 ubuntu-d）。

此外，为打造稳定、高效且安全的 AI 开发环境，本文档的高级配置部分还包含以下针对性优化：

  • 资源管控：设定 WSL 2 全局内存上限，避免子系统过度占用宿主机资源，保障 Windows 母系统的流畅运行。
  • 网络打通：配置 WSL 与宿主机的网络代理共享，确保顺畅拉取 GitHub 资源及稳定调用 AI CLI 工具的网络接口。
  • DNS 固化：禁用易失效的 DNS 自动生成机制并配置静态 DNS，解决子系统域名解析不稳定导致的间歇性网络异常。
  • 开发终端：采用 Windows Terminal 结合 VS Code 的 WSL 扩展，实现宿主机 UI 与子系统底层运行环境的完美解耦。
  • 环境隔离：通过 direnv 配合虚拟环境，严格隔离 AI 编程助手与 Ubuntu 系统自带的 Python 环境，杜绝系统级依赖被意外篡改或破坏的风险。

第一阶段：启用 WSL 底层功能

在安装之前，必须确保 Windows 系统已开启相关的虚拟化和子系统功能。

  1. 打开终端（管理员权限）：
    右键点击任务栏的 Windows 徽标（开始菜单），选择“终端 (管理员)”或“Windows PowerShell (管理员)”。

  2. 启用核心功能：
    依次执行以下两条命令：

    1
    2
    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
    dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

  3. 安装/更新 WSL 组件并设置默认版本：

    1
    2
    3
    4
    wsl --install --no-distribution --web-download
    # 兼容说明：部分文档会使用 `wsl --update`，但旧版本系统可能不支持
    # wsl --update
    wsl --set-default-version 2

注意：建议在完成上述步骤后重启计算机，以确保所有功能正确加载。

第二阶段：下载并提取 Ubuntu 镜像文件

为实现自定义安装路径，需要手动提取出纯净的根文件系统镜像。

  1. 建立目录：
    在资源管理器中，创建目标安装文件夹 D:\WSL\ubuntu。
  2. 下载并进行第一次解压：
    下载 Ubuntu 安装包（通常为 .tar.gz 格式的打包文件）。下载完成后，首先对该 .tar.gz 文件进行解压。
  3. 定位并重命名 APPX 文件：
    打开解压出来的文件夹，寻找文件名类似 Ubuntu_xxxx.x.x.x_x64.appx 的文件。选中该文件，将其扩展名从 .appx 修改为 .zip。
  4. 第二次解压提取最终镜像：
    使用解压软件对重命名后的 .zip 文件再次进行解压。进入解压后的目录，找到核心目标文件：**install.tar.gz**。
  5. 放置备用：
    将提取出的 install.tar.gz 文件复制或移动到 D:\WSL\ 根目录下备用（最终路径应为 D:\WSL\install.tar.gz）。

第三阶段：导入并安装到 D 盘

将准备好的系统镜像导入到目标文件夹中。

  1. 执行导入命令：
    回到管理员 PowerShell，运行以下命令：

    1
    wsl --import ubuntu-d D:\WSL\ubuntu D:\WSL\install.tar.gz --version 2

  2. 验证安装：
    执行 wsl -l -v，检查名为 ubuntu-d 的子系统是否处于运行（Running）或停止（Stopped）状态，且版本显示为 2。

第四阶段：初始化与基础系统配置

默认导入的子系统以 root 身份登录，且未开启 systemd。需对其进行规范化配置以符合安全最佳实践。

  1. 进入 Ubuntu 子系统：

    1
    wsl -d ubuntu-d

  2. 创建日常使用的普通用户（将 [username] 替换为实际的英文用户名）：

    1
    2
    useradd -m -s /bin/bash [username]
    passwd [username]  # 按提示设置并确认密码

  3. 赋予该用户 sudo 管理权限：

    1
    usermod -aG sudo [username]

  4. 配置默认用户与开启 systemd：
    编辑 WSL 配置文件：

    1
    nano /etc/wsl.conf

在文件中输入以下内容（注意替换用户名）：

1
2
3
4
5
[user]
default=[username]

[boot]
systemd=true

按 Ctrl + O ,然后按 ENTER 回车保存，再按 Ctrl + X 退出。

  1. 重启 WSL 使配置生效：
    在 Windows PowerShell 中完全关闭 WSL，然后重新进入：
    1
    2
    wsl --shutdown
    wsl -d ubuntu-d

再次进入后，系统应已切换为普通用户登录。

第五阶段：全局资源限制与网络 VPN 共享

WSL 2 默认会消耗大量宿主机内存，且在传统 NAT 模式下对宿主机的 VPN 支持不佳。可通过修改 Windows 端的全局配置来解决这些问题。

  1. 在 Windows 系统中，按下 Win + R 键，输入 %USERPROFILE% 回车，打开当前用户的主目录。

  2. 在该目录下新建一个名为 .wslconfig 的文本文件（注意文件名前面的点）。

  3. 使用文本编辑器打开该文件，填入以下推荐配置：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    [wsl2]
    # 限制 WSL 最大使用的内存（建议设置为宿主机总内存的 1/4 到 1/2）
    memory=4GB
    # 限制使用的 CPU 核心数
    processors=2
    # 开启 swap 虚拟内存，避免超出内存时直接崩溃
    swap=8GB
    # 允许从 Windows 本地直接访问 WSL 中运行的网络服务
    localhostForwarding=true

    # 设置共享宿主 VPN 与高级网络功能（Mirrored 模式）
    networkingMode=mirrored
    autoProxy=true
    dnsTunneling=true
    firewall=true

  4. 打开 PowerShell 执行 wsl --shutdown 重启子系统以应用新配置。

第六阶段：禁用 WSL 自动 DNS 与配置静态 DNS

为防止网络解析出现不稳定的情况，建议禁用 WSL 自动生成的 DNS 配置，强制使用稳定可靠的公共 DNS。

首先确保已进入子系统：

1
wsl -d ubuntu-d

  1. 创建 wsl.conf 禁用自动生成（使用追加模式，防止覆盖历史配置）：

    1
    2
    3
    4
    5
    sudo tee -a /etc/wsl.conf > /dev/null << 'EOF'

    [network]
    generateResolvConf = false
    EOF

  2. 删除 WSL 生成的软链接：

    1
    sudo rm -f /etc/resolv.conf

  3. 创建静态 DNS 配置（使用 Google 和阿里 DNS）：

    1
    2
    3
    4
    5
    sudo tee /etc/resolv.conf > /dev/null << 'EOF'
    nameserver 8.8.8.8
    nameserver 8.8.4.4
    nameserver 223.5.5.5
    EOF

  4. 锁定文件防止 WSL 覆盖：

    1
    sudo chattr +i /etc/resolv.conf 2>/dev/null || true

第七阶段：系统更新与软件源优化（可选）

  1. 确保处于 Ubuntu 系统终端中：

    1
    wsl -d ubuntu-d

  2. 备份并替换为国内镜像源（以阿里云为例）：

    1
    2
    3
    sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
    sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list
    sudo sed -i 's@//security.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list

  3. 更新系统软件包：

    1
    sudo apt update && sudo apt upgrade -y

第八阶段：最佳实践交互终端配置（Windows Terminal + VS Code）

在 Windows 11 环境下，与 WSL 交互的最佳实践组合是 Windows Terminal (Windows 终端) 搭配 Visual Studio Code (VS Code) 集成终端，两者分别满足系统级运维与日常编码的需求。

1. Windows Terminal 配置优化

Windows 11 已内置 Windows Terminal，导入 WSL 镜像后，系统会自动检测并在下拉菜单中生成名为 ubuntu-d 的启动配置文件。为提升体验，需进行以下关键配置：

  • 设置默认配置文件：
    打开 Windows Terminal 设置（快捷键 Ctrl + ,），在“启动”选项卡中，将“默认配置文件”从 Windows PowerShell 更改为 ubuntu-d。此后每次打开终端即可直接进入 WSL 环境。
  • 修改默认启动目录（解决跨文件系统性能问题）：
    默认情况下，WSL 会启动在宿主机的 C:\Users\[Windows用户名] 目录下。跨文件系统（Windows NT 到 Linux ext4）的读写存在极大的性能损耗。
    在 Windows Terminal 设置的左侧边栏找到 ubuntu-d 配置文件，在“启动目录”栏中，将其修改为 Linux 系统的原生家目录路径：
    1
    2
    \\wsl.localhost\ubuntu-d\home\[username]

(注意将 [username] 替换为在第四阶段创建的 Linux 用户名)

2. VS Code 与 WSL 的无缝集成工作流

对于实际的编码阶段，推荐直接使用 VS Code 的内置终端，实现 UI 与执行环境的物理隔离。

  • 安装扩展：在 Windows 宿主机打开 VS Code，进入扩展商店搜索并安装微软官方提供的 WSL (原 Remote - WSL) 插件。
  • 无缝唤起：在 Windows Terminal 的 ubuntu-d 环境中，通过 cd 命令进入目标项目目录，随后执行以下命令：
    1
    2
    code .

注：首次执行该命令时，系统会自动在 WSL 内下载并安装 VS Code Server 组件，请保持网络畅通。

  • 环境对齐：Windows 端的 VS Code 将被自动唤起并直接挂载该 Linux 目录。此时在 VS Code 中按下 Ctrl + ` 打开集成终端，该终端已完全置于 WSL 隔离环境内。所有的 Git 提交、npm 构建、Python 执行或 AI CLI 交互均在底层 Linux 环境中高速运行，彻底避免了 Windows 环境变量与 Linux 开发工具链的冲突。

第九阶段：AI CLI 工具与 Python 环境隔离（开发安全最佳实践）

在 WSL 下运行 AI CLI 工具（如 Claude Code, Codex, Gemini 等）调用 Python 时，核心风险不仅在于污染系统级 Python 环境，还包括 AI 可能会意外执行具有破坏性的系统级命令。由于这些工具会继承终端的环境变量（特别是 $PATH），最佳的日常防护实践是：使用 direnv 配合虚拟环境。

此方案可实现“进入目录即自动劫持 Python 路径”。无论 AI 如何调用 python，都将被强制指向该目录下的隔离环境。

  1. 安装 direnv 与虚拟环境支持包：由于 WSL 版 Ubuntu 镜像默认精简了构建虚拟环境的核心模块，需同时安装 python3-venv（自动匹配当前的 Python 3 版本），否则后续构建隔离环境时会报错失败。

    1
    2
    sudo apt update
    sudo apt install direnv python3-venv -y

  2. 安装 direnv：

    1
    sudo apt install direnv

  3. 配置 Shell 钩子（只需执行一次全局配置）：
    在 ~/.bashrc 或 ~/.zshrc 末尾添加钩子，使系统在切换目录时自动检测：

    1
    2
    eval "$(direnv hook bash)" 
    # 若使用的是 zsh，请将末尾的 bash 替换为 zsh

修改完成后，执行 source ~/.bashrc 使其生效。

特别强调：以下步骤 4 必须在每一个新建的或尚未配置过的项目目录中单独执行一次，以确保每个项目都拥有独立且安全的隔离环境。

  1. 在具体的项目目录下设置隔离环境，并授权该目录：
    进入需要配置的开发项目文件夹，创建一个 .envrc 文件并设置 Python 布局：
    1
    2
    3
    cd /path/to/your/project
    echo "layout python python3" > .envrc
    direnv allow .

预期效果：
配置完成后，只要在该特定目录下启动 AI CLI 工具，当前终端的 $PATH 即被劫持。此时执行 python 或 pip 命令，将严格调用该目录下的专属隔离环境，从而完全避开系统级 Python，大幅提升开发环境的安全性和稳定性。