# WSL

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt).

> **Warning:**
> 要使用 Gradle 或 Maven 项目，请确保   远程执行代理：二进制文件  已 [启用](managing-plugins.html)。

[WSL](https://docs.microsoft.com/en-us/windows/wsl/about)（ [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-index)）——Windows Subsystem for Linux——是一个兼容层，用于在 Windows 10 及更高版本上本地运行 Linux 二进制可执行文件。 目前，它支持若干 [Linux 发行版](https://docs.microsoft.com/windows/wsl/install-win10#windows-10-fall-creators-update-and-later-install-from-the-microsoft-store)，例如 Ubuntu、OpenSUSE 和 SLES。

IntelliJ IDEA 允许您在 WSL 文件系统中创建和打开项目，并在 WSL 环境中运行和调试应用程序。 您还可以使用基于 Windows 的本地项目，并使用 [run targets](run-targets.html)功能在 WSL 中远程运行应用程序。

Procedure: 配置 WSL

1. 在 Windows 设备上，从 [Microsoft Store](https://jb.gg/clion-wsl) 下载并安装一个 WSL 发行版（例如 Ubuntu）。

对于此步骤，请务必使用 Windows 10 或更高版本，并安装最新的“秋季创意者更新”（最低版本 1709，构建 16299.15）。 请参阅官方指南 [Install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)了解详细说明。

要使用   WSL 2  ，您的 Windows 版本应为 10 版本 18917 或更高版本。 请遵循 [这些指示](https://docs.microsoft.com/windows/wsl/wsl2-install#set-a-distro-to-be-backed-by-wsl-2-using-the-command-line)来切换分布式。

请注意，IntelliJ IDEA 不支持   旧版 WSL  ，该项可能是在将系统升级到 Windows 10 构建 16299.15 或更高版本之前安装的。 在这种情况下，您需要更新您的 WSL 发行版。

2. 运行 Linux 发行版。

首次启动时，系统可能会提示您启用 Windows 可选功能。 在这种情况下，您需要执行以下操作：

* 以管理员身份打开 Windows PowerShell 并运行 ```SHELL Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux ```

* 重新启动您的计算机。

> **Note:**
> 如果您使用的是除 Ubuntu 之外的 Linux 发行版，请确保该发行版已安装 [iproute2](https://wiki.linuxfoundation.org/networking/iproute2) 包，或在部署 WSL 实例后手动安装它。

您可以创建一个项目并将其存储在 WSL 环境中，从 WSL 文件系统中打开一个项目，并在 WSL 中进一步开发您的项目。

Procedure: 在 WSL 文件系统中创建一个新项目

1. 像平常一样在 Windows 本地 [安装并运行](installation-guide.html) IntelliJ IDEA。

2. 在欢迎屏幕上，点击   新建项目  。

3. 在打开的页面上，选择以下选项：

* 名称 ：输入您的项目名称。

* 创建 Git 仓库 ：如果要将您的项目添加到 Git，请选中此复选框。

* 位置 ：指定您的新项目在 WSL 上的位置。 项目路径的语法如下： ``` \\wsl.localhost\DistributionName\home\UserName\ProjectName ``` `DistributionName` 是 Linux 发行版名称， `UserName` 是您的用户目录名称。 请查看以下示例： `\\wsl.localhost\Ubuntu\home\test\MyProject` 。

* 构建系统 ：为您的项目指定构建工具。

* JDK ：指定位于 WSL 上的项目 SDK。

* 添加示例代码 ：选择此选项以让 IntelliJ IDEA 向您的项目添加简单、可运行的代码。

* 高级设置 ：根据您的项目，设置将包含附加选项。

![新项目：project sdk](https://resources.jetbrains.com/help/img/idea/2026.3/new_project_wsl.png)

4. 点击   创建  。

![在 WSL 中选择项目位置](https://resources.jetbrains.com/help/img/idea/2026.3/rm_wsl_create_project_settings.png)

IntelliJ IDEA 会创建位于 WSL 中的项目，并且可以在不离开 IDE 的情况下，在 WSL 环境中开发和构建项目。

Procedure: 在 WSL 文件系统中打开项目

在 IntelliJ IDEA，您可以直接打开存储在 WSL 文件系统中的项目，并像处理其他项目一样进行操作。

1. 请点击   打开   在 [欢迎屏幕](null)或从主菜单中选择  `文件 | 打开` 。

2. 在打开的对话框中，选择 WSL 文件系统中包含要打开项目的文件夹，或手动键入项目位置的路径。

路径语法为  `\\wsl.localhost\DistributionName` ，其中  `DistributionName`  是您的 Linux 发行版名称，例如 Ubuntu、Debian、Arch 等。

![打开存储在 WSL 文件系统中的项目](https://resources.jetbrains.com/help/img/idea/2026.3/open_project.png)

> **Tip:**
> IntelliJ IDEA 支持适用于 Linux 的 Windows 子系统 2 (WSL2) 中的 Git，该子系统可在 [Windows 10 版本 2004](https://devblogs.microsoft.com/commandline/wsl2-will-be-generally-available-in-windows-10-version-2004/) 中使用。
>
>
>
> 如果 Windows 上未安装 Git，IntelliJ IDEA 会在 WSL 中搜索 Git 并从那里使用它。 此外，当使用  `\\wsl$`  路径打开项目时，IntelliJ IDEA 会自动切换为使用来自 WSL 的 Git。
>
>
>
> 在 IntelliJ IDEA 中使用 Git 有关的更多信息，请参阅 [Git](using-git-integration.html)。

Procedure: 配置项目位置

可以确保创建或打开的任何项目都使用合适的 WSL 位置。

1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `外观与行为 | 系统设置` 。

2. 在   项目   部分下的   默认项目目录   字段中，指定合适的 WSL 目录，然后点击   OK   以保存更改。

![默认项目目录](https://resources.jetbrains.com/help/img/idea/2026.3/default_project_directory.png)

从现在起，每当 [创建](#create_project_for_wsl)、 [打开](#open-a-project-in-wsl)或 [克隆](set-up-a-git-repository.html#clone-repo)项目时，都会默认选择指定的目录。

当您 [运行](running-applications.html)项目中的代码时，它是在 WSL 中运行的。 如果您打开运行配置，请注意 IntelliJ IDEA 指的是 WSL 作为本地机器。

![运行配置](https://resources.jetbrains.com/help/img/idea/2026.3/run_configuration_wsl.png)

代码执行结果显示在   运行  工具窗口中。

> **Tip:**
> 如果需要使用终端，可以无需为 WSL 项目进行任何其他配置。

## 使用 WSL 在 Windows 文件系统中运行项目

您可以在 Windows 操作系统上使用本地 JDK [创建](new-project-wizard.html)或 [打开](import-project-or-module-wizard.html)您的项目，然后使用 [run targets](run-targets.html) 在 WSL 中运行已编译的代码。 这可能对 跨平台开发 有帮助。

> **Note:**
> 仅在 IntelliJ IDEA Ultimate 版中支持运行目标功能。

> **Note:**
> 在 IDE 中使用 WSL 功能之前，您可能需要配置 [防火墙设置](#debugging_system_settings)。

Procedure: 为 WSL 创建运行配置

1. 在主菜单中，点击  `运行 | 编辑配置` 。或者，按 `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (NetBeans), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS))，然后 `0` (Windows), `0` (macOS), `0` (IntelliJ IDEA Classic (macOS)), `0` (macOS System Shortcuts), `0` (XWin), `0` (GNOME), `0` (KDE), `0` (Emacs), `0` (Sublime Text), `0` (Sublime Text (macOS)), `0` (Visual Studio), `0` (Visual Studio (macOS)), `0` (NetBeans), `0` (Eclipse), `0` (Eclipse (macOS))。

2. 选择一种 [受支持的](run-targets.html#supported-rcs) 运行/调试配置类型。

3. 在   运行   菜单的   新目标   部分中，选择   WSL   以添加一个   WSL   目标。

当您添加 WSL 目标时，IntelliJ IDEA 会进行内省，并自动添加 WSL 中远程 JDK 的路径以及   新目标：WSL   对话框中的 JDK 版本。

![新目标：WSL](https://resources.jetbrains.com/help/img/idea/2026.3/new_target_wsl.png)

4. 如果您需要向现有的 WSL target 添加其他信息，请点击   管理目标…  ，然后在   运行目标  对话框中添加所需的信息。 例如，您可以选择 Maven 或 Gradle 作为运行时。 点击   OK   保存更改。

![运行目标对话框](https://resources.jetbrains.com/help/img/idea/2026.3/run_target_dialog.png)

5. 在主菜单中，转到   运行  并选择所需的运行配置，或按下( `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS)))运行您的代码，并在   运行  工具窗口中查看输出。

## 防火墙配置

您需要执行以下步骤以确保项目构建正常运行。

Procedure: 配置防火墙设置

1. 以管理员身份运行   Windows PowerShell  。

![将防火墙恢复为默认设置](https://resources.jetbrains.com/help/img/idea/2026.3/wsl_prep_debugging_firewall.png)

2. 使用以下命令检查确切的接口名称，例如  `vEthernet (WSL)` 、  `vEthernet (WSL2)` ，或者如果您重命名了它，则为其他名称：

```
Get-NetAdapter

```

3. 执行以下命令以允许使用 WSL 进行连接：

```
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound  -InterfaceAlias "vEthernet (WSL)"  -Action Allow

```

4. 然后执行命令以更新防火墙规则：

```
Get-NetFirewallProfile -Name Public | Get-NetFirewallRule | where DisplayName -ILike "IntelliJ IDEA*" |
Disable-NetFirewallRule

```

> **Note:**
> 如果您使用的是其他 IDE，请将  `IntelliJ IDEA*`  替换为其名称。

5. 现在 [start the debugger session](starting-the-debugger-session.html) 。 当   Windows 防火墙   弹出窗口出现时，选择   公共网络   复选框。

![允许公用网络](https://resources.jetbrains.com/help/img/idea/2026.3/windows_security_alert.png)

## WSLg

[WSLg](https://devblogs.microsoft.com/commandline/wslg-architecture) 可用于运行 Linux GUI 应用程序，并在 Windows 桌面上显示其输出。

不建议通过 WSLg 运行 IntelliJ IDEA。 IntelliJ IDEA 已提供原生 WSL 集成，这是首选方式。

请记住以下几点:

* WSLg 在渲染、弹出窗口、窗口管理、输入方法和桌面集成方面存在限制。

* 对于通过 WSLg 运行 IntelliJ IDEA，我们不提供专门支持、安装指导、入门引导或产品特定修复。

要了解如何打开项目，请参阅 [在 WSL 文件系统中打开项目](#open-a-project-in-wsl)；如果想创建新项目，请参阅 [在 WSL 文件系统中创建一个新项目](#create_project_for_wsl)。

## See also