docs/docs/cn/ai/windows-wsl.md
在 Windows 上搭建 NocoBase 本地开发环境，推荐先准备 WSL 2。这样 Node.js、Yarn、NocoBase CLI、Docker 命令和 AI Agent 都可以在同一个 Linux shell 里运行，路径、权限和依赖编译也更接近常见的 Linux 部署环境。
如果你还没确定是否需要 WSL，可以先看 本地开发搭建。
开始前，先确认 Windows 版本和虚拟化状态。
按 Win + R，输入 winver，确认系统版本满足下面任一条件：
如果版本较旧，建议先升级 Windows，再继续安装 WSL。
打开「任务管理器」，进入「性能 / CPU」，确认「虚拟化」显示为「已启用」。
如果没有启用，需要进入 BIOS / UEFI 打开虚拟化。不同厂商的名称可能不同，比如 Intel VT-x、Intel Virtualization Technology、AMD-V、SVM Mode。
用管理员身份打开 PowerShell：
PowerShell执行：
wsl --install
安装完成后，重启电脑。
默认情况下，这个命令会安装 Ubuntu。首次启动 Ubuntu 时，会要求你创建 Linux 用户名和密码。这个用户名和密码只用于 WSL 内部，不需要和 Windows 账户一致。
如果你想安装指定发行版，可以先查看列表：
wsl --list --online
再安装指定发行版，比如 Ubuntu：
wsl --install -d Ubuntu
在 PowerShell 中执行：
wsl --list --verbose
输出类似：
NAME STATE VERSION
* Ubuntu Running 2
确认 VERSION 是 2。如果某个发行版还是 WSL 1，可以转换为 WSL 2：
wsl --set-version Ubuntu 2
建议把后续新安装的发行版默认设置为 WSL 2：
wsl --set-default-version 2
另外，可以更新一次 WSL：
wsl --update
如果你计划用 Docker 安装或运行 NocoBase，需要安装 Docker Desktop for Windows。
从 Docker 官方页面下载安装包：
安装时建议注意这几项：
Per-user 即可，适合大多数个人开发场景Use WSL 2 instead of Hyper-V启动 Docker Desktop 后，先确认 WSL 2 后端已启用：
然后开启发行版集成：
Ubuntu如果「Resources」下没有「WSL Integration」，通常是 Docker Desktop 当前处于 Windows containers 模式。可以在 Windows 系统托盘中点击 Docker 图标，切换到 Linux containers 后再检查。
先在 PowerShell 中验证：
wsl --list --verbose
docker version
docker compose version
docker run hello-world
然后进入 WSL：
wsl
在 WSL 中执行：
docker version
docker compose version
docker run hello-world
如果 hello-world 容器能正常拉取并运行，说明 Docker Desktop 与 WSL 2 集成成功。
WSL 本身不等于 Node.js 运行环境。默认通过 wsl --install 安装的 Ubuntu 通常不会预装 Node.js 和 npm，需要在 WSL 发行版里单独安装。
先从 PowerShell 进入 WSL：
wsl
下面的命令都在 WSL 终端中执行。
先检查是否已经安装：
node -v
npm -v
如果提示 command not found，按下面方式安装。
如果这台 WSL 环境只需要一个统一的 Node.js 版本，推荐使用 NodeSource。
sudo apt update
sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
安装完成后验证：
node -v
npm -v
npx -v
如果你需要在多个项目之间切换 Node.js 版本，或者项目使用 .nvmrc 固定版本，可以使用 nvm。
sudo apt update
sudo apt install -y curl ca-certificates
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
验证安装结果：
node -v
npm -v
npx -v
如果项目根目录需要固定 Node.js 22，可以创建 .nvmrc：
echo "22" > .nvmrc
nvm install
nvm use
以后进入项目目录后执行：
nvm use
即可切换到项目指定版本。
:::warning 注意
NodeSource 和 nvm 二选一即可。不建议在同一个 WSL 用户环境里混用两套 Node.js 管理方式。
:::
NocoBase 本地开发需要 Yarn 1.x。Node.js 安装完成后，可以通过 Corepack 启用 Yarn：
corepack enable
corepack prepare [email protected] --activate
yarn -v
如果你的环境里没有 Corepack，也可以用 npm 安装：
npm install -g [email protected]
yarn -v
Codex CLI 也可以在 Windows 原生命令行中使用。这里按 WSL 方案安装，是为了让 Codex 和 NocoBase 本地工具链处在同一套 Linux 环境里。这样 Codex 执行 nb、yarn、docker 等命令时，使用的是同一套文件路径、shell 语法和运行环境。
先确认当前在 WSL 中：
echo $WSL_DISTRO_NAME
如果能输出发行版名称，比如 Ubuntu，说明当前在 WSL 中。
在 WSL 中执行 Codex CLI 安装命令：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
如果需要无人值守安装，可以使用：
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
安装完成后运行：
codex
首次运行会提示登录。按提示使用 ChatGPT 账户或 OpenAI API key 完成认证。
验证 Codex 命令是否可用：
codex --version
建议从 WSL 的项目目录里启动 Codex，比如：
mkdir -p ~/projects
cd ~/projects/my-app
codex
:::tip 提示
因为 Codex 安装在 WSL 内，后续也应在 WSL 终端里运行 codex。如果在 Windows PowerShell 里运行 codex，使用的是 Windows 原生命令行环境，和这篇指南准备的 WSL 环境不是同一套环境。
:::
推荐把项目放在 WSL 文件系统中，比如：
~/projects/my-app
不建议优先放在 Windows 挂载路径下，比如：
/mnt/c/Users/<your-name>/projects/my-app
这样通常能获得更好的文件系统性能，也能减少软链接和权限问题。对 Node.js、Python、Java、Go 这类依赖文件较多的项目尤其明显。
如果需要从 Windows 访问 WSL 文件，可以在 Windows 文件资源管理器中打开：
\\wsl$\Ubuntu\home\<your-name>
先确认发行版是 WSL 2：
wsl --list --verbose
如果是 WSL 1，转换为 WSL 2：
wsl --set-version Ubuntu 2
然后回到 Docker Desktop，进入「Settings / Resources / WSL Integration」，打开对应发行版的集成开关并应用。
通常是 Docker Desktop 当前处于 Windows containers 模式。
可以这样处理：
可以先尝试：
wsl --shutdown
wsl --update
然后重新启动 Docker Desktop。
Docker 官方建议，在安装 Docker Desktop 前，卸载直接安装在 WSL Linux 发行版里的 Docker Engine 或 Docker CLI。否则可能和 Docker Desktop 的 WSL 集成产生冲突。
通常做法是在 WSL 发行版中卸载 docker-ce、docker-ce-cli、containerd.io 等包，然后使用 Docker Desktop 提供的 Docker CLI 集成。
先确认是在 WSL 里执行，而不是在 PowerShell 里执行：
echo $WSL_DISTRO_NAME
然后检查 Codex 是否在 PATH 中：
which codex
如果找不到，可以重新打开 WSL 终端，或重新执行安装命令：
curl -fsSL https://chatgpt.com/codex/install.sh | sh