IDEA项目迁移至WSL2踩坑记录

1382 字

7 分钟

IDEA项目迁移至WSL2踩坑记录

2025-12-31

Development Environment

IntelliJ IDEA

/

WSL2

/

Java

/

Docker

/

Troubleshooting

1. 环境说明#

环境	版本
Windows 11	10.0.26100.7462
WSL	2.6.3.0
WSL内核	6.6.87.2-1
WSLg	1.0.71
IDEA	2025.3.1(支持远程WSL即可)

2. 为什么迁移？#

WSL2下的Linux拥有更好的文件读写性能，而且已经是高可用状态。

这种性能的影响其实更多在打包、代码索引、前端的node_modules索引以及Eslint索引时间大幅度缩短，论折腾也没有多折腾，是值得考虑的个人开发环境迁移。

3. WSL2配置#

在文件管理器中，输入%USERPROFILE%\.wslconfig

如果没有，那就在%USERPROFILE%下新建一个叫做.wslconfig的文件，注意这个文件没有文件拓展名称。

1
[wsl2]
2
# 开启镜像网络模式，让 WSL 和 Windows 共享网络 IP 和 localhost
3
networkingMode=mirrored
4

5
# 自动同步 Windows 的代理设置到 WSL
6
autoProxy=true
7

8
# 开启 DNS 隧道，解决网络访问（如 GitHub）慢或不通的问题
9
dnsTunneling=true
10

11
# 让 Windows 防火墙规则也对 WSL 生效
12
firewall=true
13

14
# 自动回收内存（推荐开启，防止 WSL 占用过多内存）
15
autoMemoryReclaim=gradual
16

17
# 内存超过后使用swap交互数据，内存够大的话可以不开
18
swap=4GB

4. 如果你使用了Docker Desktop#

4.1 若没有装任何Linux发行版#

去Microsoft store那边下载一个Ubuntu 22.04 LTS或者24.04.1 LTS版本，这个就是你以后的开发环境。

当然，不一定是Ubuntu，如果你有任何想用的Linux发行版都可以自行安装。

但是，这也涉及到一个坑点，WSL2的Linux内核并非是标准的Linux内核，是经过Patch的内核，表现还是有不同的地方。

对于我踩过的Arch来说，你很难正常在WSL2下使用，你跟Arch的更新之间肯定要死一个，常规开发环境建议Ubuntu就行了，跟Debian一同作为Microsoft维护的最好的两个发行版，对于个人来说省心。

我个人的踩坑记录是如果真的要使用Arch，那么需要使用：

1
pacman -Syu --ignore systemd,systemd-libs,systemd-sysvcompat

更新完后，备份一下再进行或许的折腾环节。

1
wsl --export Arch D:\WSL\Arch_base_backup.tar

不然你会一次次迷失在：

1
(73/89) upgrading systemd                                                [########################################] 100%
2
Creating group 'empower' with GID 972.
3
Creating group 'clock' with GID 971.
4
>wsl -d Arch
5
灾难性故障
6
错误代码: Wsl/Service/E_UNEXPECTED

经过Debug分析，我发现只要更新到systemd，systemd-libs，systemd-sysvcompat这三个模块，那么必定崩溃。

如果想要永久忽略systemd，则需要：

1
vi /etc/pacman.conf
2
# 找到#IgnorePkg这一行
3
IgnorePkg = systemd systemd-libs systemd-sysvcompat

这个时候你可能还会觉得这样就行了，但我就不得不说两句，你打这种猴子补丁是为了什么呢？你玩Arch不就是在享受它快速滚动更新么，当它在WSL2下做不到这点，说明它并不适合用于Windows。

当然，大佬无视这一点，如果能告诉我通用性解决方案或者告诉我为什么，感激不尽！

4.2 装好Linux发行版之后#

进入Docker:

Setting
Resource
WSL Integration

找到Enable integration with additional distros

在switch开关下enable你刚刚装的发行版。

这样完成后，你就能在你的Linux发行版下面直接跟docker的数据互通，其实本来Docker Desktop就是在你系统下开了个WSL。

5. 项目迁移#

在WSL2环境下，安装好maven之类的packages。

1
#我的项目是jdk-17，按你自己需求的来
2
sudo apt install openjdk-17-jdk
3
#或者使用sdkman管理你的sdk版本，建议去官网查看安装方式，会有变动，下面仅作参考：
4
curl -s "https://get.sdkman.io" | bash
5
source "$HOME/.sdkman/bin/sdkman-init.sh"
6
#maven
7
sudo apt install maven

其他也不需要我多赘述，你在Windows下开发需要什么包你就在WSL2下装什么packages，Linux安装这些环境比Windows舒服多了，不会就自己用LLM或者搜索引擎查。

将项目文件夹扔进IDEA内，打开IDEA在WSL2中的项目，它会自动使用远程模式。

注：IDEA版本需要支持WSL远程模式，如果还在2021~2022的版本，建议往上升级。

现在非Ultimate版本已经全面免费，也就是我们所说的Community社区版。

特别提醒：项目一定要在WSL2系统内，不是/mnt/c或者/mnt/d这样的目录，这样的目录你还是处于Windows文件系统下，WSL2本质上是个虚拟机，跨系统访问用的是网络I/O，如果是这种交互方式是得不偿失的，会非常慢。

下面就是重点，打开File->Settings

在Build,Execution,Deployment->Build Tools中，找到Maven

Key	Value
Maven home path	定位到你WSL中的Maven
User settings file	定位到你在WSL中.m2的settings.xml
Local repository	定位到你在WSL中.m2的repository

然后在Maven标签下的Runner的JRE中，选择你WSL中你安装的项目所需的Java SDK

最后，编辑一下你启动项目的那个文件配置：Edit Configurations...

将Build and run中的SDK设置为上面说到的JRE相同的SDK

这一步非常重要，不然你会发现项目启动总会给你报奇怪的错误。

至此迁移顺利完成。