WSL2 + OpenCode 完整搭建全流程（含迁移 WSL 到 D 盘）

环境：Windows 11 / WSL2 / Ubuntu / Node.js / OpenCode

目标：搭建 OpenCode Web 服务，并将 WSL 虚拟磁盘迁移到 D 盘，释放 C 盘空间。

准备底层虚拟化（Windows）
[安装 WSL2 Ubuntu](#安装 WSL2 Ubuntu)
[Ubuntu 内配置 Node 与环境变量](#Ubuntu 内配置 Node 与环境变量)
[安装 OpenCode 并启动 Web 服务](#安装 OpenCode 并启动 Web 服务)
[迁移 WSL 到 D 盘（可选）](#迁移 WSL 到 D 盘（可选）)
日常使用命令汇总
关键踩坑要点

一、准备底层虚拟化（Windows）

1. BIOS 开启 CPU 虚拟化

进入主板 BIOS，确认开启 CPU 虚拟化功能。

2. 启用 Windows 可选功能

启用以下 Windows 功能：

适用于 Linux 的 Windows 子系统
虚拟机平台

3. 设置 WSL 默认版本为 2

管理员 PowerShell 执行：

powershell 复制代码

wsl --set-default-version 2

二、安装 WSL2 Ubuntu

1. 管理员 PowerShell 安装 Ubuntu

powershell 复制代码

wsl --install -d Ubuntu

2. 首次启动 Ubuntu

设置 Linux 用户名：user
设置密码

3. 验证 WSL 状态

powershell 复制代码

wsl -l -v

确认：

NAME=Ubuntu
VERSION=2

三、Ubuntu 内配置 Node 与环境变量

1. 进入 WSL Ubuntu

在 Windows PowerShell 中执行：

powershell 复制代码

wsl

2. 安装 Node.js 与 npm

在 Ubuntu 内安装 Node.js，并确保 npm 可用。

3. 配置环境变量

编辑 .bashrc：

bash 复制代码

nano ~/.bashrc

根据 Node 安装位置追加 Node 路径，并追加 OpenCode 的 bin 目录：

bash 复制代码

export PATH="$HOME/.opencode/bin:$PATH"

生效并验证：

bash 复制代码

source ~/.bashrc
echo $PATH

四、安装 OpenCode 并启动 Web 服务

1. 安装 OpenCode

在 Ubuntu 内按官方方式安装 OpenCode。

2. 验证安装

bash 复制代码

opencode --version

3. 可选：配置访问密码

编辑 .bashrc：

bash 复制代码

nano ~/.bashrc

追加：

bash 复制代码

export OPENCODE_SERVER_PASSWORD="自定义密码"

生效：

bash 复制代码

source ~/.bashrc

4. 启动 OpenCode Web 服务

bash 复制代码

opencode web --port 4096 --hostname 0.0.0.0

5. 浏览器访问

text 复制代码

http://localhost:4096

五、迁移 WSL 到 D 盘（可选）

⚠️ 迁移前：停止 OpenCode，关闭所有 WSL 程序。

⚠️ 必须确认导出成功后再注销旧实例，否则系统可能丢失。

1. 停止 WSL

管理员 PowerShell 执行：

powershell 复制代码

wsl --shutdown
wsl -l -v

确认 Ubuntu 状态为：

text 复制代码

Stopped

2. D 盘新建目录

text 复制代码

D:\WSL\Ubuntu

3. 导出完整 Ubuntu 备份镜像

powershell 复制代码

wsl --export Ubuntu D:\ubuntu_backup.tar

4. 注销 C 盘旧 Ubuntu

导出成功后执行：

powershell 复制代码

wsl --unregister Ubuntu

5. 将备份镜像导入 D 盘

powershell 复制代码

wsl --import Ubuntu D:\WSL\Ubuntu D:\ubuntu_backup.tar --version 2

6. 配置默认登录用户

进入 Ubuntu：

powershell 复制代码

wsl

编辑配置：

bash 复制代码

sudo nano /etc/wsl.conf

写入：

ini 复制代码

[user]
default=user

保存退出。

7. 重启 WSL

在 Windows PowerShell 中执行：

powershell 复制代码

wsl --shutdown

8. 校验

重新进入 WSL：

powershell 复制代码

wsl

确认直接进入 user 用户，并检查：

bash 复制代码

opencode --version
node -v

9. 清理备份文件

全部验证无误后，可删除：

text 复制代码

D:\ubuntu_backup.tar

用于释放空间。

六、日常使用命令汇总

Windows PowerShell

powershell 复制代码

wsl                          # 进入 Ubuntu
wsl --shutdown               # 关闭 WSL
wsl -l -v                    # 查看 WSL 列表

Ubuntu WSL 内部

bash 复制代码

opencode web --port 4096 --hostname 0.0.0.0  # 启动 OpenCode
opencode --version
node -v
echo $PATH
cat /etc/wsl.conf

七、关键踩坑要点

wsl 系列命令只能在 Windows PowerShell 运行，不能在 WSL Linux 终端运行。
WSL1 老旧，全程使用 WSL2，依赖硬件虚拟化。
迁移必须"导出成功再注销"，否则系统丢失。
OpenCode 启动提示 OPENCODE_SERVER_PASSWORD is not set 表示无访问密码；本地测试可用，内网部署必须设置密码。