WSL
WSL (WSL 2 )——Windows Subsystem for Linux——是一个兼容层,用于在 Windows 10 及更高版本上本地运行 Linux 二进制可执行文件。 目前,它支持若干 Linux 发行版 ,例如 Ubuntu、OpenSUSE 和 SLES。
通过为您的项目设置 WSL 工具链 ,您可以使用来自 Linux 的工具链进行构建,并在 WSL 上运行/调试,而无需离开运行在 Windows 机器上的 WebStorm。
配置 WSL
在 Windows 计算机上,从 Microsoft Store 下载并安装一个 WSL 发行版(例如 Ubuntu)。
此步骤请务必使用至少 Windows 10 或更高版本,并安装最新的“秋季创作者更新”(最低版本 1709,构建 16299.15)。 请参阅官方指南 Install the Windows Subsystem for Linux了解详细说明。
要使用 WSL 2 ,您的 Windows 版本应为 10 版本 18917 或更高版本。 请遵循 这些指示来切换分布式。
运行 Linux 发行版。
首次启动时,系统可能会提示您启用 Windows 可选功能。 在这种情况下,您需要执行以下操作:
以管理员身份打开 Windows PowerShell 并运行
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux重新启动您的计算机。
安装 Node.js 和 npm
在 Linux(Ubuntu)安装中,确保已安装 nvm、Node.js 和 npm。 有关详细的安装说明,请参阅 在 Windows Subsystem for Linux 上安装 Node.js。
打开命令行 shell 或嵌入式 终端 (Alt+F12)。
安装
cURL:sudo apt-get install curl安装
nvm:curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash通过运行以下命令之一安装 Node.js:
nvm install --lts以安装稳定的长期支持版 Node.jsnvm install node以安装或当前发布版本
您可以创建一个项目并将其存储在 WSL 环境中,从 WSL 文件系统中打开一个项目,并在 WSL 中进一步开发您的项目。
在 WSL 文件系统中创建一个新项目
安装并运行 WebStorm,就像您通常在 Windows 上本地运行一样。
在欢迎屏幕上,单击 新建项目。

在打开的对话框中:
从左侧窗格的列表中选择项目类型。
在右侧窗格中指定项目名称和位置。 WSL 的项目位置将显示以 \\wsl$ 开头的 WSL 文件系统的绝对路径。

通常,WebStorm 会要求您指定 Node.js 的位置。 如果您尚未安装 Node.js,请从列表中选择 下载。 或者,选择 添加 以配置 WSL Node.js 解释器。

然后从弹出窗口中选择 添加 WSL。

在打开的 添加 WSL Node.js 运行时 对话框中,指定当前使用的 Linux 发行版和 Node.js 的路径。

填写右侧窗格中的其他字段。 字段的设置取决于所选的项目类型。 有关详细信息,请参阅 其他语言和框架 下的相关文章。
点击 创建。

WebStorm 会创建一个位于 WSL 中的项目,您可以在不离开 IDE 的情况下,在 WSL 环境中开发和构建项目。
在 WSL 文件系统中打开项目
在 WebStorm,您可以直接打开存储在 WSL 文件系统中的项目,并像处理其他项目一样进行操作。
请点击 打开 在 欢迎屏幕或从主菜单中选择 。
在打开的 选择路径对话框中,选择 WSL 文件系统中包含要打开项目的文件夹,或者手动输入项目位置的路径。
路径语法为
\\wsl.localhost\DistributionName,其中DistributionName是您的 Linux 发行版名称,例如 Ubuntu、Debian、Arch 等。
配置项目位置
可以确保创建或打开的任何项目都使用合适的 WSL 位置。
配置基于 WSL 的 Node.js 运行时
您可以将 Node.js 安装设置为 当前项目的默认运行时 ,或者您可以在 Node.js 运行/调试配置中配置并使用此 Node.js 版本。
在 设置 对话框(Ctrl+Alt+S ),转到 。
单击
,该控件位于 Node.js 运行时 字段旁;在打开的 Node.js 运行时 对话框中,单击
,然后从列表中选择 添加 WSL。

在打开的 添加 WSL Node.js 运行时 对话框中,选择您正在使用的 Linux 发行版并指定 Node.js 的路径。

配置的 Node.js 安装已添加到列表中,并设置为当前项目的默认值。

运行和调试您的项目
当您运行或调试应用程序时,它将在 WSL 中运行。 如果您打开运行配置,请注意 WebStorm 指的是 WSL 作为本地机器。
根据您的应用程序类型, 创建运行/调试配置。 为此,请转到 。 然后在 运行/调试配置 对话框中,点击工具栏上的
,并选择所需的运行/调试配置类型。 在打开的对话框中,根据需要填写字段或接受预定义值。

要运行您的应用程序,请从 运行 小部件中选择新创建的运行/调试配置,然后点击其旁边的
。
要调试您的应用程序,请在必要的位置设置断点,从 运行 小部件中选择新创建的运行/调试配置,然后点击其旁边的
。

WSLg
WSLg 可让您运行 Linux GUI 应用程序,并在 Windows 桌面上显示其输出。
不建议通过 WSLg 运行 WebStorm。 WebStorm 已提供原生 WSL 集成,这是首选方法。
请注意以下内容:
WSLg 在渲染、弹出窗口、窗口管理、输入法和桌面集成方面存在限制。
对于通过 WSLg 运行 WebStorm,我们不提供专门支持、安装指导、新手引导或产品特定的修复。
要了解如何打开项目,请参阅 在 WSL 文件系统中打开项目 ;如果要创建新项目,请参阅 在 WSL 文件系统中创建一个新项目。
提示与技巧
将 WSL 作为日常开发工作流的一部分时,需要做出几个重要选择,这些选择可能会影响性能、兼容性和易用性。
选择文件系统
在 Windows 上使用 WSL 创建项目时,本质上的选择是在 Windows 文件系统中存储项目(例如,在 C:\Users\...\project 中),还是在 WSL/Linux 文件系统中存储项目(例如,在 ~/projects/project 中)。 最佳选择主要取决于开发工具和运行时的执行位置。
当大部分开发环境在 Windows 上原生运行时,请选择 Windows 文件系统 ( C:\Users\me\project ),也就是说,当您使用以下内容时:
Windows Node.js 和 npm/yarn/pnpm
Windows 版 Git
基于 Windows 的终端
可使用 Windows 路径的 Windows Docker 工具
需要频繁直接访问项目文件的其他 Windows 应用程序
主要优势是 Windows 应用程序可以正常、快速地访问项目文件。
当从 WSL 运行 Linux 工具来处理这些文件时,就会出现缺点。 文件会在诸如 /mnt/c/Users/me/projects/my-app 的路径下公开。 跨越此 Windows/Linux 边界的文件操作可能会更慢,尤其是对于包含大量小文件的 Web 项目,例如 node_modules 。 文件监视也可能更加麻烦。
当应用程序的运行时和开发工具链主要在 WSL 上运行时,请选择 WSL 文件系统( /home/me/projects/my-app 或直接使用 ~/projects/my-app )。 例如:
WSL 上的 Git
Linux shell 脚本
基于 Linux 的构建工具
具有 WSL 集成的 Docker
基于 Linux 的测试和开发服务器
此方法的主要优势是 Linux 工具可以访问原生 Linux 文件系统。 此方法的主要优势是 Linux 工具可以访问原生 Linux 文件系统。 涉及数千个文件的操作,例如依赖项安装、索引、编译、测试和文件监视,通常在那里表现得更自然。
它还会使开发环境更接近持续集成和生产中常用的 Linux 环境。
选择 WebStorm 访问文件的方式
如果项目文件存储在 WSL 文件系统上,则需要选择 WebStorm 访问这些文件的方式以及其后端运行的位置。
WebStorm 安装在 Windows 上,并 访问 WSL 上的文件。
当桌面便利性比让整个开发堆栈在 Linux 内部执行更重要时,此配置最有意义。
主要优势是可以保留正常的 Windows 桌面应用程序: Windows 快捷键、窗口管理、浏览器集成、凭据存储、字体和其他桌面集成将继续自然运行。
缺点是 WebStorm 和项目位于 Windows/Linux 边界的两侧。 根据 WebStorm 架构,索引、文件监视、Git 操作和解析大型依赖项树等操作可能涉及跨系统文件访问。
WebStorm 安装在 Windows 上,并在 远程开发模式下访问 WSL 上的文件。
对于强烈面向 WSL 的 Web 开发工作流,将项目存储在 WSL 上,并将 WebStorm 与 WSL 上的远程后端配合使用,通常是架构上最一致的选择。
主要优势是 Linux 原生开发。 这对于以 WSL 为中心的工作流尤其有吸引力,因为计算密集型项目操作发生在 WSL 内部,靠近文件。 例如,IDE 后端可以索引 ~/projects/my-app ,同时 Node.js、npm、Git、TypeScript、ESLint 和其他工具也在 WSL 上执行。
可以同时获得两个好处: 原生 Windows UI 和 Linux 原生项目环境。 对于工具假定 Linux 语义、使用 Linux shell 脚本、严重依赖符号链接或权限,或者具有大型 node_modules 树的项目,这会特别有价值。
WebStorm 的 Linux 版本访问 WSL 上的文件。 WebStorm GUI 通过 WSLg 显示。
虽然此方法看起来有益,因为所有内容都在同一个 Linux 环境中运行,但通过 WSL 运行的 WebStorm Linux 版本仍然是 Linux GUI 应用程序,而不是原生 Windows 应用程序。 因此,与 Windows 应用程序、浏览器、凭据管理器、通知、文件对话框和类似桌面设施的集成可能不那么无缝。
解决热重载和其他读/写问题
如果将项目保留在 Windows 文件系统上,但在 WSL 内部运行开发服务器或工具,热重载和某些读/写操作可能会变得不太可靠,因为 Linux 进程正在通过 Windows 挂载的路径监视文件,通常为:
强烈建议避免将这种跨文件系统设置用于构建系统、 node_modules 和 Git 密集型工作流,因为这会带来额外的输入/输出开销。
具体到热重载,常用的解决方法是将文件监视器从原生事件切换为轮询,这意味着开发服务器会定期检查文件,例如其修改时间戳,以查看它们是否已更改。
当 Vite 在 WSL2 上运行且文件由 Windows 进程编辑时,文件监视可能无法工作,而
usePolling: true是回退方案。 代价是 CPU 使用率更高。export default defineConfig({ server: { watch: { usePolling: true, }, }, })使用基于轮询的监视配置:
module.exports = { watchOptions: { poll: 1000, // Check for changes every second }, };使用默认或特定间隔进行轮询。
const wp = new Watchpack({ poll: true // Check for changes at a default interval });或:
const wp = new Watchpack({ poll: 1000 });- import chokidar from 'chokidar'; const watcher = chokidar.watch('.', { usePolling: true });
对于其他读/写问题,重要措施是尽可能保持环境一致。 如果项目保留在 C:\... 上,请从 WSL 使用 /mnt/c/... ,避免针对同一 node_modules 混用 Windows 和 Linux 版本的软件包管理器,并注意权限、大小写敏感性、符号链接和可执行位。 WSL 通过 DrvFS 映射 Windows 文件,并且这些文件上的 Linux 权限行为与原生 Linux 文件系统上的权限并不完全相同;WSL 可以选择在 Windows 文件上存储 Linux 权限元数据。
示例: 在启用轮询的情况下运行 Vite 开发服务器
在 Windows 文件系统的 C:\projects\my-app 处创建 Vite 项目。
确保项目 package.json 包含用于启动 Vite 开发服务器的脚本:
{ "scripts": { "dev": "vite" } }从 WSL 运行开发服务器。
WSL 将项目视为 /mnt/c/projects/my-app 。
在 vite.config.ts 中,启用轮询:
import { defineConfig } from 'vite' export default defineConfig({ server: { watch: { usePolling: true, }, }, })从 WSL 终端导航到项目并启动 Vite:
cd /mnt/c/projects/my-app npm install npm run devVite 会启动开发服务器,通常位于
http://localhost:5173/在 Windows 上的 WebStorm 中编辑应用程序代码,例如 src/App.tsx 。 由于已在配置文件 (
usePolling: true) 中启用轮询,在 WSL 上运行的 Vite 会定期检查项目文件是否有更改,而不是仅依赖文件系统更改事件。 当 Vite 检测到修改时,它会触发 HMR(Hot Module Replacement)或根据需要重新加载页面。
