Windows 从 0 搭建 WSL2 原生 AI 开发环境：Codex + Docker + VSCodeWindow

Windows 从 0 搭建 WSL2 原生 AI 开发环境：Codex + Docker + VSCode

这篇是从零开始教程，不依赖任何历史项目。
目标：搭建一套可长期使用的开发环境：工具在 WSL2，代码在 WSL2，Docker 只跑服务。

1. 最终环境长什么样

操作系统：Windows 11
Linux 环境：WSL2 + Ubuntu
IDE：VSCode + Remote - WSL
AI CLI：Codex（可扩展到其他 AI CLI）
容器：Docker Desktop + docker compose
项目目录：~/workspace/<PROJECT_NAME>（WSL Linux 文件系统）

2. 为什么要这样配（核心理由）

性能更稳定：代码放 WSL 的 Linux 文件系统，比 /mnt/c 更适合前端热更新和大量小文件。
环境一致：命令语义接近 Linux 服务器，减少“本地能跑线上不行”。
职责清晰：AI 工具/编译工具在宿主机，Docker 只负责运行服务。
可维护：~/.codex 持久化，关机重启配置不丢。

3. 第一步：安装 WSL2 与 Ubuntu

在 Windows PowerShell（管理员）执行：

wsl --install -d Ubuntu

安装后重启电脑，首次打开 Ubuntu 设置用户名密码。

检查：

wsl -l -v

确保 Ubuntu 是 Version 2。

4. 第二步：安装 Docker Desktop（并启用 WSL 集成）

安装 Docker Desktop。
打开 Docker Desktop -> Settings -> Resources -> WSL Integration。
勾选 Ubuntu 发行版。

在 WSL 终端检查：

docker --version
docker compose version

5. 第三步：安装开发工具（WSL 内）

sudo apt update
sudo apt install -y git curl jq unzip

按需安装 Node（示例用 nvm）：

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node -v
npm -v

Java（可选）：

sudo apt install -y openjdk-17-jdk
java -version

6. 第四步：从 0 配置 Codex CLI（WSL 原生）

安装 Codex：

npm install -g @openai/codex
codex --version

初始化配置目录：

mkdir -p ~/.codex

创建 ~/.codex/config.toml（最小可用模板）：

model_provider = "openai"
model = "gpt-5-codex"
model_reasoning_effort = "high"
personality = "pragmatic"
notify = []

[projects."/home/<user>/workspace"]
trust_level = "trusted"

[mcp_servers.filesystem]
type = "stdio"
startup_timeout_sec = 60
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/<user>/workspace"]

[mcp_servers.context7]
type = "stdio"
startup_timeout_sec = 120
command = "npx"
args = ["-y", "@upstash/context7-mcp@2.1.1"]

[mcp_servers.github]
type = "stdio"
startup_timeout_sec = 60
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.memory]
type = "stdio"
startup_timeout_sec = 60
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]

codex

关键点：WSL 里必须用 npx，不要出现 npx.cmd。

7. 第五步：从 0 创建项目目录与工作区

mkdir -p ~/workspace
cd ~/workspace
mkdir <PROJECT_NAME>
cd <PROJECT_NAME>

如果你要用 worktree：

git init
git checkout -b main
mkdir -p .worktrees/<FEATURE_BRANCH>

8. 第六步：从 0 写 docker-compose（服务化）

在项目根目录创建 docker-compose.yml：

name: app_main

services:
  db:
    image: postgis/postgis:15-3.4
    restart: unless-stopped
    environment:
      POSTGRES_DB: app_db
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
    ports:
      - "5432:5432"
    volumes:
      - app_main_db:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - "6379:6379"

volumes:
  app_main_db:

验证：

docker compose config
docker compose up -d
docker compose ps

9. 第七步：写一键开工 / 收工脚本

创建 scripts/workday-start.sh：

#!/usr/bin/env bash
set -euo pipefail
cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
docker compose config >/dev/null
docker compose up -d
docker compose ps

创建 scripts/workday-stop.sh：

#!/usr/bin/env bash
set -euo pipefail
cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
docker compose down

赋权限：

chmod +x scripts/workday-start.sh scripts/workday-stop.sh

10. 第八步：VSCode 工作方式

在 WSL 终端执行：

cd ~/workspace/<PROJECT_NAME>
code .

确认左下角是 WSL: Ubuntu。

11. 每日标准流程（小白照抄）

开工

wsl -d Ubuntu
cd ~/workspace/<PROJECT_NAME>
bash scripts/workday-start.sh
codex

收工

wsl -d Ubuntu
cd ~/workspace/<PROJECT_NAME>
bash scripts/workday-stop.sh

12. 常见问题排障

12.1 Docker 拉镜像失败（代理）

docker info | grep -E 'HTTP Proxy|HTTPS Proxy|No Proxy'

到 Docker Desktop 检查 Proxies，改为 System 或有效代理后重启。

12.2 Codex/MCP 启动失败

检查 ~/.codex/config.toml：

是否有 npx.cmd（必须没有）
路径是否是 Linux 路径
filesystem MCP 指向的目录是否存在

13. 可直接复制的两条命令

开工：

wsl -d Ubuntu -e bash -lc 'cd ~/workspace/<PROJECT_NAME> && bash scripts/workday-start.sh && code . && codex'

收工：

wsl -d Ubuntu -e bash -lc 'cd ~/workspace/<PROJECT_NAME> && bash scripts/workday-stop.sh'

14. 一句话总结

从 0 搭建时，优先遵守这一条：
代码在 WSL，工具在 WSL，Docker 只跑服务。

这套结构最稳、最通用、最接近生产环境，也最适合 AI CLI 深度参与开发。