Featured image of post WSL 远程开发环境搭建：从 Maven 到 IDE 集成
编程

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

WSL 远程开发工作流：Maven 在 WSL 安装配置、环境变量、IDEA 集成 WSL 项目、Linux 命令行 + Windows IDE 的混合开发模式。

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 项目

  1. File → New → Project from Existing Sources
  2. 浏览路径，输入 \\wsl$\Ubuntu-22.04\path\to\project
  3. 或：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 1WSL 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
© 2006 - 2026 Liangweidong's blog
使用 Hugo 构建
主题 Stack 由 Jimmy 设计