WSL2 下的 Java 开发环境踩坑实录

文章目录

- [一、为什么折腾 WSL2？](#一、为什么折腾 WSL2？)
- 二、环境准备
- - [2.1 安装 WSL2](#2.1 安装 WSL2)
  - [2.2 安装基础工具链](#2.2 安装基础工具链)
- [三、IntelliJ IDEA 配置](#三、IntelliJ IDEA 配置)
- - [3.1 打开 WSL 中的项目](#3.1 打开 WSL 中的项目)
  - [3.2 配置 JDK 和 Maven](#3.2 配置 JDK 和 Maven)
  - [3.3 启动配置](#3.3 启动配置)
- 四、开发环境适配
- - [4.1 VPN 网络共享](#4.1 VPN 网络共享)
  - [4.2 Git SSL 证书问题](#4.2 Git SSL 证书问题)
- [五、项目问题：Swagger 中文丢失](#五、项目问题：Swagger 中文丢失)
- - [5.1 现象](#5.1 现象)
  - [5.2 排查思路](#5.2 排查思路)
  - [5.3 为什么 Windows 下正常？](#5.3 为什么 Windows 下正常？)
  - [5.4 解决方案](#5.4 解决方案)
  - [5.5 经验总结](#5.5 经验总结)
- [六、AI 编程助手：OpenCode 安装与配置](#六、AI 编程助手：OpenCode 安装与配置)
- - [6.1 安装 Node.js](#6.1 安装 Node.js)
  - [6.2 安装 OpenCode CLI](#6.2 安装 OpenCode CLI)
  - [6.3 配置模型提供商](#6.3 配置模型提供商)
  - [6.4 启动 OpenCode Web 界面](#6.4 启动 OpenCode Web 界面)
  - [6.5 基础使用](#6.5 基础使用)
  - [6.6 常用命令速查](#6.6 常用命令速查)
- 七、总结

记录一次从 Windows 迁移 Spring Boot 项目到 WSL2 开发环境时遇到的问题与解决过程。

一、为什么折腾 WSL2？

之前开发一直在 Windows 上，项目能跑，Swagger 能看，一切正常。最近想试试 AI 编程工具，据说这类工具对 Linux 环境的支持更好。为了跟上节奏，决定把开发环境迁到 WSL2试试。

结论先行：能跑，但有一堆小坑要填。

二、环境准备

2.1 安装 WSL2

确认系统版本：

Windows 10 版本 2004（Build 19041）或更高版本
Windows 11 任意版本（含家庭版）
CPU 必须支持虚拟化（Intel VT-x / AMD-V），并在 BIOS 中开启

确认系统版本后，以管理员身份打开 PowerShell，执行：

powershell 复制代码

# 1. 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. 重启电脑

# 4. 重启后，将 WSL2 设为默认
wsl --set-default-version 2

# 5. 安装 Ubuntu
wsl --install -d Ubuntu

安装完成后，在 Windows Terminal 中打开 Ubuntu 终端，设置用户名和密码即可。

2.2 安装基础工具链

进入 WSL 的 Ubuntu 环境后：

bash 复制代码

# 更新软件源
sudo apt update

# 安装 JDK 17
sudo apt install -y openjdk-17-jdk

# 安装 Maven
sudo apt install -y maven

# Git（Ubuntu 22.04+ 一般已自带，确认一下版本）
git --version

# 顺手装两个常用工具
sudo apt install -y curl vim

检查版本：

bash 复制代码

java -version
mvn -version
git --version

三、IntelliJ IDEA 配置

3.1 打开 WSL 中的项目

代码必须放在 WSL 的文件系统内（如 ~/projects/），不要放在 /mnt/c/ 下，否则编译和索引会慢到让人怀疑人生。

IDEA 欢迎界面 → Open → 在路径栏输入：

复制代码

\\wsl.localhost\Ubuntu\home\你的用户名\projects\your-project

3.2 配置 JDK 和 Maven

IDEA 打开 WSL 项目后，通常会自动识别 WSL 内的 JDK 和 Maven。如果没自动识别：

JDK ：File → Project Structure → Project → SDK → 选择 /usr/lib/jvm/java-17-openjdk-amd64
Maven ：File → Settings → Build Tools → Maven → Maven home path → /usr/share/maven

3.3 启动配置

点击 IDEA 右上角 Add Configuration → Spring Boot → Main class 选择启动类即可。

需要注意的是：代码和 Java 进程都跑在 WSL 里 ，IDEA 只负责显示界面。Windows 任务管理器里看不到 Java 进程，要在 WSL 中用 ps -ef | grep java 查看。

四、开发环境适配

4.1 VPN 网络共享

WSL2 默认是 NAT 网络，和 Windows 不在同一网段。Windows 连上 VPN 后，WSL 里拉不到内网依赖包------这是最常见的问题。

解决方案：开启 WSL 的镜像网络模式

在 Windows 用户目录下创建 .wslconfig：

复制代码

C:\Users\你的用户名\.wslconfig

内容：

ini 复制代码

[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

保存后，在 PowerShell 中执行：

powershell 复制代码

wsl --shutdown

重新打开 Ubuntu 终端，WSL 就会共享 Windows 的网络配置，VPN 对内网地址的访问在 WSL 中同样生效。

4.2 Git SSL 证书问题

从内网 Git 仓库 clone 代码时，可能会遇到：

复制代码

fatal: SSL certificate verification failed: certificate signer not trusted.

内网 Git 服务通常使用自签名证书，WSL 不认。

临时跳过（适合单次操作）：

bash 复制代码

git clone -c http.sslVerify=false https://内网地址/项目.git

全局跳过（适合内网开发环境）：

bash 复制代码

git config --global http.sslVerify false

⚠️ 全局跳过会降低安全性，仅限内网可信环境使用。

五、项目问题：Swagger 中文丢失

5.1 现象

项目使用 therapi-runtime-javadoc 将 Javadoc 转换成 Springdoc 的 Swagger 文档。

Windows 下跑项目 → Swagger 显示中文正常
IDEA 跑 WSL → Swagger 中文丢失，字段描述变成了方法名/英文
target/classes/META-INF/_Javadoc.json 文件已正常生成 → 说明不是生成阶段的问题

5.2 排查思路

Springdoc 的 Javadoc 自动配置会检查 classpath 中是否存在这个类：

复制代码

com.github.therapi.runtimejavadoc.CommentFormatter

只有检测到该类，Springdoc 才会启用 therapi 的 Javadoc 读取能力。

WSL 下的运行 classpath 比 Windows 更"干净"，某些可选依赖没有被传递进来，导致 CommentFormatter 不在 classpath 中，Javadoc 功能降级。

5.3 为什么 Windows 下正常？

项目中已经引用了 therapi-runtime-javadoc，但配置是：

xml 复制代码

<dependency>
    <groupId>com.github.therapi</groupId>
    <artifactId>therapi-runtime-javadoc</artifactId>
    <version>0.15.0</version>
    <optional>true</optional>
</dependency>

<optional>true</optional> 的作用是：该依赖不会传递给下游项目。Windows 下之所以能工作，是因为某些间接依赖或 IDE 的 classpath 计算碰巧把它带进来了，属于"侥幸"。

WSL 下的类加载环境更严格，这种"侥幸"不存在了。

5.4 解决方案

在当前项目的 pom.xml 中显式引用 该依赖，去掉 optional 标签：

xml 复制代码

<dependency>
    <groupId>com.github.therapi</groupId>
    <artifactId>therapi-runtime-javadoc</artifactId>
    <version>0.15.0</version>
</dependency>

显式引用后，无论在 Windows 还是 WSL 下跑，CommentFormatter 都会稳定出现在 classpath 中，Swagger 中文恢复。

5.5 经验总结

场景	是否需要显式引用
Windows 下跑（依赖传递侥幸带上）	不一定需要
WSL 下跑（classpath 更干净）	必须显式引用
生产环境部署	必须显式引用

依赖关系要在 pom 中显式声明，不要依赖传递带来的"侥幸"。 这不仅解决当前问题，也让构建结果更可预测。

六、AI 编程助手：OpenCode 安装与配置

环境搭好了，顺带把 AI 编程助手装上。这里选 OpenCode，原因很简单：开源、支持本地部署、可以配置自己的 API Key，不用被厂商锁定。

6.1 安装 Node.js

OpenCode 基于 Node.js，先装 Node.js 环境：

bash 复制代码

# 安装 nvm（Node 版本管理工具）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 安装 Node.js 22（OpenCode 要求 22 或更高）
nvm install 22

# 设为默认版本
nvm alias default 22

# 验证
node -v

6.2 安装 OpenCode CLI

bash 复制代码

# 全局安装
npm install -g opencode

# 验证安装
opencode --version

6.3 配置模型提供商

OpenCode 支持 OpenAI 兼容的 API，可以接入中转服务。

方式一：通过环境变量配置

bash 复制代码

# 在 ~/.bashrc 中添加
export OPENAI_API_KEY="你的API密钥"
export OPENAI_BASE_URL="https://你的中转地址/v1"

# 生效
source ~/.bashrc

方式二：通过配置文件

创建 ~/.config/opencode/opencode.json：

json 复制代码

{
  "provider": {
    "my-gpt-proxy": {
      "type": "openai",
      "name": "GPT 中转",
      "baseURL": "https://你的中转地址/v1",
      "apiKey": "你的API密钥"
    }
  },
  "model": "my-gpt-proxy/gpt-4o-mini"
}

6.4 启动 OpenCode Web 界面

OpenCode 提供了 Web 界面，可以通过浏览器操作：

bash 复制代码

# 启动 Web 服务
opencode web --port 3000

然后在浏览器打开 http://localhost:3000，就可以在 Web 界面中进行 AI 辅助编程了。

如果需要在后台持续运行：

bash 复制代码

# 使用 nohup 后台运行
nohup opencode web --port 3000 > ~/opencode.log 2>&1 &

# 查看日志
tail -f ~/opencode.log

6.5 基础使用

终端模式：

bash 复制代码

# 进入项目目录
cd ~/projects/your-project

# 启动 OpenCode 会话
opencode

# 输入 /help 查看所有命令

Web 模式：

浏览器访问 http://localhost:3000，直接输入需求即可。

6.6 常用命令速查

命令	作用
`opencode`	启动交互式会话
`opencode web --port 3000`	启动 Web 界面
`/init`	初始化项目上下文
`/help`	查看帮助
`/model`	切换模型
`/clear`	清空对话历史
`@文件名`	引用特定文件
`#指令`	执行特定任务

七、总结

WSL2 做 Java 开发是可行的，以下几点值得记住：

WSL2 不挑 Windows 版本（家庭版/专业版都行），挑的是系统版本号（Build 19041+）和 CPU 虚拟化支持
代码放 WSL 内 （~/projects/），不要放 /mnt/c/，否则性能感人
VPN 访问内网 需要配置 .wslconfig 开启镜像网络模式
内网 Git 证书问题 用 git config --global http.sslVerify false 绕过
Swagger 中文丢失本质是 classpath 中缺少依赖，不要指望传递依赖
IDEA 跑 WSL 是远程开发模式，Java 进程在 WSL 里，IDEA 只负责显示界面
OpenCode 推荐用 Web 模式，可以后台运行，随时访问