Windows 搭建 WSL2 AI 开发环境
内容提要
介绍在 Windows 上搭建 WSL2 AI 开发环境：Windows 作为唯一源码与 Git 权威环境，WSL2 Debian 仅作无状态编译测试沙盒；通过 PowerShell 调度脚本 linux-task.ps1 实现跨环境同步与构建，Docker 使用 Docker Desktop 集成，并配置 AI Agent 约束规则以防误操作。
延伸解读
为什么选择 Windows 作为权威源码环境
文章明确将 Windows 仓库设为唯一权威源码，WSL2 内的副本随时可清空重建。这样做的好处是 Git、SSH、GPG、YubiKey 等无需在 WSL2 中重复配置，AI Agent 也能直接操作宿主机代码。但代价是跨文件系统访问的 I/O 性能较差，因此作者通过调度脚本将编译测试任务同步到 WSL2 的 ext4 分区执行，以平衡开发便利性与构建性能。
跨环境调度器的设计要点
linux-task.ps1 提供 build、direct、sync、path、clean 五种模式，分别对应增量同步后构建、轻量只读检查、仅同步、输出副本路径和清理副本。build 模式将源码同步到 ~/Build 下的 ext4 副本，并排除 .git、node_modules 等目录，确保构建环境干净且可丢弃。direct 模式则直接在 /mnt 下执行，适合单文件 lint 等轻量操作，避免不必要的同步开销。
AI Agent 约束规则的实际作用
为防止 Agent 误在 Windows 执行 Linux 编译命令或修改 WSL 临时副本，文章建议在 Codex 的 developer_instructions 和 Claude Code 的 CLAUDE.md 中明确环境分工。规则强调 Git 变更操作只能在 Windows 执行，Linux 构建测试必须通过 linux-task.ps1 调用，且不得在 Debian 内安装独立 Docker 引擎。这些约束能降低 Agent 误操作风险，但需要用户根据实际路径替换示例中的用户名和发行版名称。
日常使用中的注意事项
文章提醒，构建依赖 Git 版本号时，由于 Linux 副本排除了 .git，依赖 git describe 的脚本会报错，需先在 Windows 读取 commit 或 tag 再传入。Docker Compose 的 bind mount 挂载的是 Linux 副本，持久数据应使用命名卷。此外，WSL 的 VHDX 虚拟磁盘会随使用膨胀且不会自动释放空间，需定期手动压缩，避免磁盘占用过大。
Q&A
为什么在 Windows 上搭建 WSL2 AI 开发环境时，不把源码直接放在 WSL2 里？
因为 WSL2 通过 /mnt 挂载 Windows 盘符，跨文件系统访问的 I/O 性能相比原生 ext4 损耗很大，涉及大量小文件时尤为明显。因此文章将 Windows 仓库作为唯一权威源码，WSL2 内的副本随时可以清空重建，只充当无状态的编译与测试沙盒。
linux-task.ps1 脚本支持哪些模式，分别有什么作用？
支持五种模式：build 增量同步源码至 ext4 副本并执行依赖安装、编译与测试；direct 在 /mnt 下做轻量只读检查；sync 仅增量同步源码不执行构建；path 输出项目在 Linux 中对应的副本路径；clean 删除该项目的 Linux 副本及依赖缓存。
Docker 在 WSL2 中如何集成，需要单独安装 Docker 引擎吗？
不需要。Docker 采用 Docker Desktop 的 WSL2 后端，在 Docker Desktop 设置 Resources → WSL Integration 中勾选 Debian 即可，Docker CLI 会自动挂载到 Linux。在 Debian 内把用户加入 docker 组后即可使用，不应在 WSL2 里单独安装 Docker 引擎。
如何配置 AI Agent 的约束规则，防止它误在 Windows 执行 Linux 命令？
规则按作用域分两层：机器全局层面，Codex 在 ~/.codex/config.toml 顶层写 developer_instructions，~/.codex/AGENTS.md 规范测试与汇报流程；Claude Code 在 ~/.claude/CLAUDE.md 做同样分工约束。项目本地在仓库根目录 AGENTS.md 记录项目独有的依赖命令与测试流水线。约束中明确源码和 .git 在 Windows，Linux 构建测试走 linux-task.ps1。
在 Windows 下用 Claude Code 调用 linux-task.ps1 时，为什么要设置 MSYS_NO_PATHCONV=1？
因为 Claude Code 在 Windows 下默认通过 Git Bash 执行命令，Git Bash 会把 / 开头的参数改写为 Windows 盘符路径，导致传给 Linux 的参数被损坏。调用脚本时声明 MSYS_NO_PATHCONV=1 可以避免这种路径转换，例如：MSYS_NO_PATHCONV=1 pwsh.exe -NoProfile -File 'D:\WSL\Scripts\linux-task.ps1' -Mode build -Project 'D:\Forgejo\App' -Command 'pnpm test'。
日常使用这套工作流时，如何提取构建产物或备份 WSL2 系统？
提取构建产物时，先获取 Linux 副本路径，再按需拷贝所需文件到 Windows 目标目录，禁止将整个构建目录反向推回覆盖源码。系统备份时，先退出 Docker Desktop，然后执行 wsl --shutdown，再用 wsl --export Debian "D:\WSL\Snapshots\Debian-$stamp.vhdx" --vhd 导出快照。
