本教程带你从零开始,在 Windows 上搭建一套完整的 OpenCode 开发环境:WSL + Ubuntu → OpenCode → Git/GitHub 认证 → IDE 远程连接。读完即可上手。

---

目录

• 一、WSL 环境搭建

• 二、OpenCode 安装

• 三、Git 与 GitHub 认证配置

• 四、文件跨系统操作与 IDE 连接

• 五、完整工作流总结

---

个人使用配置: Trae(仅用于远程连接WSL,不用AI模型交互)+WSL中opencode

前置概念:为什么要用 WSL?

OpenCode 官方建议在 Linux 环境下安装。对于 Windows 用户,最优雅的方案是 WSL(Windows Subsystem for Linux),而不是装双系统或虚拟机。

在开始之前,先理清两个概念:

名词	是什么	扮演的角色
WSL	Windows 内置的 Linux 兼容层	一条高速通道,把硬件资源透传给 Linux
Ubuntu	最流行的 Linux 发行版之一	通道里搭建出来的具体工作房间,自带 apt、bash 等工具

简单说:WSL 是"路",Ubuntu 是"路尽头的房子"。我们从微软商店安装的 "Ubuntu",就是给 WSL 配了一个具体的 Linux 系统。

---

一、WSL 环境搭建

1.1 安装位置:装在哪个盘?

核心结论:

• WSL 本身只是 Windows 的一个功能开关(启用即可,不选路径)。

• Ubuntu 发行版才是真正要安装的东西,可以指定安装位置。

• 必须装在 SSD(固态硬盘)上,装在 HDD 上性能会暴跌。

性能差异参考(同样一块盘):

操作	WSL 原生文件系统	通过 /mnt/c 访问 Windows 盘
大文件读写	>1GB/s	~100MB/s
小文件随机读	~4.6k IOPS	~3.6k IOPS
高并发混合读写	~16k IOPS	~6.2k IOPS

在 WSL 内部跑项目,和在 /mnt/c 下跑项目,速度能差 10 倍。所以项目一定要放在 WSL 内部文件系统(也就是 ~ 主目录下),而不是 Windows 盘。

1.2 启用 Windows 功能

打开 "启用或关闭 Windows 功能",勾选以下两项:

• ✅ 适用于 Linux 的 Windows 子系统

• ✅ 虚拟机平台

勾选后重启电脑。

这两步只是"毛坯房"——给 WSL 运行的资格和虚拟化能力,但还缺一个关键的内核组件,下一步补上。

1.3 在线安装 Ubuntu(网络通畅时)

以管理员身份打开 PowerShell 或 CMD,执行:

wsl --install -d Ubuntu --location D:\WSL

⚠️ 避坑:路径末尾不要加反斜杠! 写成 "D:\WSL\" 会报错:

错误代码: Wsl/InstallDistro/Service/RegisterDistro/ERROR_INVALID_NAME

去掉末尾的 \,改成 --location D:\WSL 即可。

安装过程中会下载 WSL 2.x.x 内核更新包(约 15-20MB)。这步不能跳过:

• 前面勾选的"Windows 功能"只是空房间;

• 这里下载的内核包才是真正的 Linux 内核、图形界面支持、GPU 加速等"工具箱";

• 装上之后 Ubuntu 才能真正跑起来。

国内网络注意:wsl --install 会访问 raw.githubusercontent.com,如果超时(报 WININET_E_TIMEOUT),用下面 1.4 的离线方案。

1.4 离线导入 Ubuntu(国内网络超时时的方案)

如果在线安装一直超时,采用手动下载镜像 + 离线导入:

第一步:下载 Ubuntu 的 WSL 镜像

到 Ubuntu WSL 官方发布页 下载对应版本的 .wsl 文件(例如 ubuntu-24.04.4-wsl-amd64.wsl,约 382MB),放到 D:\WSL\。

第二步:导入到指定位置

wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 D:\WSL\ubuntu-24.04.4-wsl-amd64.wsl --version 2

参数说明:

• Ubuntu-24.04:给这个发行版起的名字(后面 wsl -d 会用到)

• D:\WSL\Ubuntu-24.04:Ubuntu 实际存放位置

• ...amd64.wsl:镜像文件路径

• --version 2:使用 WSL 2 架构(性能更好)

1.5 首次启动与用户配置

wsl -d Ubuntu-24.04

首次进入默认是 root 用户。

创建普通用户(可选):

adduser opencode
usermod -aG sudo opencode

💡 如果你这个 WSL 环境只用来跑 OpenCode,可以像我一样直接用 root 操作,省去每次 sudo 切换的麻烦。专用环境用 root 是可以接受的。

1.6 配置默认进入主目录

默认情况下,在 Windows 地址栏输入 wsl 进入时,会停留在 /mnt/c/Users/你的用户名(Windows 盘),每次都要手动 cd ~。配置一下让它直接进主目录。

第一步:创建 /etc/wsl.conf

echo -e "[user]\ndefault=$(whoami)\n\n[automount]\noptions = \"metadata,umask=22\"" | tee /etc/wsl.conf

第二步:在 ~/.bashrc 末尾加一行 cd ~

echo "cd ~" >> ~/.bashrc && source ~/.bashrc

这行代码做的事:打开终端时自动从当前目录跳转到主目录 /root(或 /home/你的用户名)。

第三步:重启 WSL 让配置生效

回到 Windows 的 PowerShell:

wsl --terminate Ubuntu-24.04
wsl

之后无论是地址栏输入 wsl,还是在终端里敲 wsl,都会直接进入主目录。

---

二、OpenCode 安装

2.1 一行命令安装

curl -fsSL https://opencode.ai/install | bash

安装成功的标志:

• 终端打印出 OpenCode 的 ASCII Logo

• 提示 Successfully added opencode to $PATH in /root/.bashrc

❓ 为什么用 curl | bash 而不是 npm install? OpenCode 是 Rust 编译的独立二进制程序,不是 Node.js 包。npm 管的是 Node 生态,这里用不上。curl ... | bash 直接下载预编译二进制,无需先装 Node,最干净。

2.2 验证安装

opencode --version

2.3 避坑:command not found

如果安装成功但运行 opencode 却提示 command not found,别慌,这是正常的。

原因: 安装脚本把 opencode 的路径写进了 /root/.bashrc,但这只对下次登录或手动加载这个文件时才生效。你当前这个终端窗口还是"旧状态"。

解决: 手动加载一次配置:

source ~/.bashrc

之后再输入 opencode 即可正常启动。

📌 原理: 每次修改 .bashrc 后,需要 source 或新开终端窗口才能让新配置生效。

2.4 启动与工作目录

opencode

OpenCode 进入的是你执行命令时所在的目录:

• 在 /root 执行 → 工作目录是 /root

• 在 /mnt/c/Users/xxx 执行 → 工作目录是 Windows 盘(❌ 性能差,不推荐)

推荐习惯: 先进 WSL 内部项目目录,再启动:

cd ~/opencode-projects   # 先进入 WSL 内部的项目文件夹
opencode                  # 再启动

---

三、Git 与 GitHub 认证配置

OpenCode 生成代码后,你需要用 Git 提交到 GitHub。WSL 里虽然没主动装 Git,但 Ubuntu 24.04 默认预装了 Git(git --version 可以验证),不需要额外安装。

3.1 配置 Git 全局信息

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

3.2 选择认证方式:SSH 还是 HTTPS?

方式	协议 URL	凭证	配置方式
SSH	git@github.com:user/repo.git	私钥 + 公钥配对	私钥在本地,公钥传到 GitHub
HTTPS + Token	https://github.com/user/repo.git	Personal Access Token	credential.helper 缓存 token

推荐用 SSH。原因:

• HTTPS + Token 需要交互式弹出输入框,而 WSL 非交互环境下弹不出来,容易卡住;

• SSH 配好一次,以后 push/pull 都无感。

3.3 配置 SSH 认证(复制 Windows 的私钥到 WSL)

如果你 Windows 上已经配好了 GitHub SSH(用 VS Code / Git Bash 推过代码),最省事的做法是把 Windows 的私钥复制到 WSL:

# 1. 复制私钥(把 27844 换成你的 Windows 用户名)
cp /mnt/c/Users/27844/.ssh/id_ed25519 ~/.ssh/

# 2. 修正权限(关键!权限不对 SSH 会拒绝使用)
chmod 600 ~/.ssh/id_ed25519

⚠️ chmod 600 这步不能省。 从 Windows 复制过来的文件权限是"宽松"的,SSH 出于安全考虑,会拒绝读取权限过宽的私钥。不 chmod 会报 Permissions are too open 错误。

3.4 测试连接

ssh -T git@github.com

看到这行就说明成功了:

Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.

❓ 两台电脑能共用一个私钥吗? 能,私钥只是个文件,复制到哪台机器都能用。但更安全的做法是:每台机器一对密钥,GitHub 上保留多个公钥。共用一把私钥的风险是——丢了更容易被滥用。

3.5 (可选)配置 credential.helper

如果你还想用 HTTPS 方式推送,可以让 WSL 调用 Windows 的 Git Credential Manager 来缓存 token:

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

这只对 HTTPS 有效,和 SSH 互不冲突。已经用 SSH 的话可以忽略本节。

---

四、文件跨系统操作与 IDE 连接

4.1 WSL 不是传统虚拟机

很多人(包括之前的我)以为 WSL 像传统虚拟机(VMware/VirtualBox),可以随便拖拽文件。这是个误区:

特性	传统虚拟机	WSL 2
文件系统	完全隔离,靠"共享文件夹"传输	Linux 可直接访问 Windows 盘(/mnt/c/)
拖拽文件	安全的"复制"操作	跨文件系统的"直接读写"
权限处理	各自独立,传输时转换	直接读写可能破坏 Linux 文件权限

关键结论: 在 Windows 和 WSL 之间直接拖拽/复制零散文件,可能破坏 Linux 权限,导致:

• 脚本文件失去"可执行"权限(报 Permission denied)

• Git 仓库出现大量虚假变更

• 符号链接丢失(Windows 不支持)

4.2 什么时候可以直接复制?什么时候不行?

场景	方案
偶尔复制几个纯文本文件(.md/.txt/.json)	✅ 直接 cp 到 /mnt/c/,没问题
整个项目 / 含脚本的目录	❌ 用 Git 或打包传输
日常开发修改	❌ 用 IDE 远程连接,永远在 WSL 内部操作

关于"文件损坏"的说法澄清: 正常的纯文本文件(.java/.xml/.md)不会损坏。真正的风险不是内容损坏,而是权限变化导致的间接故障(脚本不能跑、Git 混乱)。所以偶尔复制几个文本文件是安全的,别被"会损坏"吓到。

4.3 推荐方案:用 IDE 远程连接 WSL

这是日常开发最舒服的方式:IDE 的界面在 Windows 显示,但所有文件操作都在 WSL 内部完成,完美隔离,零权限问题。

方案 A:VS Code / Trae(Cursor 同理)

1. 安装 Remote - WSL 扩展(或 Cursor/Trae 自带的远程功能)

2. 在 WSL 的项目目录下执行:

   cd ~/opencode-projects/my-project
   code .        # VS Code
   # 或 trae .   # Trae

3. IDE 会以"客户端-服务端"架构启动:UI 在 Windows,后端跑在 WSL 里。你可以直接修改、运行、调试,就像操作本地项目一样。

方案 B:JetBrains IDEA / WebStorm 等

官方当前主推的方式叫 "远程开发(Remote Development)",通过 JetBrains Gateway 启动:

1. 打开 JetBrains Gateway(和 IDEA 一起装的,在开始菜单里)

2. 选择 连接到在 WSL2 上运行的项目

3. Gateway 自动检测你的 WSL 发行版,选 Ubuntu → 指定项目路径 → 选 IDE 版本

4. 点 Download and Start IDE,它会在 WSL 里部署后端并启动 IDE

⚠️ 避坑: 目前 JetBrains 2026.1 版本 连接 WSL 有已知 Bug(报 Failed to find compatible JDK),建议暂用 2025.3.3 版本,等官方修复后再升级。

⚠️ IDEA 里也有一种"直接打开 WSL 路径"的方式(输入 \\wsl.localhost\Ubuntu\home\...),但这种方式 I/O 性能差,只适合临时测试,日常开发还是用 Gateway 远程开发。

4.4 需要把成品交到 Windows 时怎么办?

项目一直在 WSL 里开发,最终产物(比如 jar/war/exe)需要拿到 Windows:

# 在 WSL 里构建产物
mvn package

# 把产物复制到 Windows 桌面
cp target/*.war /mnt/c/Users/你的用户名/Desktop/

产物是单个文件,直接 cp 安全无虞。

---

五、完整工作流总结

经过以上全部配置,你的日常开发流程是这样的:

# 1. Windows 终端输入 wsl → 自动进入 /root 主目录
wsl

# 2. 进入项目文件夹
cd ~/opencode-projects/my-project

# 3. 启动 OpenCode 做 AI 辅助开发
opencode

# 4. 用 IDE 远程连接修改文件(在项目目录执行)
code .          # 或 trae .

# 5. 提交到 GitHub
git add .
git commit -m "feat: xxx"
git push

多环境共享: 通过 GitHub 做中转,其他电脑直接 git clone 即可拿到最新代码。

---

附录:常见问题速查

问题	原因	解决
wsl --install 一直超时	国内访问 githubusercontent 不稳	用离线导入方案(1.4 节)
路径报 ERROR_INVALID_NAME	--location 末尾多了 \	去掉末尾反斜杠
opencode: command not found	当前终端还没加载新配置	source ~/.bashrc
每次 wsl 都进 Windows 盘	没配默认目录	见 1.6 节
SSH 报 Permissions are too open	私钥权限太宽	chmod 600 ~/.ssh/id_ed25519
git clone HTTPS 卡住要输 token	非交互环境弹不出输入框	改用 SSH,见 3.3 节
IDEA 连 WSL 报 JDK 错	2026.1 版本 Bug	降到 2025.3.3
项目跑得慢	放在了 /mnt/c 下	移到 WSL 内部 ~ 目录

---

写完这篇,你已经具备了一套生产可用的 WSL + OpenCode 开发环境。遇到坑就翻附录速查,祝开发顺利!🚀