Codex 工程化落地指南 02：Windows 11、WSL2 与 Codex 环境搭建

码东

339人浏览 · 2026-07-22 14:24:44

码东 · 2026-07-22 14:24:44 发布

一：教程定位 🎯

Codex 能否稳定完成开发任务，很大程度上取决于本地开发环境是否统一、可重复、可测试。

在 Windows 11 中，常见的开发环境问题包括：

Node.js 安装在 Windows，项目却运行在 WSL Git 在 Windows 和 WSL 中分别使用不同账号项目放在 C 盘，Linux 工具访问速度较慢 Docker 同时安装在 Windows 和 WSL，命令发生冲突 Python 包全部安装到系统环境 Codex CLI 找不到项目使用的 Node、Python 或 Docker VS Code 打开的不是 WSL 工作区终端、IDE 和 Codex 使用不同的配置文件

本篇的目标，是建立一套统一结构：

Windows 11 ├── ChatGPT 桌面应用 / Codex ├── VS Code ├── Windows Terminal └── Docker Desktop │ │ WSL2 Integration ▼ WSL2 Ubuntu ├── Git ├── Node.js / npm ├── Python / venv ├── Codex CLI ├── Docker CLI └── 项目源码

Codex CLI 官方支持 Windows 11 通过 WSL2 使用；Docker Desktop 官方也建议在 WSL2 开发时把项目代码存放在 Linux 文件系统中，并通过 WSL Integration 使用 Docker。([GitHub][1])

二：教程信息 📋

目标读者： Codex 初学者、Windows 开发人员 预计时长： 1.5～2 小时 难度等级： ★☆☆ 操作系统： Windows 11 推荐 Linux： Ubuntu WSL2

三：学习目标 📌

完成本篇后，你应该能够：

安装并检查 WSL2

安装 Ubuntu 开发环境

在 WSL 中配置 Git

使用 NVM 管理 Node.js

配置 Python 虚拟环境

在 WSL 中安装 Codex CLI

安装 Codex IDE 扩展

安装并使用 Windows 桌面应用中的 Codex

配置 Docker Desktop WSL2 集成

在 VS Code 中打开 WSL 项目

完成一次 Codex 环境验证

排查 Windows 与 WSL 路径、权限和命令冲突

第一部分：环境架构设计

四：推荐架构 🏗️

推荐将工具按以下方式安装。

安装在 Windows

Windows Terminal

Visual Studio Code

ChatGPT 桌面应用

Docker Desktop

浏览器

安装在 WSL2 Ubuntu

Git

Node.js

npm

Python

pip

Codex CLI

项目依赖

项目源码

通过 Docker Desktop 提供

docker

docker compose

Docker Engine

BuildKit

容器网络

镜像存储

这样可以让：

Codex CLI Git Node.js Python Docker CLI 项目源码

全部运行在接近 Linux 服务器的环境中。

五：为什么不建议全部装在 Windows 🤔

完全使用 Windows 原生环境并非不可行，但在以下项目中容易遇到差异：

Docker 项目

Linux Shell 脚本

Node.js 后端

Python 后端

Java 微服务

Kubernetes 与 Helm

CI/CD 脚本

依赖 chmod、grep、sed、awk 的项目

典型问题包括：

⚠️ 注意：

路径分隔符不同

文件权限不同

Shell 命令不同

换行符不同

软链接行为不同

大小写敏感性不同

开发环境和 Linux 服务器不一致

WSL 可以直接在 Windows 上运行 Linux 工具和 Bash 命令，不需要维护完整传统虚拟机。Microsoft 当前为 Windows 11 提供了 wsl --install 一键安装方式。([Microsoft Learn][2])

第二部分：安装和检查 WSL2

六：安装前检查 🔍

按下：

Win + R

输入：

winver

确认操作系统为 Windows 11。

然后打开任务管理器：

任务管理器 → 性能 → CPU

确认：

虚拟化：已启用

如果显示未启用，需要进入 BIOS/UEFI 开启：

Intel VT-x AMD-V SVM Mode Virtualization Technology

不同电脑名称可能不同。

七：安装 WSL ⚙️

以管理员身份打开 PowerShell：

wsl --install

该命令会：

启用 WSL 组件

启用虚拟机平台

安装 WSL 内核

默认安装 Ubuntu

执行完成后重启 Windows。Microsoft 官方当前推荐通过该命令安装 WSL。([Microsoft Learn][2])

如果只显示帮助信息，先查看可用发行版：

wsl --list --online

安装 Ubuntu：

wsl --install -d Ubuntu

如果下载停在 0.0%：

wsl --install --web-download -d Ubuntu

八：更新 WSL 🔄

重新启动后打开普通 PowerShell：

wsl --update

设置默认使用 WSL2：

wsl --set-default-version 2

查看发行版：

wsl --list --verbose

预期：

  NAME      STATE     VERSION
* Ubuntu    Stopped   2

如果 Ubuntu 显示版本 1：

wsl --set-version Ubuntu 2

设置默认发行版：

wsl --set-default Ubuntu

九：初始化 Ubuntu 🚀

从开始菜单打开：

Ubuntu

首次启动时需要创建：

Linux 用户名

Linux 密码

例如：

Username: developer

设置密码时终端不会显示字符，这是正常现象。

⚠️ 注意：

该用户不是 Windows 用户

该密码不是 Windows 登录密码

该用户将拥有自己的 Linux Home 目录

进入后检查：

whoami
pwd
uname -a

预期目录类似：

/home/developer

十：更新 Ubuntu 软件包 📦

执行：

sudo apt update
sudo apt upgrade -y

安装基础工具：

sudo apt install -y \
  git \
  curl \
  wget \
  ca-certificates \
  build-essential \
  unzip \
  zip \
  jq \
  tree \
  ripgrep \
  python3 \
  python3-pip \
  python3-venv

检查：

git --version
curl --version
python3 --version
jq --version
rg --version

第三部分：项目目录设计

十一：项目应该放在哪里 📁

✅ 推荐： /home/developer/projects

创建目录：

mkdir -p ~/projects
cd ~/projects

⚠️ 注意： 不建议长期把活跃项目放在：

/mnt/c/Users/用户名/Desktop

/mnt/c/Users/用户名/Documents

/mnt/d/projects

Docker 官方建议 WSL2 开发时把项目代码放在 Linux 发行版的文件系统中，以获得更好的文件访问和容器开发体验。([Docker Documentation][3])

✅ 推荐： ~/projects/city-snapshot-platform

⚠️ 注意： 不推荐放在 /mnt/c/project/city-snapshot-platform

十二：Windows 如何访问 WSL 文件 🔗

在 Windows 文件资源管理器地址栏输入：

\\wsl$

然后进入：

Ubuntu → home → developer → projects

也可以在 WSL 中执行：

explorer.exe .

这会使用 Windows 文件资源管理器打开当前 Linux 目录。

⚠️ 注意： 不要频繁使用 Windows 编辑器直接修改 WSL 内部系统文件：

/etc

/usr

/var

项目文件建议通过 VS Code WSL 模式编辑。

第四部分：配置 Git

十三：安装检查 ✅

Ubuntu 中已经通过 apt 安装 Git。

检查：

git --version

Git 官方建议 Debian/Ubuntu 系统通过包管理器安装 Git。([Git][4])

十四：配置 Git 用户 👤

执行：

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

例如：

git config --global user.name "Shengjie He"
git config --global user.email "shengjie@example.com"

设置默认分支：

git config --global init.defaultBranch main

设置拉取策略：

git config --global pull.ff only

设置换行符：

git config --global core.autocrlf input

查看：

git config --global --list

推荐结果：

user.name=Shengjie He
user.email=shengjie@example.com
init.defaultbranch=main
pull.ff=only
core.autocrlf=input

十五：配置 SSH Key 🔑

在 WSL 中生成：

ssh-keygen -t ed25519 -C "你的邮箱"

直接按回车，默认路径为：

~/.ssh/id_ed25519

建议为私钥设置密码。

启动 Agent：

eval "$(ssh-agent -s)"

添加私钥：

ssh-add ~/.ssh/id_ed25519

查看公钥：

cat ~/.ssh/id_ed25519.pub

把公钥添加到：

GitHub

GitLab

Gitee

企业 Git 服务器

测试：

ssh -T git@github.com

或者：

ssh -T git@gitlab.company.com

⚠️ 注意： 不要提交 ~/.ssh/id_ed25519

私钥永远不应放入 Git 仓库。

十六：克隆项目 📥

cd ~/projects
git clone git@gitlab.company.com:team/city-snapshot-platform.git
cd city-snapshot-platform

检查：

git status
git branch --show-current
git remote -v

第五部分：配置 Node.js

十七：为什么使用 NVM 🤷

不同项目可能要求：

Node.js 18

Node.js 20

Node.js 22

Node.js 24

直接使用系统级 Node.js，容易发生版本冲突。

NVM 可以：

安装多个 Node.js 版本

按项目切换版本

使用 .nvmrc 固定版本

设置默认 Node.js

NVM 官方支持 Linux 和 Windows WSL。([GitHub][5])

十八：安装 NVM 📥

执行：

curl -o- \
  https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh \
  | bash

重新加载终端配置：

source ~/.bashrc

检查：

command -v nvm
nvm --version

如果没有输出，关闭 Ubuntu 终端后重新打开。

十九：安装 Node.js LTS ⚡

执行：

nvm install --lts

设置默认版本：

nvm alias default 'lts/*'

检查：

node --version
npm --version

Codex CLI 通过 npm 安装，因此 Node.js 必须能在当前 WSL Shell 中正常运行。

二十：项目固定 Node.js 版本 📌

进入项目：

cd ~/projects/city-snapshot-platform

查看当前版本：

node --version

创建 .nvmrc：

node --version > .nvmrc

之后进入项目执行：

nvm use

其他团队成员可以执行：

nvm install
nvm use

NVM 会向上查找 .nvmrc，并使用其中声明的 Node.js 版本。([GitHub][5])

二十一：配置 npm 国内源（可选）🌐

网络访问 npm 官方源较慢时，可以临时设置：

npm config set registry https://registry.npmmirror.com

检查：

npm config get registry

恢复官方源：

npm config set registry https://registry.npmjs.org

企业项目更推荐使用：

Nexus

Artifactory

Verdaccio

企业 npm 私服

⚠️ 注意： 不要在未经团队确认的情况下提交个人 .npmrc。

第六部分：配置 Python

二十二：检查 Python 🐍

python3 --version
pip3 --version

Ubuntu 中建议保留系统 Python，不要直接删除或覆盖。

每个 Python 项目应建立独立虚拟环境。

二十三：创建虚拟环境 🔧

进入项目：

cd ~/projects/city-snapshot-platform

创建：

python3 -m venv .venv

激活：

source .venv/bin/activate

检查：

which python
python --version
pip --version

路径应类似：

/home/developer/projects/city-snapshot-platform/.venv/bin/python

Python 官方建议使用 venv 创建彼此隔离的项目环境，常用目录名为 .venv，且虚拟环境不应提交到 Git。([Python documentation][6])

二十四：升级虚拟环境中的 pip ⬆️

python -m pip install --upgrade pip

安装项目依赖：

pip install -r requirements.txt

退出环境：

deactivate

在 .gitignore 中加入：

.venv/
__pycache__/
*.pyc

第七部分：安装 Codex CLI

二十五：在 WSL 中安装 💻

确认：

node --version
npm --version

安装 Codex：

npm install -g @openai/codex

检查：

codex --version

Codex 官方提供 npm 全局安装方式，官方仓库也将 Windows 11 via WSL2 列为支持的运行环境。([OpenAI Help Center][7])

二十六：登录 Codex 🔐

进入项目：

cd ~/projects/city-snapshot-platform

启动：

codex

选择：

Sign in with ChatGPT

浏览器会打开登录页面。

登录后，在 Codex 中执行：

/status

检查：

当前目录

认证状态

运行模式

模型

Git 仓库

Codex 可使用 ChatGPT 账号登录；CLI、IDE 和桌面应用可以共享同一 Codex 账号能力。([OpenAI Help Center][8])

二十七：更新 Codex CLI ⬆️

执行：

codex --upgrade

也可以：

npm install -g @openai/codex@latest

更新后检查：

codex --version

二十八：第一次环境验证 ✅

在项目根目录启动：

codex

输入：

请只检查当前开发环境，不修改任何文件。

请执行并汇总：

当前操作系统和工作目录。

Git 版本与当前分支。

Node.js 和 npm 版本。

Python 和 pip 版本。

Docker 和 Docker Compose 版本。

当前项目是否为 Git 仓库。

当前是否有未提交修改。

项目中可用的测试、构建和启动命令。

无法运行的命令要明确说明原因。

此时 Docker 还未配置完成，允许 Codex 如实报告 Docker 不可用。

第八部分：安装 VS Code 与 WSL 扩展

二十九：安装 VS Code 📝

在 Windows 安装 Visual Studio Code。

安装完成后打开 PowerShell：

code --version

如果无法识别 code，重新启动终端或重新安装 VS Code，并确保加入 PATH。

三十：安装 WSL 扩展 🔌

在 Windows PowerShell 执行：

code --install-extension ms-vscode-remote.remote-wsl

也可以在 VS Code 扩展市场搜索：

WSL Publisher: Microsoft

VS Code 的 WSL 扩展允许 Windows 上的编辑器连接 WSL，并在 Linux 环境中执行扩展、终端、调试和开发工具。([Visual Studio Code][9])

三十一：从 WSL 打开 VS Code 🚀

Ubuntu 中执行：

cd ~/projects/city-snapshot-platform
code .

VS Code 左下角应显示：

WSL: Ubuntu

打开终端：

Terminal → New Terminal

检查：

pwd
which node
which python3
which git

路径应该来自 Linux：

/home/developer/... /home/developer/.nvm/... /usr/bin/python3 /usr/bin/git

如果显示：

C:...

说明当前不是 WSL 工作区。

第九部分：安装 Codex IDE 扩展

三十二：安装官方扩展 🔌

在 VS Code 中搜索：

Codex – OpenAI's coding agent Publisher: OpenAI

扩展标识为：

OpenAI.chatgpt

也可以执行：

code --install-extension OpenAI.chatgpt

官方 Codex 扩展支持 VS Code，并兼容 Cursor、Windsurf 等多数 VS Code 派生编辑器。扩展可以使用打开文件和选中代码作为上下文，也可以委派云端任务。([OpenAI Help Center][8])

三十三：在 WSL 工作区启用扩展 ⚙️

在 VS Code 打开：

Extensions

找到 Codex 扩展。

如果出现：

Install in WSL: Ubuntu

点击安装。

不同扩展的执行位置可能不同，关键是确保当前项目窗口左下角显示：

WSL: Ubuntu

然后使用 ChatGPT 账号登录。

三十四：IDE 验证任务 ✅

在项目中打开：

package.json

或：

README.md

在 Codex 面板输入：

请分析当前打开的文件，并说明：

文件用途。

关键配置。

可能使用的启动命令。

可能使用的测试命令。

不要修改文件。

确认 Codex 可以读取当前 WSL 项目。

第十部分：安装 Windows 桌面应用

三十五：当前桌面应用形态 💻

截至 2026 年 7 月，Codex 已集成到新的 ChatGPT 桌面应用中，支持 Windows 和 macOS。应用中可以在 ChatGPT、Work 与 Codex 之间切换；功能正在逐步向符合条件的账号开放。([OpenAI Help Center][10])

如果账号暂时没有桌面 Codex 入口，不影响使用：

Codex CLI

Codex IDE 扩展

Codex Cloud

三十六：安装桌面应用 📥

下载并安装 Windows ChatGPT 桌面应用。

启动后：

使用 ChatGPT 账号登录

从左上角选择 Codex

添加本地项目

选择项目文件夹或 Git 仓库

Codex 官方入门流程是：

登录 ChatGPT 选择本地文件夹或 Git 仓库创建第一个任务

([OpenAI][11])

三十七：桌面应用和 WSL 项目的选择 🔄

WSL 项目路径为：

\\wsl$\Ubuntu\home\developer\projects\city-snapshot-platform

在桌面应用中选择项目时，优先选择对应 WSL 路径。

如果桌面应用提供 Agent Environment 选项，选择：

WSL Ubuntu

不同版本的桌面应用界面可能略有不同。

首次使用时建议用简单只读任务验证：

请只分析当前项目，不修改文件。

确认：

当前项目根目录。

当前 Git 分支。

项目主要语言。

可用测试命令。

是否能访问 Node.js 和 Python。

第十一部分：安装 Docker Desktop

三十八：为什么使用 Docker Desktop 🐳

推荐在 Windows 安装 Docker Desktop，并使用 WSL2 Backend。

⚠️ 注意： 不要同时在 Ubuntu 中另外安装：

docker-ce

dockerd

containerd

Docker 官方明确建议：使用 Docker Desktop WSL2 Backend 前，移除直接安装在 WSL 发行版中的 Docker Engine 或 Docker CLI，避免冲突。([Docker Documentation][12])

三十九：安装 Docker Desktop 📥

安装最新 Docker Desktop for Windows。

普通个人开发推荐使用默认的 Per-user 安装方式。Docker 官方当前将 Per-user 安装列为多数用户的推荐方式，并默认使用 WSL2 Backend。([Docker Documentation][13])

安装完成后启动 Docker Desktop。

进入：

Settings → General

确认：

Use the WSL 2 based engine

部分版本默认开启，不会显示该选项。

四十：启用 Ubuntu 集成 🔗

进入：

Settings → Resources → WSL Integration

开启：

Enable integration with my default WSL distro Ubuntu

点击：

Apply & Restart

Docker 官方说明，启用 WSL Integration 后，可以直接在对应 Linux 发行版中使用 docker 命令。([Docker Documentation][12])

四十一：检查 Docker ✅

Ubuntu 中执行：

docker version
docker compose version
docker info

测试：

docker run --rm hello-world

查看容器：

docker ps

如果项目有 Compose 文件：

docker compose config

四十二：Docker 基础验证 🧪

创建测试目录：

mkdir -p ~/projects/docker-check
cd ~/projects/docker-check

创建 compose.yaml：

services:
  web:
    image: nginx:alpine
    ports:
      - "18080:80"

启动：

docker compose up -d

访问：

curl http://127.0.0.1:18080

查看：

docker compose ps

清理：

docker compose down

第十二部分：建立统一项目环境

四十三：推荐项目基线文件 📄

项目根目录建议包含：

AGENTS.md

README.md

.gitignore

.editorconfig

.gitattributes

.nvmrc

.env.example

Python 项目还可包含：

requirements.txt

pyproject.toml

四十四：`.gitignore` 🚫

# Environment
.env
.env.*
!.env.example

# Node.js
node_modules/
npm-debug.log*
pnpm-debug.log*
yarn-error.log*

# Python
.venv/
__pycache__/
*.pyc
.pytest_cache/
.mypy_cache/
.ruff_cache/

# IDE
.vscode/settings.local.json
.idea/

# OS
.DS_Store
Thumbs.db

# Build
dist/
build/
coverage/

# Secrets
*.pem
*.key
*.p12
*.jks

四十五：`.gitattributes` ⚙️

* text=auto eol=lf

*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

*.sh text eol=lf
*.yml text eol=lf
*.yaml text eol=lf
*.json text eol=lf

作用：

Shell 脚本统一 LF

Windows 批处理统一 CRLF

降低 Windows/WSL 换行符冲突

四十六：`.editorconfig` 📐

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

[*.py]
indent_size = 4

[*.md]
trim_trailing_whitespace = false

[*.{bat,cmd,ps1}]
end_of_line = crlf

第十三部分：完整环境自检

四十七：自检脚本 📋

创建：

mkdir -p ~/bin
nano ~/bin/check-dev-env.sh

内容：

#!/usr/bin/env bash
set -u

PASS=0
FAIL=0

check_command() {
  local command_name="$1"

  if command -v "${command_name}" >/dev/null 2>&1; then
    printf "[PASS] %-15s %s\n" \
      "${command_name}" \
      "$(command -v "${command_name}")"
    PASS=$((PASS + 1))
  else
    printf "[FAIL] %-15s not found\n" "${command_name}"
    FAIL=$((FAIL + 1))
  fi
}

echo "===== System ====="
uname -a
printf "User: %s\n" "$(whoami)"
printf "Home: %s\n" "${HOME}"
printf "PWD:  %s\n" "$(pwd)"

echo
echo "===== Commands ====="
check_command git
check_command node
check_command npm
check_command python3
check_command pip3
check_command codex
check_command docker
check_command jq
check_command rg
check_command code

echo
echo "===== Versions ====="
git --version 2>/dev/null || true
node --version 2>/dev/null || true
npm --version 2>/dev/null || true
python3 --version 2>/dev/null || true
codex --version 2>/dev/null || true
docker --version 2>/dev/null || true
docker compose version 2>/dev/null || true
code --version 2>/dev/null | head -n 1 || true

echo
echo "===== Git ====="
if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  printf "Branch: %s\n" "$(git branch --show-current)"
  git status --short
else
  echo "Current directory is not a Git repository."
fi

echo
echo "===== Result ====="
printf "PASS=%s\n" "${PASS}"
printf "FAIL=%s\n" "${FAIL}"

if [ "${FAIL}" -gt 0 ]; then
  exit 1
fi

授权：

chmod +x ~/bin/check-dev-env.sh

运行：

~/bin/check-dev-env.sh

四十八：预期结果 📊

至少应通过：

git

node

npm

python3

pip3

codex

docker

jq

rg

code

如果项目没有使用 Python，可以保留 Python 基础环境，不需要安装项目依赖。

第十四部分：使用 Codex 验证整个环境

四十九：创建验证仓库 🏗️

mkdir -p ~/projects/codex-environment-lab
cd ~/projects/codex-environment-lab

git init
npm init -y

cat > README.md <<'EOF'
# Codex Environment Lab

This repository is used to verify the Windows 11,
WSL2, VS Code, Node.js, Python, Docker and Codex environment.
EOF

git add README.md package.json
git commit -m "chore: initialize environment lab"

五十：启动 Codex ▶️

codex

输入：

请检查当前开发环境，不要修改任何文件。

需要验证：

当前工作目录位于 WSL Linux 文件系统，而不是 /mnt/c。

当前目录是 Git 仓库。

Git、Node.js、npm、Python、Codex、Docker 和 Docker Compose 可用。

输出各工具版本。

执行 git status。

执行 docker info，但不要创建或删除容器。

检查 README.md 内容。

最后给出：

已通过项目

失败项目

修复建议

五十一：合格结果 ✅

Codex 应能够确认：

当前路径位于 /home/...

Git 仓库可用

Node.js 可用

Python 可用

Docker Desktop WSL Integration 正常

Docker Compose 可用

README.md 可读取

没有修改文件

执行后检查：

git status

工作区应保持干净。

第十五部分：常见问题排查

五十二：`wsl --install` 无法执行 ❌

以管理员方式运行 PowerShell。

执行：

wsl --status
wsl --update

查看发行版：

wsl --list --online

手动安装：

wsl --install -d Ubuntu

如果仍然失败，检查：

Windows Update

虚拟化

Virtual Machine Platform

Windows Subsystem for Linux

五十三：Ubuntu 显示 WSL1 🔄

查看：

wsl -l -v

转换：

wsl --set-version Ubuntu 2

设置默认：

wsl --set-default-version 2

五十四：`nvm: command not found` ❓

执行：

source ~/.bashrc

检查：

grep -n "NVM_DIR" ~/.bashrc

正常应包含：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

关闭终端后重新打开。

五十五：`codex: command not found` ❓

检查 npm 全局目录：

npm config get prefix
npm bin -g 2>/dev/null || true

重新安装：

npm install -g @openai/codex@latest

检查：

command -v codex
codex --version

确认 Codex 是在 WSL 中安装，而不是只安装在 Windows PowerShell 中。

五十六：VS Code 终端使用的是 Windows 🔧

检查 VS Code 左下角是否显示：

WSL: Ubuntu

关闭当前窗口，在 Ubuntu 中执行：

cd ~/projects/项目目录
code .

终端检查：

uname -a
pwd
which node

五十七：Docker 命令不可用 ❓

确认 Docker Desktop 正在运行。

检查：

wsl -l -v

Docker Desktop 中打开：

Settings → Resources → WSL Integration

开启 Ubuntu，然后：

Apply & Restart

Ubuntu 中重新执行：

docker version

五十八：Docker 与 WSL 内 Docker 冲突 ⚠️

检查：

which docker
ps aux | grep dockerd

⚠️ 注意： 如果此前在 Ubuntu 中安装过 Docker Engine，可能与 Docker Desktop 冲突。

按照 Docker 官方建议，使用 Docker Desktop WSL2 Backend 时，不应同时维护一套直接安装在 WSL 内的 Docker Engine。([Docker Documentation][12])

五十九：项目在 `/mnt/c` 中运行很慢 🐢

移动项目：

mkdir -p ~/projects
cp -a /mnt/c/projects/city-snapshot-platform \
  ~/projects/

或者重新克隆：

cd ~/projects
git clone <仓库地址>

然后使用：

code ~/projects/city-snapshot-platform

六十：Git 文件全部显示被修改 🔧

通常由换行符造成。

检查：

git config --global core.autocrlf

WSL 推荐：

git config --global core.autocrlf input

项目增加 .gitattributes：

* text=auto eol=lf

⚠️ 注意： 不要在未确认内容前直接提交所有换行符变化。

六十一：Python 安装包污染系统环境 ⚠️

⚠️ 注意： 不要执行 sudo pip install ...

正确方式：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

六十二：Codex 桌面应用找不到 WSL 工具 🔧

先确认项目是以 WSL 环境打开。

检查桌面应用中的：

Project Path

Agent Environment

Integrated Terminal

首次配置时，不要同时在 Windows 和 WSL 中安装两套不同版本的项目依赖。

✅ 推荐： Windows：只安装桌面工具

WSL：安装 Git、Node、Python、Codex CLI 和项目依赖

第十六部分：一小时练习

六十三：练习一：完成环境安装 🏋️

要求：

WSL2 Ubuntu 正常运行

Git 正常

Node.js 正常

Python 正常

Codex CLI 正常

Docker 正常

VS Code WSL 正常

Codex IDE 扩展正常

六十四：练习二：克隆项目 🏋️

cd ~/projects
git clone <项目地址>
cd <项目目录>

执行：

git status
nvm use || true
python3 --version
docker compose config || true

六十五：练习三：让 Codex 检查项目 🏋️

提示词：

请只分析当前项目，不修改任何文件。

输出：

操作系统和当前路径。

项目技术栈。

Git 当前分支和状态。

Node.js 要求。

Python 要求。

Docker 与 Compose 配置。

安装依赖命令。

启动命令。

测试命令。

当前环境缺失项。

六十六：练习四：检查环境隔离 🏋️

Node.js：

nvm ls
node --version

Python：

python3 -m venv .venv
source .venv/bin/activate
which python
deactivate

Docker：

docker context show
docker version
docker compose version

第十七部分：验收标准

六十七：本篇验收清单 ✅

完成后应达到：

Windows 11 虚拟化已开启

WSL2 已安装

Ubuntu 运行在 WSL2

项目存放在 ~/projects

Git 用户信息已配置

SSH Key 已配置

Node.js 使用 NVM 管理

项目包含 .nvmrc

Python 使用 .venv

Codex CLI 安装在 WSL

Codex CLI 可以登录

VS Code 已安装 WSL 扩展

VS Code 工作区显示 WSL: Ubuntu

Codex IDE 扩展可以读取项目

Windows 桌面应用可以打开 Codex

Docker Desktop 使用 WSL2 Backend

Docker Desktop 已启用 Ubuntu Integration

docker 与 docker compose 可在 WSL 中执行

Codex 可以检查完整开发环境

第十八部分：本篇总结

六十八：核心结论 📝

Windows 负责桌面工具

WSL2 负责开发工具链

项目源码优先放在 Linux 文件系统

Git、Node、Python、Codex CLI 安装在 WSL

Node.js 使用 NVM 管理版本

Python 使用 venv 隔离项目依赖

VS Code 必须以 WSL 模式打开项目

Docker Engine 由 Docker Desktop 提供

不要同时在 WSL 中再运行一套 Docker Engine

Codex 桌面应用、IDE 和 CLI 可以组合使用

环境验证必须基于真实命令，而不是只看安装界面

推荐最终结构：

Windows 11 ├── ChatGPT 桌面应用 ├── VS Code ├── Windows Terminal └── Docker Desktop │ ▼ WSL2 Ubuntu ├── ~/projects ├── Git ├── NVM + Node.js ├── Python + .venv ├── Codex CLI └── Docker CLI / Compose

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

码东

@baidu_36496687

已为社区贡献8条内容

Codex 工程化落地指南 02：Windows 11、WSL2 与 Codex 环境搭建

码东

一：教程定位 🎯

二：教程信息 📋

三：学习目标 📌

第一部分：环境架构设计

四：推荐架构 🏗️

安装在 Windows

安装在 WSL2 Ubuntu

通过 Docker Desktop 提供

五：为什么不建议全部装在 Windows 🤔

第二部分：安装和检查 WSL2

六：安装前检查 🔍

七：安装 WSL ⚙️

八：更新 WSL 🔄

九：初始化 Ubuntu 🚀

十：更新 Ubuntu 软件包 📦

第三部分：项目目录设计

十一：项目应该放在哪里 📁

十二：Windows 如何访问 WSL 文件 🔗

第四部分：配置 Git

十三：安装检查 ✅

十四：配置 Git 用户 👤

十五：配置 SSH Key 🔑

十六：克隆项目 📥

第五部分：配置 Node.js

十七：为什么使用 NVM 🤷

十八：安装 NVM 📥

十九：安装 Node.js LTS ⚡

二十：项目固定 Node.js 版本 📌

二十一：配置 npm 国内源（可选）🌐

第六部分：配置 Python

二十二：检查 Python 🐍

二十三：创建虚拟环境 🔧

二十四：升级虚拟环境中的 pip ⬆️

第七部分：安装 Codex CLI

二十五：在 WSL 中安装 💻

二十六：登录 Codex 🔐

二十七：更新 Codex CLI ⬆️

二十八：第一次环境验证 ✅

第八部分：安装 VS Code 与 WSL 扩展

二十九：安装 VS Code 📝

三十：安装 WSL 扩展 🔌

三十一：从 WSL 打开 VS Code 🚀

第九部分：安装 Codex IDE 扩展

三十二：安装官方扩展 🔌

三十三：在 WSL 工作区启用扩展 ⚙️

三十四：IDE 验证任务 ✅

第十部分：安装 Windows 桌面应用

三十五：当前桌面应用形态 💻

三十六：安装桌面应用 📥

三十七：桌面应用和 WSL 项目的选择 🔄

第十一部分：安装 Docker Desktop

三十八：为什么使用 Docker Desktop 🐳

三十九：安装 Docker Desktop 📥

四十：启用 Ubuntu 集成 🔗

四十一：检查 Docker ✅

四十二：Docker 基础验证 🧪

第十二部分：建立统一项目环境

四十三：推荐项目基线文件 📄

四十四：.gitignore 🚫

四十五：.gitattributes ⚙️

四十六：.editorconfig 📐

第十三部分：完整环境自检

四十七：自检脚本 📋

四十八：预期结果 📊

第十四部分：使用 Codex 验证整个环境

四十九：创建验证仓库 🏗️

五十：启动 Codex ▶️

五十一：合格结果 ✅

第十五部分：常见问题排查

五十二：wsl --install 无法执行 ❌

五十三：Ubuntu 显示 WSL1 🔄

五十四：nvm: command not found ❓

五十五：codex: command not found ❓

五十六：VS Code 终端使用的是 Windows 🔧

五十七：Docker 命令不可用 ❓

五十八：Docker 与 WSL 内 Docker 冲突 ⚠️

五十九：项目在 /mnt/c 中运行很慢 🐢

六十：Git 文件全部显示被修改 🔧

四十四：`.gitignore` 🚫

四十五：`.gitattributes` ⚙️

四十六：`.editorconfig` 📐

五十二：`wsl --install` 无法执行 ❌

五十四：`nvm: command not found` ❓

五十五：`codex: command not found` ❓

五十九：项目在 `/mnt/c` 中运行很慢 🐢