Windows → WSL2 全面迁移：工具链、Docker、OpenCode

我的开发环境转型计划

2026/7/12

当前环境状态

硬件配置

• C: 200GB（系统盘，剩余 ~61GB）
• D: 275GB（数据盘，剩余 ~136GB）
• R: 1GB RAM 盘（缓存盘）

已安装工具链

工具	版本	位置
Node.js	v22.22.2	D:\Program Files (x86)\nvm
Python	3.12.13	?
Git	2.50.0	Windows 版
Docker	29.5.3	Docker Desktop
Go	1.24.1	?
Rust	nightly	?
Java	OpenJDK 21	D:\devtools\Java
Maven	3.9.5	D:\devtools\apache-maven
Android SDK	?	D:\devtools\Android\Sdk
CMake	?	D:\devtools\CMake
OpenSSL	?	D:\devtools\OpenSSL

WSL2 状态

• Ubuntu 26.04 LTS (WSL 2) ------ 已安装，位置：D:\devtools\wsl\ubuntu
• docker-desktop (WSL 2) ------ 已安装，位置：D:\devtools\Docker\Images\main

---

问题根源

opencode 无法启动的根本原因

opencode.exe 是用 Bun 打包的独立可执行文件。Bun 在 Windows 上编译独立 exe 时，会将 bunfs（Bun 虚拟文件系统）的根路径硬编码为 B:/~BUN/root/。这是 Bun 的设计决策 ------ Windows 上需要一个驱动器字母来挂载虚拟文件系统。

相关源码（packages/cli/script/build.ts:98 和 packages/opencode/script/build.ts:165）：

// Windows 平台强制使用 B:/~BUN/root/ 作为 bunfs 根路径
const bunfsRoot = item.os === "win32" ? "B:/~BUN/root/" : "/$bunfs/root/"

两层问题：

1. Bun 的 bunfs 硬编码 B: 驱动器 ------ 运行时必须是可访问的有效驱动器
2. ImDisk RAM 盘上的 DLL 提取失败 ------ 当 %TEMP% 指向 ImDisk RAM 盘时，Bun 提取内置 DLL 的操作静默失败

错误表现：

Failed to initialize OpenTUI render library: Failed to open library "B:/~BUN/root/opentui-2nr24hkx.dll": error code 126

error code 126 = "找不到指定的模块"

---

解决方案对比

方案	优点	缺点	推荐度
从源码运行	完全绕过 Bun 独立 exe	需要手动维护源码	⭐⭐⭐
WSL2 运行	一劳永逸，性能最好	需要适应 Linux 环境	⭐⭐⭐⭐⭐
管理员权限运行	简单尝试	不一定有效	⭐
虚拟 B: 驱动器	临时 workaround	不治本	⭐⭐

---

转型计划：全面转向 WSL2 开发

阶段 1：准备工作

1. 备份当前环境

   • 导出 WSL2 Ubuntu：wsl --export Ubuntu D:\backup\ubuntu-backup.tar
   • 备份重要项目代码

2. 清理 Docker Desktop

   • 卸载 Docker Desktop（控制面板 → 卸载）
   • 删除 Docker 数据：C:\Users\a1\AppData\Local\Docker

阶段 2：WSL2 原生 Docker 安装

# 在 Ubuntu WSL2 中执行
sudo apt update
sudo apt install docker.io docker-compose -y
sudo usermod -aG docker $USER
sudo service docker start

# 验证
docker --version
docker run hello-world

阶段 3：开发工具迁移

工具	Windows 版	WSL2 替代方案
Node.js (nvm)	D:\Program Files (x86)\nvm	`curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh
Python	Python 3.12.13	sudo apt install python3 python3-pip 或 pyenv
Git	Git 2.50.0 (Windows)	sudo apt install git
Go	go1.24.1 windows/amd64	sudo apt install golang 或官方二进制
Rust	cargo 1.95.0-nightly	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs
Java	OpenJDK 21 (D:\devtools)	sudo apt install openjdk-21-jdk
Maven	apache-maven-3.9.5	sudo apt install maven

阶段 4：代码项目迁移

1. 创建 WSL2 项目目录

   mkdir -p ~/projects
   cd ~/projects

2. 从 Windows 复制项目（一次性）

   cp -r /mnt/d/path/to/project ~/projects/

3. 后续开发全部在 WSL2 文件系统内进行 （不要用 /mnt/c/ 或 /mnt/d/，性能差）

阶段 5：opencode 迁移

# 在 WSL2 中安装 opencode
curl -fsSL https://opencode.ai/install | bash

# 运行
opencode -c

WSL2 中完全避开 Windows 的 B: 驱动器问题，因为 Linux 上 bunfs 使用 /$bunfs/root/ 虚拟路径，不需要驱动器字母。

---

转型后的环境架构

┌─────────────────────────────────────────────────────┐
│                    Windows 11                        │
│  ┌─────────────────────────────────────────────────┐ │
│  │              WSL2 (Ubuntu 26.04)                │ │
│  │  ┌─────────────────────────────────────────────┐│ │
│  │  │  Node.js, Python, Go, Rust, Java, Maven    ││ │
│  │  │  Docker Engine (原生)                       ││ │
│  │  │  Git, opencode, 所有开发工具                ││ │
│  │  └─────────────────────────────────────────────┘│ │
│  └─────────────────────────────────────────────────┘ │
│                                                       │
│  保留：Clash Verge, 图吧工具箱, 浏览器, Office     │
└─────────────────────────────────────────────────────┘

---

转型收益

性能提升

• Docker：内存占用减少 50-70%，CPU 开销更低，磁盘 I/O 更快
• 开发工具：直接在 Linux 文件系统上操作，无跨文件系统性能损耗
• 缓存 ：/tmp 默认 tmpfs，无需额外配置内存盘

运维简化

• 不再需要处理 Windows 盘符、路径分隔符、权限问题
• 所有工具链版本管理更灵活（nvm, pyenv, rustup 等）
• 更接近生产环境（大部分服务器运行 Linux）

兼容性解决

• opencode 的 B: 驱动器问题彻底解决
• 符号链接、文件权限正常工作
• npm/npx 不再遇到 EPERM 错误

---

需要保留在 Windows 的

软件	原因
Clash Verge	Windows GUI 代理工具
图吧工具箱	Windows 硬件工具
浏览器	GUI 应用，Windows 版更好用
Office	文档处理
游戏	Windows 独占

---

混合开发工作流

# 在 WSL2 里开发
cd ~/projects/my-app
code .  # VS Code Remote-WSL

# 需要 Windows 工具时
/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -Command "Get-Process"

# 文件同步（如果需要）
cp dist/* /mnt/d/releases/my-app/

---

总结

从 Windows 开发全面转向 WSL2 开发，是一次性的迁移成本，换来长期的开发体验提升。

核心收益：

1. 解决 opencode 等工具的兼容性问题
2. Docker 性能大幅提升
3. 开发环境更接近生产环境
4. 工具链管理更灵活

唯一需要适应的是：从 Windows 文件系统转到 Linux 文件系统，以及命令行环境的变化。但这个适应期很短（1-2周），之后开发体验会好很多。