Windows安装WSL2教程：Ubuntu迁移与Docker环境配置

1. 为什么 Windows 开发者需要 WSL2Ubuntu 迁移与 Docker 环境配置的真实痛点如果你在 Windows 上写代码大概率遇到过这些场景项目依赖一堆 Linux 工具链make、gcc、bash脚本在 PowerShell 里跑不起来Docker Desktop 装了又卸、卸了又装容器挂载 Windows 目录时文件 IO 慢到怀疑人生团队里别人用 Mac 一条命令搞定的事你得折腾半天环境变量。WSL2Windows Subsystem for Linux 2就是为解决这类问题而生的——它让你在 Windows 上跑一个完整的 Linux 内核Ubuntu 发行版、Docker 引擎、Python/Node.js 工具链都能原生运行同时还能和 Windows 文件系统互通。这篇文章面向的是需要在 Windows 上搭建稳定 Linux 开发环境的开发者尤其是做 AI 应用、多智能体项目、容器化部署的同学。我会把整个流程拆成可复制的步骤从 PowerShell 检查系统版本、安装 WSL2 和 Ubuntu 发行版到把发行版迁移到非系统盘比如 D 盘再到配置 Docker 环境、验证 Ubuntu 与 Docker 运行状态。每一步都给出具体命令和配置片段你跟着敲就能跑通。先说清楚 WSL2 和 WSL1 的区别这决定了你后面 Docker 能不能用。WSL1 是系统调用翻译层没有真实 Linux 内核Docker 跑不了WSL2 用的是轻量级虚拟机 真实 Linux 内核支持 systemd、Docker、GPU 直通。所以只要你的目标是 Docker 或 AI 工具链必须用 WSL2。检查方式很简单在 PowerShell 里执行wsl -l -v看 VERSION 列是不是 2。另一个常见痛点是发行版默认装在 C 盘。Ubuntu 加上 Docker 镜像、Python 虚拟环境、Node 的 node_modules几十 GB 很快就吃满系统盘。所以这篇教程会把「迁移发行版到 D 盘」作为核心步骤之一用wsl --export和wsl --import完成搬迁而不是让你重装。迁移后原来的用户名、已装的包、项目文件都保留只是存储位置变了。还有 Docker 的接入方式。很多人第一反应是在 Ubuntu 里apt install docker.io然后在 WSL2 里跑 dockerd。这条路能走通但维护成本高每次 WSL 重启要手动起服务和 Windows 侧的 Docker Desktop 抢资源。更稳的方案是用 Docker Desktop 的 WSL Integration让 Ubuntu 里的docker命令直接连到 Docker Desktop 管理的引擎上。这样 Windows 和 WSL 共用一套镜像缓存容器挂载 Linux 文件系统性能也好。下面会详细写这个配置。最后提一下目录结构。项目代码放/home/你的用户名/projects还是/mnt/c/projects性能差距很大。/mnt/c走的是 9P 文件协议跨系统调用开销高Git 操作和 Docker 挂载都会变慢。放在 WSL 自己的 ext4 文件系统里IO 性能接近原生 Linux。这个习惯从第一天就养成后面省很多事。2. TaoToken 前置准备为 WSL2 里的 AI 开发工具链配好模型接入WSL2 环境搭好之后你大概率会往里装 Claude Code、Cline、Codex 这类 AI 编码工具。这些工具需要一个稳定的模型 API 入口TaoToken 就是干这个的——它提供统一的 API 网关兼容 Anthropic 和 OpenAI 的接口格式你拿到一个 Key 就能在多个工具里复用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。为什么要在 WSL2 教程里提前讲这个因为很多 AI 工具的配置文件路径和 WSL 环境强相关。比如 Claude Code 在 Linux 下的配置目录是~/.claude/Codex 的auth.json在~/.codex/Cline 的 MCP 配置在 VS Code 的设置里。如果你等装完工具再回头找 Key容易在环境变量和配置文件之间来回折腾。提前把 Key 准备好后面配置就是填空。具体操作打开浏览器访问 https://taotoken.net/api-keys 注册后创建一个 API Key。这个 Key 只在创建时显示一次复制下来存到安全的地方。然后在 WSL2 的 Ubuntu 里你可以把它写进 shell 配置文件比如~/.bashrc或~/.zshrcexport TAOTOKEN_API_KEYsk-你的实际Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY这样 Claude Code 启动时会自动读取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY不用每次手动传参。注意ANTHROPIC_BASE_URL后面不要加/v1TaoToken 的网关会自动处理路径。如果你用的是 OpenAI 兼容的工具把OPENAI_BASE_URL设成https://taotoken.net/api即可。模型 ID 怎么填TaoToken 支持 Claude 系列和 GPT 系列具体可用的模型列表在文档里查 https://taotoken.net/doc 。常见的比如claude-sonnet-4-20250514、gpt-4o这些。在 Claude Code 里通常不用手动指定模型它会用默认的在 Cline 或 Codex 里需要在配置里写 Model ID。记住三件套Base URL、API Key、Model ID缺一不可。如果你打算长期在 WSL2 里跑编码 Agent可以考虑 Coding Plan额度更划算 https://taotoken.net/coding-plan 。对于只是偶尔验证模型效果的情况用模型对话页面直接测就行 https://taotoken.net/models 。控制台在 https://taotoken.net/console 可以看用量和余额。有一点要提醒TaoToken 是合规的 API 接入服务不是让你绕过什么限制。它的价值在于统一入口、简化多工具配置、提供稳定的调用链路。你在 WSL2 里配好环境变量后所有走 Anthropic 或 OpenAI 协议的工具都能直接复用不用每个工具单独填一遍。3. 可复制配置PowerShell 安装 WSL2、迁移 Ubuntu 到 D 盘、接入 Docker这一节是全文的核心操作区所有命令都可以直接复制。我按顺序拆成四步检查系统、安装 WSL2 与 Ubuntu、迁移发行版、配置 Docker Integration。每步都给出预期输出你对照着看就知道有没有跑对。3.1 检查系统版本与 WSL 支持情况以管理员身份打开 PowerShell。先看 Windows 版本winverWindows 11 全部支持 WSL2。Windows 10 需要 Version 2004 以上、Build 19041 以上。如果版本太低先去 Windows Update 升级。然后查看可安装的发行版列表wsl --list --online这会列出 Microsoft 商店里支持的发行版比如 Ubuntu、Ubuntu-22.04、Ubuntu-24.04 等。如果你看到wsl命令不存在说明 WSL 功能还没启用执行wsl --install --no-distribution这条命令会启用 WSL 和虚拟机平台功能然后提示你重启。重启后再继续。3.2 安装 Ubuntu 发行版并指定安装位置默认wsl --install Ubuntu会把发行版装在 C 盘。我们直接指定到 D 盘避免后续迁移wsl --install Ubuntu-24.04 --name Ubuntu-Dev --location D:\WSL参数说明Ubuntu-24.04是发行版名称--name Ubuntu-Dev是注册名后面wsl -d用这个--location D:\WSL是安装目录。执行后会自动下载并注册默认使用 WSL2。安装完成后关闭 PowerShell 再重新打开然后启动wsl -d Ubuntu-Dev第一次启动会要求创建 Linux 用户Enter new UNIX username: yourname New password: Retype new password:密码输入时不显示字符正常现象。完成后你会看到yournameDESKTOP:~$提示符。确认版本wsl -l -v输出应该是NAME STATE VERSION * Ubuntu-Dev Running 2VERSION 是 2 就对了。3.3 迁移已有发行版到 D 盘如果你已经装在 C 盘如果你之前已经装了 Ubuntu 在 C 盘不想重装用导出再导入的方式迁移。先关闭 WSLwsl --shutdown导出为 tar 文件wsl --export Ubuntu-Dev D:\WSL\ubuntu-backup.tar注销原发行版wsl --unregister Ubuntu-Dev从 tar 文件导入到新位置wsl --import Ubuntu-Dev D:\WSL\Ubuntu-Dev D:\WSL\ubuntu-backup.tar --version 2导入后默认用户会变成 root需要恢复你的普通用户。进入发行版wsl -d Ubuntu-Dev编辑/etc/wsl.conf[user] defaultyourname把yourname换成你原来的用户名。保存后退出在 PowerShell 里执行wsl --shutdown再重新进入就恢复普通用户了。3.4 配置 wsl.conf 与 Docker Desktop Integration在 Ubuntu 里创建或编辑/etc/wsl.conf加入以下内容[boot] systemdtrue [interop] enabledtrue appendWindowsPathtrue [network] generateResolvConftruesystemdtrue让 WSL2 支持 systemd 服务管理Docker 和很多工具依赖它。改完后在 PowerShell 执行wsl --shutdown重启生效。接下来装 Docker Desktop。去官网下载 Windows 版安装包安装时勾选「Use WSL 2 instead of Hyper-V」。安装完成后打开 Docker Desktop进入 Settings → Resources → WSL Integration开启「Enable integration with my default WSL distro」在「Enable integration with additional distros」里勾选你的Ubuntu-DevApply Restart。然后在 Ubuntu 里验证docker version如果能看到 Client 和 Server 两段信息说明接入成功。再跑docker run hello-world输出Hello from Docker!就通了。3.5 配置 AI 编码工具的 settings 片段以 Claude Code 为例在 Ubuntu 里创建~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key } }如果你用 Cline 的 MCP 配置在 VS Code 的settings.json里加{ cline.mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }Codex 的auth.json放在~/.codex/auth.json{ api_key: sk-你的实际Key, base_url: https://taotoken.net/api }三件套齐了Base URL、Key、Model ID。Model ID 在工具配置里单独填比如claude-sonnet-4-20250514。4. 验证请求与成功结果确认 Ubuntu、Docker、模型调用都跑通配置写完不算完得验证每一层都正常工作。这一节给出具体的检查命令和预期输出你照着跑一遍哪里断了就知道问题出在哪。4.1 验证 WSL2 与 Ubuntu 运行状态在 PowerShell 里wsl -l -v预期输出NAME STATE VERSION * Ubuntu-Dev Running 2STATE 是 RunningVERSION 是 2。如果 STATE 是 Stopped执行wsl -d Ubuntu-Dev启动。进入 Ubuntu 后检查内核版本uname -r应该看到类似5.15.90.1-microsoft-standard-WSL2的输出带microsoft-standard-WSL2就说明是 WSL2 内核。检查 systemd 是否生效systemctl is-system-running输出running或degraded都算正常degraded 通常是某些非关键服务没起来不影响 Docker。4.2 验证 Docker 引擎与容器运行在 Ubuntu 里docker version预期看到 Client 和 Server 两段。Server 段的Server Version应该是 Docker Desktop 管理的版本号。如果只看到 Client 没有 Server说明 WSL Integration 没开回 Docker Desktop 设置里检查。docker info | grep -i operating system输出Operating System: Docker Desktop说明连的是 Docker Desktop 的引擎。跑一个真实容器docker run --rm alpine echo WSL2 Docker OK输出WSL2 Docker OK就通了。再验证挂载性能cd ~/projects docker run --rm -v $(pwd):/workspace alpine ls /workspace能列出你项目目录里的文件说明挂载正常。4.3 验证模型 API 调用在 Ubuntu 里用 curl 测 TaoToken 的接口curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复WSL2环境就绪}] }如果返回 JSON 里包含content字段和模型回复说明 Key 和 Base URL 都对了。返回 401 就是 Key 错了返回 404 检查 Base URL 有没有多写/v1。如果你装了 Claude Code直接运行claude然后输入一句「列出当前目录文件」能正常返回就说明工具链通了。4.4 验证项目目录与文件系统确认项目放在 WSL 文件系统里df -h ~输出里Filesystem应该是/dev/sdX挂载点是/说明是 ext4。如果是/mnt/c下的路径df -h会显示 9p 文件系统性能差。创建测试项目mkdir -p ~/projects/test-app cd ~/projects/test-app git init echo # test README.md git add . git commit -m initGit 操作流畅无卡顿说明文件系统正常。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照这一节收集的是 WSL2 Docker AI 工具链配置过程中最容易撞上的报错。每个都给出原因和修复命令你对着自己的终端输出找。5.1 401 UnauthorizedAPI Key 没生效报错长这样{error:{type:authentication_error,message:invalid x-api-key}}原因通常是三种Key 复制时带了空格、环境变量没 source、配置文件路径不对。检查echo $ANTHROPIC_API_KEY如果输出为空说明~/.bashrc没生效执行source ~/.bashrc。如果输出有值但还报 401检查 Key 是否完整有没有换行符。在 TaoToken 控制台重新生成一个 Key 试试 https://taotoken.net/api-keys 。Claude Code 的 settings.json 路径是~/.claude/settings.json不是~/.config/claude/。确认文件存在cat ~/.claude/settings.json5.2 local proxy failedDocker Desktop 代理冲突报错error during connect: Get http://%2F%2F.%2Fpipe%2FdockerDesktopLinuxEngine/v1.xx/version: open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.或者Cannot connect to the Docker daemon at unix:///var/run/docker.sock.原因Docker Desktop 没启动或者 WSL Integration 没开。先在 Windows 侧确认 Docker Desktop 托盘图标是运行状态。然后在 Docker Desktop 设置里检查 WSL Integration 是否勾选了你的发行版。如果还不行在 PowerShell 里wsl --shutdown等几秒再启动 Docker Desktop然后重新进 WSL。5.3 reading choices模型返回格式解析失败报错Error reading choices: unexpected end of JSON input或者failed to parse response: invalid character looking for beginning of value这通常是 Base URL 配错了请求打到了 HTML 页面而不是 API 端点。检查ANTHROPIC_BASE_URL或OPENAI_BASE_URL是不是https://taotoken.net/api不要带/v1不要带尾部斜杠。用 curl 直接测curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/messages返回 401 或 405 说明端点存在返回 404 说明路径错了。5.4 OAuth 报错Claude Code 登录方式冲突报错OAuth error: invalid_grant或者 Claude Code 启动时卡在浏览器登录。原因是你同时配了 OAuth 登录和 API Key。Claude Code 优先走 OAuth如果之前登录过会忽略环境变量。解决删除 OAuth 凭证rm -rf ~/.claude/credentials.json然后确保~/.claude/settings.json里的env段有ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。重新启动claude它应该直接用 API Key 认证。5.5 wsl --import 后默认用户变 root迁移后进入 Ubuntu 发现提示符是rootDESKTOP:~#。修复编辑/etc/wsl.conf[user] defaultyourname保存后 PowerShell 执行wsl --shutdown重新进入。如果/etc/wsl.conf不存在就新建。5.6 Docker 挂载 /mnt/c 路径权限错误报错Permission denied或者容器里看不到文件。原因/mnt/c的权限模型和 Linux 不同Docker 挂载时 UID/GID 映射有问题。解决把项目移到~/projects用 WSL 文件系统路径挂载。如果必须挂载 Windows 目录加:cached或:delegated参数docker run --rm -v /mnt/c/projects:/workspace:cached alpine ls /workspace但性能还是不如 ext4长期项目建议迁移。6. 在 WSL2 里跑 AI 编码 AgentTaoToken 接入与长期环境维护环境跑通之后接下来就是日常使用。这一节讲怎么把 TaoToken 接入到常见的 AI 编码工具里以及 WSL2 环境的长期维护习惯。Claude Code 的接入最简单。确保~/.claude/settings.json里有{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key } }然后在项目目录里直接运行claude。它会读取当前目录的代码上下文你可以让它改 bug、写测试、重构。实测下来WSL2 里的文件监听比 Windows 原生快很多Claude Code 扫描项目文件几乎无延迟。如果你用 Cline 或 Roo Code 这类 VS Code 插件配置 MCP Server 指向 TaoToken。在 VS Code 的settings.json里加{ cline.mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这样 Cline 就能通过 MCP 协议调用 TaoToken 的模型能力。注意 MCP Server 不要直连生产数据库只做模型调用。Codex 的配置在~/.codex/auth.json{ api_key: sk-你的实际Key, base_url: https://taotoken.net/api }Model ID 在 Codex 的配置文件里单独指定比如claude-sonnet-4-20250514或gpt-4o。三件套确认Base URL、Key、Model ID。长期维护方面几个习惯能省很多事。第一定期更新 WSL 内核wsl --update第二Ubuntu 里的包定期升级sudo apt update sudo apt upgrade -y第三Docker 镜像清理docker system prune -a第四项目目录固定在~/projects不要散落在/mnt/c。第五/etc/wsl.conf里的systemdtrue保持开启很多工具依赖它。如果你需要更细的接入文档TaoToken 的文档页有各工具的配置示例 https://taotoken.net/doc 。模型列表和可用性在 https://taotoken.net/models 查。控制台看用量 https://taotoken.net/console 。API Key 管理 https://taotoken.net/api-keys 。长期编码建议用 Coding Plan https://taotoken.net/coding-plan 。最后说一个实际经验WSL2 的.wslconfig文件可以限制内存和 CPU避免 WSL 吃满宿主机资源。在 Windows 用户目录下创建C:\Users\你的用户名\.wslconfig[wsl2] memory8GB processors4 swap2GB改完wsl --shutdown生效。这样 WSL2 最多用 8GB 内存不会把 Windows 拖卡。对于 16GB 内存的机器这个配置比较均衡。