AI编程01: WSL2+Claude Code AI开发环境指南 (保姆级·详尽版)

本文档涉及的开源项目速查表

项目/工具	核心作用	GitHub 地址
WSL	Linux 子系统内核	microsoft/WSL
Oh My Zsh	终端美化与管理	ohmyzsh/ohmyzsh
FZF	命令行模糊搜索	junegunn/fzf
Zoxide	智能目录跳转	ajeetdsouza/zoxide
Docker	容器引擎	moby/moby
SDKMAN!	Java/Maven 管理	sdkman/sdkman-cli
uv	极速 Python 管理	astral-sh/uv
NVM	Node.js 版本管理	nvm-sh/nvm
ZCF (CCR)	Claude 逆向/中转工具	UfoMiao/zcf
OpenSpec	AI 开发规范工具	Fission-AI/OpenSpec

---

WSL2 + Ubuntu + Claude Code 全栈开发指南

---

第零部分：从零安装 WSL2 (版本 Ubuntu 22.04)

1. 开启安装命令

1. 在 Windows 任务栏搜索框输入 Powershell。
2. 关键步骤！ 右键点击 "Windows PowerShell"，选择 “以管理员身份运行” 。
3. 在蓝色的窗口中，先输入以下命令查看可用列表（可选）,若提示wsl未安装,不用管直接执行下一条命令：

wsl --list --online

4. 输入以下命令正式安装 Ubuntu 22.04：

wsl --install -d Ubuntu-22.04

5. 重启电脑 6. 重启后继续执行

wsl --install -d Ubuntu-22.04

如果一直下载0%，先取消命令行下载。再去微软的应用里面下载

使用管理员身份打开ubuntu

检查是否是 WSL2

wsl -l -v

如果某发行版版本不是 2，可改成：

wsl --set-version <发行版名> 2

例如：

wsl --set-version Ubuntu-22.04 2

设置以后默认都用 WSL2：

wsl --set-default-version 2

2. 重启与初始化

1. 命令执行完毕后，系统会提示你重启电脑。请立即重启。
2. 重启后，电脑会自动弹出一个黑色窗口，提示 Installing, this may take a few minutes...。
3. 等待片刻，它会让你输入用户名 (Enter new UNIX username) 和密码。

🛑 新手必读：关于密码输入
在 Linux 终端中输入密码时，屏幕上不会显示任何字符（连星星 ****** 也没有）。
这是 Linux 的安全机制。你只管输，输完直接按 回车 (Enter) 即可。

---

第一部分：WSL2 局域网访问优化方案（启用“镜像模式”）

1. 问题概述

在使用 WSL2（Windows Subsystem for Linux, version 2）时，您可能遇到以下情况：

• Windows 主机能够成功地与局域网中的其他设备进行通信（例如，能够ping通IP地址为192.168.1.50的开发板或NAS服务器）。
• 然而，在同一环境下，WSL2环境下的Ubuntu系统却无法通过Ping命令到达上述IP地址，或者无法建立到局域网内数据库的连接。
  这种现象的根本原因在于，默认配置下，WSL2作为一个类似于运行于Windows操作系统之上的虚拟机存在，它位于一个独立的网络子网内（NAT模式），从而导致了WSL2与主机之间在网络层面的隔离。

解决目标

我们的目标是消除这一网络障碍，通过激活微软最新推出的Mirrored Networking（镜像网络）功能，实现WSL2实例与宿主Windows系统共享相同的IP地址。这样不仅简化了网络配置过程，还增强了两者之间的互操作性，使得从WSL2发起的网络请求能够直接利用Windows的网络栈，从而达到更高效、更稳定的局域网访问效果。

2. 准备工作 🛠️

在开始之前，请确保你的系统版本满足要求。

• Windows 版本要求：

• • Win 11 (22H2 或更高)
  • Win 10 (22H2, 内部版本 19045.3754 或更高)

• WSL 版本要求：

• • WSL 版本需 >= 2.0.0

✅ 检查与更新步骤
打开 PowerShell (管理员)，输入以下命令更新 WSL 到最新版：

wsl --update

操作步骤

通过单一配置文件的设置，可实现长期有效的系统配置。

第一步：访问配置文件目录

1. 使用键盘快捷键 Win + R 打开“运行”对话框。
2. 在打开的窗口中输入 %UserProfile% 并按回车确认。
3. 此操作将引导您进入当前用户的主目录（路径通常为 C:\Users\您的用户名）。

• • 提示：建议在此处附上一张截图，展示如何在“运行”对话框中输入 %UserProfile%。

第二步：创建或编辑 .wslconfig 文件

1. 在用户主目录内查找是否存在名为 .wslconfig 的文件。
2. 若不存在该文件，请执行以下操作：

• • 右击空白区域选择“新建”，然后点击“文本文档”。
  • 将新创建的文本文件重命名为 .wslconfig 注意文件名前有一个点，并且确保删除默认的 .txt 扩展名。

3. 如果文件已存在，则右键点击该文件，选择“打开方式”>“记事本”进行编辑。

• • 提示：此处推荐添加一张截图来帮助识别文件资源管理器中的 .wslconfig 文件图标。

第三步：配置核心参数

请将下列代码完整地复制并粘贴到.wslconfig文件中，之后保存更改（使用快捷键 Ctrl+S）。

# WSL 2 核心网络配置
[wsl2]

# 1. 开启镜像模式 (核心)
# 让 WSL 和 Windows 共享同一个网络接口和 IP，彻底解决局域网访问问题
networkingMode=mirrored

# 2. 开启 DNS 隧道
# 解决 VPN 环境下 WSL 无法解析域名的问题，网络更稳定
dnsTunneling=true

# 3. 开启防火墙同步
# 让 Windows 防火墙规则直接保护 WSL，安全不裸奔
firewall=true

# 4. 自动同步代理
# Windows 开了代理/加速器，WSL 自动同步，无需手动 export IP
autoProxy=true

第四步：重启 WSL 生效
回到 PowerShell，彻底关闭运行中的 WSL 实例：

wsl --shutdown

重新打开你的 Ubuntu 终端即可。

4. 验证效果

验证方法 1：查看 IP 地址
在 Ubuntu 中输入：

ip addr

现在的效果：你应该能看到一大堆网卡，且其中包含你 Windows 本机的真实局域网 IP（例如 192.168.1.x）。
(以前的 NAT 模式只能看到一个 172 开头的虚拟 IP)

验证方法 2：Ping 局域网设备
尝试 Ping 你局域网里的路由器或其他电脑：

ping 192.168.1.1

如果能通，恭喜你！问题彻底解决。

5. wsl2配置解析

配置项	中文名	如果不开启	开启后效果
networkingMode=mirrored	镜像网络模式	WSL 是独立 IP，访问不到局域网设备，IPv6 也经常坏。	共享 Windows IP，局域网互通无阻，就像原生 Linux。
dnsTunneling=true	DNS 隧道	开了 VPN 后，WSL 经常连不上网，无法解析域名。	走 Windows 的 DNS 通道，VPN 怎么设，WSL 就怎么走，稳。
firewall=true	防火墙集成	WSL 直接暴露在网络上，容易被攻击，且端口管理混乱。	使用 Windows Defender 统一管理，安全且省心。
autoProxy=true	自动代理	每次开代理都要手动查 Windows IP，然后手动输命令，极其繁琐。	Windows 只要能翻墙/连内网，WSL 自动同步，无感体验。

---

🛠️ 第二部分：极速基础环境 (清华源 + Zsh + Docker)

在 WSL2 (Ubuntu 22.04) 中打造全能、极速、安全的开发环境。
核心特性：安全加固（强制备份）、国产加速（清华源）、终端改造（Zsh）。

1. 基础环境与中文显示支持

1.1 备份并替换清华源
复制以下命令块，在终端一次性执行（利用 sed 命令自动替换，无需手动编辑文件）：

# 1. 备份原始软件源配置
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 2. 替换为清华大学镜像源 (正则替换)
sudo sed -i "s@http://.*archive.ubuntu.com@https://mirrors.tuna.tsinghua.edu.cn@g" /etc/apt/sources.list
sudo sed -i "s@http://.*security.ubuntu.com@https://mirrors.tuna.tsinghua.edu.cn@g" /etc/apt/sources.list

# 3. 更新软件包列表
sudo apt update

1.2 安装依赖与中文支持

# 1. 更新系统并安装必备工具
sudo apt upgrade -y
sudo apt install -y curl git unzip zip build-essential \
    language-pack-zh-hans fontconfig gnupg lsb-release

# 2. 生成中文 Locale (防止中文乱码)
sudo locale-gen zh_CN.UTF-8

2. 终端改造：Zsh + FZF 交互搜索

2.1 安装 Zsh & Oh My Zsh

# 安装 zsh
sudo apt install -y zsh

# 安装 Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

如果是用的v2rayN,则开启v2rayN tun后如果一直卡在https握手

github.com/2dust/v2ray…

7.19+的v2rayN修复了tun问题，mtu保持默认9000，否则可能会异常。

提示：安装过程中如果询问是否将 Zsh 设为默认 Shell，请输入 Y 并回车。

2.2 安装 FZF & Zoxide

• FZF: 命令行模糊搜索神器。
• Zoxide: 智能目录跳转（比 cd 更快）。
• (可选) 安装ripgrep、fd搜索.

# 安装 FZF
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install
# (一路按 y 确认)

# 安装 Zoxide (智能跳转)
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

2.3 配置插件 (.zshrc)

# 下载高亮和建议插件
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

编辑配置文件：
输入 nano ~/.zshrc，找到对应位置修改，或者直接在文件底部添加：

# 1. 修改 plugins 这一行，启用插件
plugins=(git zsh-syntax-highlighting zsh-autosuggestions extract z)

# 2. 在文件底部添加以下内容
eval "$(~/.local/bin/zoxide init zsh)"
export LANG=zh_CN.utf8
export LC_ALL=zh_CN.utf8
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh

保存并刷新：

source ~/.zshrc

3. 部署 Docker (纯清华源安装)

3.1 安装 Docker

# 添加 Key 和 源
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

3.2 配置加速与权限

# 免 Sudo (把当前用户加入 docker 组)
sudo usermod -aG docker $USER

# 镜像加速 (DaoCloud + Huecker)
sudo mkdir -p /etc/docker
echo '{"registry-mirrors": ["https://docker.1ms.run"]}' | sudo tee /etc/docker/daemon.json

# 重启 Docker 服务
sudo service docker start

read tcp [2408:8459:...]:...: read: connection reset by peer：这个 2408 开头的地址是IPv6地址，说明 Docker 客户端尝试通过 IPv6 发起连接，但连接被对端重置了。

fix:

{
    "ipv6": false,
    "registry-mirrors": [
        "https://docker.1ms.run"
    ]
}

sudo service docker restart

---

💻 第三部分：多版本环境管理实战 (Python/Java/Node)

Python 环境管理：uv

选择 uv 的理由

在传统的 Python 开发流程中，开发者通常需要使用 pip 来安装包，通过 virtualenv 或 venv 创建虚拟环境，并利用 pyenv 来管理不同的 Python 版本。而 uv 作为一个基于 Rust 编写的工具，集成了上述所有功能，并且在执行速度上相比传统方法有显著提升，据测试显示，其性能可提高 10 至 100 倍。

1.1 安装 uv

# 1. 安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 刷新环境变量 (必须执行)
source ~/.zshrc

# 3. 验证安装
uv --version

1.2 第一步：管理 Python 版本

# 查看所有可安装的 Python 版本
uv python list

# 安装 Python 3.12 (最新稳定版)
uv python install 3.12

# 安装 Python 3.10 (老项目常用)
uv python install 3.10
# 设置默认python为3.12
uv python install --default 3.12

1.3 第二步：小白实战——创建一个新项目 (推荐方式)
uv 推荐使用“项目化”的管理方式（类似 Node.js 的 npm init），这比传统的手动创建 venv 更科学。
场景：我要写一个爬虫，需要 python 3.12 和 requests 库。

1. 创建项目目录：

mkdir my-spider
cd my-spider

2. 初始化项目：
这会创建一个 pyproject.toml 文件。

uv init

3. 指定 Python 版本：
告诉 uv 这个项目要用 3.12。

uv python pin 3.12

4. 添加依赖包：
不用激活虚拟环境，直接加！uv 会自动创建虚拟环境并安装包。

uv add requests

5. 运行脚本：

# 直接运行 (假设你写了个 hello.py)
uv run hello.py

1.4 第三步：老鸟实战——传统虚拟环境 (兼容模式)
如果你还是习惯手动 source activate，uv 依然支持，且速度飞快。

# 1. 创建名为 .venv 的虚拟环境
uv venv --python 3.10

# 2. 激活环境
source .venv/bin/activate

# 3. 极速安装包 (注意是用 uv pip)
uv pip install numpy pandas flask

2. Java 多版本管理 (SDKMAN)

目标：同时拥有 Java 8 (老项目) 和 Java 21 (LTS 新标准)。

2.1 安装 SDKMAN

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

2.2 安装与切换

# --- 安装阶段 ---
# 安装 Java 8
sdk install java 8.0.432-zulu

# 安装 Java 21
sdk install java 21.0.4-zulu

# 安装 Maven
sdk install maven 3.6.2
sdk install maven 3.8.2

# --- 使用阶段 ---
# 1. 查看当前版本
java -version

# 2. 临时切换到 Java 8 (仅当前窗口有效)
sdk use java 8.0.432-zulu

# 3. 设置 Java 21 为系统默认 (永久生效)
sdk default java 8.0.432-zulu

3. Node.js 多版本管理 (NVM)

目标：同时拥有 Node 22 (LTS) 和 Node 24 (最新)。

3.1 安装 NVM (v0.40.1)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc

3.2 安装与切换

# --- 安装阶段 ---
# 安装 LTS (v22)
nvm install 22
# 安装最新版 (v24)
nvm install 24

# --- 使用阶段 ---
# 1. 切换到 Node 22 开发公司项目
nvm use 22
node -v  # 输出 v22.x.x

# 2. 设置默认版本
nvm alias default 22

---

🤖 第四部分：Claude Code + iFlow 白嫖实战 (CCR UI篇)

核心原理：

• Claude Code: Anthropic 官方推出的强大命令行 AI 编程工具。
• CCR (Claude Code Relay) : 一个协议中转工具，该工具能够将遵循OpenAI协议的请求转换为符合Anthropic标准的格式，进而使得用户能够利用Claude Code进行操作。

4.1 获取 iFlow Key 🎫

1. 登录 iFlow 官网 (或其他官网地址)。
2. 创建令牌，复制 sk- 开头的 Key。
3. 牢记 API 地址: https://apis.iflow.cn/v1 (⚠️注意：必须要有 /v1 后缀)。

4.2 安装并启动 CCR 🛠️

Claude Code node 方式安装

# 安装cc
npm install -g @anthropic-ai/claude-code

1. 安装 ZCF (包含 CCR,可以简化配置过程，跟着提示走就行)
   在终端输入：

npx zcf

• • 语言选择：简体中文。
  • 如果提示安装 Claude Code，选 Y。
  • 注意：在 ZCF 的 API 配置环节，可以直接跳过或随便选，因为我们马上要用 CCR 的网页版来精细配置。

2. 启动 CCR 后台
   在终端直接输入：

ccr

终端会显示：CCR is running on http://127.0.0.1:3456

4.3 在浏览器中配置api

1. 打开配置页面
   切换到 Windows 的浏览器（Chrome/Edge），访问：
   👉 http://127.0.0.1:3456
2. 添加渠道 (Add Provider)
   在网页界面中操作：

• • 点击 "Add Provider" (添加渠道)。
  • Type (类型) : 选择 OpenAI Compatible (兼容协议)。
  • Name (名称) : 填 xxx-api (方便自己看)。
  • Base URL: 填 https://apis.xxx.cn/v1
  • API Key: 粘贴你的 sk-xxxxxxxx。
  • Model Mapping (模型映射) :

• • • Original Model (原始模型): claude-sonnet-4-5-20250929
    • Target Model (目标模型): claude-sonnet-4-5-20250929。

• • 点击 "Save" (保存) 并确保开关是 On (绿色) 。

4.4 启动 Claude Code

1. 保持 CCR 运行 (不要关闭刚才运行 ccr 的终端窗口)。
2. 打开新终端：在 Windows Terminal 顶部点击 + 号，新开一个 Ubuntu 标签页。
3. 运行 Claude：
   输入：

claude

4. 验证：输入 hi。如果收到回复，说明 CCR UI 配置成功！ 🎉

---

第五部分：Claude Code + OpenSpec 工程化开发实战

核心理念：Spec-First (规范驱动开发)
正确的工程化流程应该是：初始化项目认知 -> 建立规范 -> 设计文档 -> 生成代码。

• OpenSpec: Fission-AI/OpenSpec (规范/图纸)

5.1 准备工作

在 Ubuntu 终端中安装 OpenSpec：

npm install -g @fission-ai/openspec@latest

5.2 实战演示：开发一个“待办事项 API”

请严格按照以下顺序操作，这是让 AI “不犯傻”的关键。

第一步：创建目录与启动 Claude

mkdir todo-api && cd todo-api
# 启动 Claude Code
claude

第二步：Claude 初始化 (关键步骤!) 🔑

进入 Claude 对话界面后，首先输入以下指令。这一步会生成 CLAUDE.md，让 Claude 记住这个项目该怎么跑、怎么测。

输入指令：
/init

Claude 会询问你几个问题，请根据项目情况回答（以 Python FastAPI 项目为例）：

• Build command: uv build (或者留空)
• Test command: uv run pytest
• Lint command: uv run ruff check .

💡 为什么要先做这步？
CLAUDE.md 是 Claude 的“长期记忆”。不先做这一步，后续它写完代码不知道怎么验证，容易产生 Bug。

第三步：OpenSpec 初始化 🏗️

Claude 初始化完成后，在对话框中告诉它初始化 OpenSpec 结构。

输入指令：
"请执行 openspec init 命令，初始化工程化文档结构。"

Claude 会执行命令，你的项目目录下会出现 .openspec/ 文件夹，里面包含了 spec.md (设计文档模板)。

第四步：PDCA 循环开发 (核心流程) -- 新版可能变动较大，以官方github为准

现在，我们进入正式的开发循环：

1. Proposal (提案/需求)
告诉 Claude 你想做什么：

"我想开发一个基于 Python FastAPI + SQLite 的待办事项服务，使用 uv 管理依赖。请帮我构思一下。"

2. Spec (生成设计文档)
不要让它直接写代码！要求它先写文档：

"请根据上述需求，更新 .openspec/spec.md 文件。
我需要包含：

1. 项目目录结构树
2. 数据模型 (Pydantic)
3. API 接口定义 (GET /todos, POST /todos)"

3. Review (人工审查)
Claude 修改完文档后，你输入：

"读取 .openspec/spec.md 让我检查一下。"

• 人工介入点：你发现它漏了“删除任务”的接口？
• 修正：告诉它 "在 spec 中补充一个 DELETE 接口"，而不是直接改代码。

4. Execute (执行编码)
文档确认无误后，下达最终指令：

"Spec 文档已确认。请读取 CLAUDE.md 中的配置，并根据 spec.md 的定义，初始化项目文件并编写所有代码。"

5. Verify (验证)
因为我们在第二步配置了 /init，你可以直接说：

"运行测试，确保所有接口正常工作。"

📝 附录：常用命令速查表

场景	命令	说明
启动中转	ccr	每次写代码前必须先运行这个！
写代码	claude	需要新开一个窗口运行
Java 版本	java -version	检查当前 Java 版本
Maven 版本	mvn -v	检查当前 Maven 版本
WSL 重启	wsl --shutdown	(PowerShell中执行) 重启 WSL
Python	uv run hello.py	运行 Python 脚本
清理 Token	/compact	在 Claude 对话框中输入，压缩上下文省钱

vscode 连接wsl, 之后从命令行终端打开code .就会自动连接，完美适配wsl2

✅ 最终验证 Checklist

1. FZF: 按 Ctrl+R 能弹出历史命令搜索框。
2. Docker: docker run hello-world 正常运行且拉取速度快。
3. UV:

• • uv python list 能列出版本。
  • mkdir test && cd test && uv init && uv run hello.py 能成功运行。

4. Java: sdk use java 8.0.432-zulu 后 java -version 变更为 1.8。
5. Node: nvm use 22 后 node -v 变更为 v22。