WSL 远程开发环境搭建：从 Maven 到 IDE 集成

Sun, 15 Apr 2018 00:00:00 +0800

WSL 远程开发的核心理念

WSL 远程开发 = Linux 后端 + Windows 前端 IDE：

后端编译 / 构建 / 测试在 WSL（Linux 工具链）
前端编辑 / 调试 / Git 在 Windows（熟悉工具）
文件系统：项目放在 WSL，IDE 远程打开

好处：

Linux 工具链（apt、bash、coreutils）
Windows IDE（IntelliJ IDEA / VSCode / Cursor）
不需要 Dual Boot / VirtualBox
文件 IO 通过 9P 协议

WSL2 时代

2019 年 WSL2 GA 后，WSL 2 相比 WSL 1：

完整 Linux 内核
文件 IO 5~20 倍快
完整 syscall（Docker / ptrace / cgroups）

在 WSL 中安装 Maven

1. 准备

1
2
3
4
5
6
7
8


# 检查 WSL 版本
wsl -l -v
# NAME STATE VERSION
# Ubuntu-22.04 Running 2

# 切换默认用户为 root（可选）
# PowerShell 中：
wsl -u root -d Ubuntu-22.04

2. 下载 Maven

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 进入 WSL
wsl

# 切到 root（如有需要）
sudo su -

# 下载并解压到 /opt
cd /usr/local
sudo wget https://archive.apache.org/dist/maven/maven-3/3.9.14/binaries/apache-maven-3.9.14-bin.tar.gz

# 解压
sudo tar -zxvf apache-maven-3.9.14-bin.tar.gz -C /opt/

# 创建符号链接
sudo ln -s /opt/apache-maven-3.9.14 /opt/maven

3. 配置环境变量

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 写入 ~/.zshrc
sed -i '$a \
export M2_HOME=/opt/maven \
export PATH=$M2_HOME/bin:$PATH' ~/.zshrc

# 验证
cat ~/.zshrc | tail -5

# 重新加载
source ~/.zshrc

# 验证 Maven
mvn -v

输出：

1
2
3
4
5


Apache Maven 3.9.14 (9b613dcf7b...)
Maven home: /opt/maven
Java version: 21.0.10, vendor: Liberica, runtime: ...
Default locale: en, platform encoding: UTF-8
OS name: "linux", version: "...", arch: "amd64", family: "unix"

4. 配置 Maven 镜像

1
2


# 修改 settings.xml
nvim /opt/maven/conf/settings.xml

1
2
3
4
5
6


<mirror>
 <id>aliyun-public</id>
 <name>阿里云公共仓库</name>
 <url>https://maven.aliyun.com/repository/public</url>
 <mirrorOf>central</mirrorOf>
</mirror>

5. 用 sdkman 管理多版本（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 安装 sdkman
curl -s "https://get.sdkman.io" | bash
source ~/.sdkman/bin/sdkman-init.sh

# 装多个 Maven
sdk install maven 3.9.14
sdk install maven 3.8.9

# 切换
sdk use maven 3.9.14

IDE 集成 WSL

IntelliJ IDEA

打开 WSL 项目

File → New → Project from Existing Sources
浏览路径，输入 \\wsl$\Ubuntu-22.04\path\to\project
或：File → Open → Recent → WSL

配置 Maven 路径

Settings → Build, Execution, Deployment → Build Tools → Maven

Maven home directory: \\wsl$\Ubuntu-22.04\opt\maven
或：/opt/maven（用 WSL 内部路径）
User settings file: \\wsl$\Ubuntu-22.04\home\<user>\.m2\settings.xml
Local repository: \\wsl$\Ubuntu-22.04\home\<user>\.m2\repository

2024+ 的 IDEA Ultimate 支持 WSL 集成，直接识别 WSL 发行版，无需 \\wsl$ 前缀。

远程 SDK

Project Structure → Platform Settings → SDKs → + → WSL

选择 WSL 发行版（Ubuntu-22.04）
选择 Java 路径（如 /opt/jdk21）
OK

运行 / 调试

IDEA 直接在 WSL 中执行 mvn 命令。Console 输出在 WSL 终端（可在 IDEA 内部显示）。

VSCode / Cursor

安装 WSL 扩展

WSL（Microsoft 官方）

在 WSL 中打开

1
2
3
4
5


# PowerShell 中
wsl -d Ubuntu-22.04
code .
# 或
cursor .

配置

.vscode/settings.json：

1
2
3
4


{
 "remote.WSL.fileSystem.polling": true,
 "terminal.integrated.defaultProfile.linux": "zsh"
}

文件系统性能

WSL 1 vs WSL 2

场景	WSL 1	WSL 2
启动速度	快	中
文件 IO	慢（9P 桥接）	快（虚拟磁盘）
系统调用兼容	部分	完整
内存管理	共享	独立 VM

项目放哪？

位置	推荐	原因
WSL 内部（如 `~/projects/`）	✅	文件 IO 快
Windows（如 `C:\projects\`）	❌	跨 OS 文件 IO 慢

经验法则：把项目放在 WSL 文件系统（如 ~/projects/），IDE 通过 \\wsl$\... 访问。

WSL 配置

.wslconfig（Windows 用户目录）

1
2
3
4
5
6
7


[wsl2]
memory=4GB # 限制 WSL 内存
processors=4 # 限制 CPU 核数
swap=8GB # Swap 大小
swapFile=D:\wsl-swap.vhdx
localhostForwarding=true
sparseVhd=true # 自动压缩 vhdx

wsl.conf（WSL 内部）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# /etc/wsl.conf
[automount]
enabled=true
options=metadata,umask=022
mountFsTab=true

[network]
generateHosts=true
generateResolvConf=true

[interop]
enabled=true
appendWindowsPath=true

常见工作流

工作流 1：纯 Linux 开发

1
2
3
4
5


wsl
cd ~/projects/my-app
# 用 vim / nano / emacs 编辑
mvn clean package
java -jar target/my-app.jar

工作流 2：混合开发（推荐）

Windows 端：IDEA / VSCode / Cursor 打开项目
后端编译运行在 WSL
数据库 / Redis / Nginx 用 docker compose（WSL 内）
浏览器 / Postman / 数据库客户端在 Windows

工作流 3：远程 SSH 风格

1
2
3
4
5


# 用 Windows Terminal + SSH 客户端
ssh user@your-wsl-host

# 或直接 PowerShell 进入
wsl ~ -d Ubuntu-22.04

Docker in WSL

WSL2 内 Docker 部署有 3 种方案：

方案 1：Docker Desktop for Windows（推荐）

自动用 WSL2 后端
Docker CLI 也在 WSL 中可用
适合一般场景

方案 2：WSL 独立 Docker daemon

1
2
3
4


# 在 WSL 内安装 docker.io
sudo apt install -y docker.io
sudo systemctl start docker
sudo usermod -aG docker $USER

方案 3：Rancher Desktop / Podman

轻量替代 Docker Desktop
完全开源

网络访问

WSL2 通过 localhost 与 Windows 互访：

WSL 访问 Windows：http://host.docker.internal 或 \\wsl$\
Windows 访问 WSL：http://localhost:<port>（WSL 转发到 Windows localhost）

1
2


# .wslconfig
localhostForwarding=true

调试案例

问题 1：Maven 找不到 JAVA_HOME

1
2
3
4
5
6
7


# 检查
echo $JAVA_HOME
which java
java -version

# 设置
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

问题 2：IDEA 找不到 WSL 路径

Settings → Appearance & Behavior → System Settings → WSL：

启用 WSL 集成
选择发行版

问题 3：文件修改无响应

IDEA 默认每 3 秒刷新文件。WSL 文件变更需要更频繁：

1
2
3
4
5
6
7


// .vscode/settings.json
{
 "files.watcherExclude": {
 "**/target/**": true,
 "**/node_modules/**": true
 }
}

项目级 init 脚本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


#!/bin/bash
# ~/bin/dev-env.sh

# 安装基础工具链
sudo apt update
sudo apt install -y openjdk-21-jdk maven nodejs npm zsh git curl

# 安装 oh-my-zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
chsh -s $(which zsh)

# 安装 sdkman
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 安装 Maven
sdk install maven 3.9.14

# 装 IDEA 替代品（可选）
# ...

完整开发体验检查清单

WSL2 已启用
zsh + oh-my-zsh + Powerlevel10k
fcitx5 五笔
sdkman 管理 JDK / Maven
Docker Desktop 或 WSL Docker
Git 配置（user.name / user.email）
SSH key 已加到 GitHub
项目在 ~/projects/（WSL 文件系统）
IDE 通过 \\wsl$\... 打开
中文字体（Cantarell / Fira Code / Meslo）

下一步

WSL 完整使用手册，看 2017-01-15《WSL2 完整使用手册》
Linux 工作站基础配置，看 2014-01-15《Linux 工作站基础配置》
远程开发常见问题排查，看 2018-04-15 后 WSL2 高级用法

参考资料

WSL 官方文档：https://learn.microsoft.com/en-us/windows/wsl/
Maven 官方：https://maven.apache.org/
sdkman：https://sdkman.io/
IntelliJ IDEA WSL 集成：https://www.jetbrains.com/help/idea/how-to-use-wsl-development-environment.html

远程开发 on Liangweidong's blog