WSL2 + Docker Desktop：Windows 下的完美 Java 开发环境

前言

作为一名 Windows 主力机用户，我曾在 Java 开发环境中饱受折磨：文件 I/O 慢、环境变量混乱、Docker 启动卡顿、路径分隔符反斜杠……直到 WSL2 + Docker Desktop 方案成熟，Windows 终于成为了一流的 Java 开发平台。

本文将带你从零开始，在 Windows 11 上配置一套高性能、跨平台、生产级的 Java 开发环境。所有步骤已在我的主力机上验证，最终效果：Spring Boot 构建速度提升 3 倍，Docker 容器与本地代码无缝协作。

本文属于 MACS Dev Hub “现代架构与编码解决方案”系列，前文已探讨 Maven vs Gradle 构建工具选型 和 Cursor AI 编程助手实战，建议先阅读。

一、为什么需要 WSL2 + Docker Desktop？

在 Windows 上开发 Java 应用，传统方案有两种：

• 原生 Windows 环境：JDK、Maven 直接安装在 Windows，Docker Desktop 使用 Hyper-V 虚拟机。缺点：文件 I/O 慢（尤其是大量小文件扫描），路径兼容性问题（\ vs /），Docker 挂载卷性能差。
• 纯 Linux 虚拟机：用 VirtualBox/VMware 装 Linux，然后远程开发。缺点：资源占用高，与 Windows 文件系统割裂。

WSL2 方案的优势：

• 内核级虚拟化：轻量级 Linux 虚拟机，启动快（1-2 秒），内存动态分配。
• 文件系统性能：在 WSL2 内部（\\wsl.localhost\Ubuntu\home\user\project）操作文件，接近原生 Linux 速度。
• 与 Docker Desktop 深度集成：Docker Desktop 可直接使用 WSL2 后端，无需独立虚拟机。
• IDE 支持：VS Code、IntelliJ IDEA 均可通过 Remote 方式连接 WSL2，体验如本地。

下表对比三种方案的关键指标（实测数据）：

结论：WSL2 在性能、启动速度、资源占用上全面超越传统虚拟机，且与 Windows 无缝集成。

二、从零配置 WSL2

2.1 启用 WSL

以管理员身份打开 PowerShell，执行：

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

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

# 重启计算机
Restart-Computer

2.2 设置 WSL2 为默认版本

wsl --set-default-version 2

2.3 安装 Linux 发行版

推荐 Ubuntu 22.04 LTS 或 24.04 LTS。在 Microsoft Store 搜索“Ubuntu”并安装，或使用命令行：

wsl --install -d Ubuntu-24.04

安装完成后启动 Ubuntu，设置用户名和密码。

验证 WSL 版本：

wsl --list --verbose

输出应显示 VERSION 2。

2.4 配置 WSL2 资源限制（可选）

创建 %UserProfile%\.wslconfig 文件，限制内存和 CPU 核心数（避免占用过多 Windows 资源）：

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

重启 WSL 生效：

wsl --shutdown

三、Docker Desktop 与 WSL2 集成

3.1 安装 Docker Desktop

从 Docker 官网 下载安装包。安装时勾选 “Use WSL 2 instead of Hyper-V”。

3.2 启用 WSL2 后端

打开 Docker Desktop → Settings → Resources → WSL Integration：

• 确保 “Enable integration with my default WSL distro” 开启
• 在下方选择你的 Ubuntu 发行版


3.3 在 WSL 中验证 Docker

进入 Ubuntu 终端，执行：

docker --version
docker run hello-world

如果看到欢迎消息，说明 Docker 已成功连接到 WSL2 的 Docker 守护进程。

关键点：此时 WSL2 内无需安装 Docker 服务端，直接使用 Windows 上的 Docker Engine，但性能与原生 Linux 一致。

四、配置 Java 开发环境（在 WSL 内）

为了最佳性能，所有项目代码、JDK、构建工具都应放在 WSL2 文件系统内（/home/yourname/），而不是 /mnt/c/。

4.1 安装 JDK 17/21

推荐使用 SDKMAN 管理多个 JDK 版本：

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 17.0.10-tem
sdk install java 21.0.2-tem
sdk default java 21.0.2-tem

验证：

java --version

4.2 安装 Maven 或 Gradle

同样使用 SDKMAN：

sdk install maven
sdk install gradle

关于 Maven 和 Gradle 的选择，可参考 Maven vs Gradle：2026 年 Java 项目构建选择指南。

4.3 配置 IDE 远程开发

VS Code（推荐新手）

安装扩展 “WSL”（Microsoft 官方）。点击左下角绿色按钮 → “Open Folder in WSL”，选择 WSL 内的项目目录。终端、调试、插件全部在 WSL 内运行。

IntelliJ IDEA

专业版支持 SSH 连接 WSL。设置 → Tools → SSH Configurations，添加 localhost:22（需先启动 WSL 内的 SSH）。或者使用 Gateway 方式。

五、核心难点：解决文件性能问题

很多开发者反映 WSL2 文件 I/O 慢，根本原因在于代码放在了 /mnt/c/（Windows 文件系统）下。跨文件系统访问时，WSL2 需要做路径转换和权限映射，导致性能急剧下降。

5.1 性能对比实测

我在同一个项目（Spring Petclinic）上测试不同存储位置：

结论：永远不要通过 /mnt/c/ 访问代码。应该将项目放在 WSL 内部。

5.2 迁移现有项目

如果代码已在 Windows 磁盘上，有两种方法：

1. 使用 cp 命令复制（推荐）：

   cp -r /mnt/c/Users/yourname/Projects/my-java-app /home/yourname/projects/

2. 通过 VS Code 直接克隆：在 WSL 终端内 git clone 到 ~/projects。

5.3 Docker 挂载卷也需指向 WSL 内路径

使用 docker run -v 时，务必挂载 WSL 内部路径，而不是 /mnt/c/ 路径：

# 正确做法
docker run -v /home/username/project:/app my-image

# 错误做法（慢）
docker run -v /mnt/c/Users/username/project:/app my-image

5.4 流程图：正确与错误的文件访问路径

六、实战：运行完整 Java + 数据库开发栈

我们用一个真实场景验证配置效果：Spring Boot + MySQL 容器，所有代码和配置都在 WSL2 内。

6.1 在 WSL 内创建 Spring Boot 项目

cd ~/projects
curl https://start.spring.io/starter.zip -d dependencies=web,data-jpa,mysql -d name=demo -o demo.zip
unzip demo.zip -d demo-app
cd demo-app

6.2 编写 docker-compose.yml

在项目根目录创建：

version: '3.8'
services:
  mysql:
    image: mysql:8.0
    container_name: local-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: demo
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 10s
      retries: 5

  app:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/demo
      SPRING_DATASOURCE_USERNAME: root
      SPRING_DATASOURCE_PASSWORD: root

volumes:
  mysql_data:

6.3 配置 Spring Boot 的 application.properties

spring.datasource.url=jdbc:mysql://localhost:3306/demo
spring.datasource.username=root
spring.datasource.password=root
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

6.4 启动服务

# 首次需构建镜像
docker-compose up -d --build

访问 http://localhost:8080，应用运行成功。查看容器状态：

docker-compose ps

6.5 清理资源

docker-compose down -v

七、常见问题与解决方案

八、总结与进阶建议

经过上述配置，你将获得一套媲美原生 Linux 的 Java 开发环境，同时保留 Windows 的 GUI 生态。核心要点：

• 代码必须放在 WSL2 内部文件系统（~/ 下），避免 /mnt/c/
• Docker Desktop 使用 WSL2 后端，无需单独维护 Linux 虚拟机
• IDE 通过 Remote 方式连接 WSL，编辑、编译、运行都在 Linux 内
• 利用 docker-compose 管理依赖服务（数据库、消息队列等）

下一步可以优化：

• 配置 oh-my-zsh 提升终端效率
• 使用 dive 分析 Docker 镜像层
• 结合 GitHub Actions 实现 CI/CD（参考后续文章）

本文环境：Windows 11 22H2 + WSL2 2.0.14 + Docker Desktop 4.26 + Ubuntu 24.04 + JDK 21。所有示例代码可在 MACS Dev Hub 找到。

下一篇计划探讨 Spring AI + Ollama 本地运行 LLM 生成 SQL，敬请期待。

Windows WSL2 Java开发环境配置、Docker Desktop WSL2集成、Spring Boot WSL2开发、Java文件性能优化、跨平台Java开发环境2026