WebStorm 识别 WSL 项目必须通过 /mnt/ 挂载路径，而非原生 Linux 路径；Node.js 解释器需设为 //wsl$/Ubuntu/usr/bin/node；node_modules 必须位于 WSL 原生路径，不可放在 /mnt/ 下；sourcemap 路径需适配 WSL 文件系统语义。
WSL 项目路径必须挂载在 /mnt/ 下才能被 WebStorm 识别
WebStorm 不会主动扫描 WSL 的原生 Linux 路径（比如 /home/username/project），它只认 Windows 视角下的挂载点。WSL2 默认把 Linux 文件系统挂载到 C:Users...AppDataLocalPackages...LocalState
ootfs，但这个路径对 WebStorm 来说不可读、不可索引、无法调试。
正确做法是：把项目放在 Windows 磁盘（如 C:devmyapp），再通过 WSL 访问 /mnt/c/dev/myapp；或者反向——在 WSL 中创建软链指向 /mnt/c/...，但源文件必须物理位于 /mnt/ 对应的 Windows 分区上。
- 不要直接用
\wsl$Ubuntuhomeuserproject打开项目 —— WebStorm 可能加载成功，但语法检查、运行配置、Git 集成大概率失效 - 如果已在 WSL 内建了项目（如
/home/user/app），先用cp -r /home/user/app /mnt/c/tmp/app搬到挂载路径，再从 Windows 侧打开C: mppp - WSL1 和 WSL2 在 I/O 性能和路径语义上有差异，WebStorm 更适应 WSL2 +
/mnt/路径组合；WSL1 下某些符号链接行为异常，可能触发Cannot resolve file报错
运行配置里选「WSL’ 时，Node.js interpreter 必须设为 WSL 路径
即使你开了 WSL 终端，WebStorm 默认仍用 Windows 上的 Node.js。点「Edit Configurations」→ 「Node.js」→ 「Interpreter path」，不能填 C:Program Files
odejs
ode.exe，得填类似 //wsl$/Ubuntu/usr/bin/node 这样的 UNC 路径，或点击右侧小图标从 WSL 中自动探测。
- 手动输入时，注意斜杠方向：
//wsl$/Ubuntu/usr/bin/node是合法的，wsl$...或C:WindowsSystem32...都无效 - 如果 WSL 中用
nvm管理 Node 版本，确保nvm初始化已写入~/.bashrc或~/.zshrc，否则 WebStorm 启动时找不到node - 改完解释器后，务必点「Reload project from disk」，否则旧缓存可能导致 ESLint 或 TypeScript Server 仍走 Windows 解释器
npm install 在 WSL 里执行，但 node_modules 不能放在 /mnt/ 下
WSL 访问 /mnt/c/ 是通过 drvfs 驱动，性能差且不支持某些 Unix 文件权限和符号链接。若把 node_modules 放在 /mnt/c/... 目录下，会出现 ENOTDIR、EPERM、yarn 安装卡死、Webpack watch 失效等问题。
- 解决方案：在 WSL 内建一个本地路径作为工作区，例如
/home/user/ws/myapp，然后用ln -s /mnt/c/dev/myapp .软链源码；node_modules自然落在/home/user/ws/myapp/node_modules（即 WSL 原生文件系统） - WebStorm 的「Excluded」目录设置要同步更新：把真正的
node_modules路径（/home/user/ws/myapp/node_modules）加进排除，而不是 Windows 下那个空壳 - VS Code 用户常误以为「Remote-WSL 插件」能解决一切，但 WebStorm 没有同等级远程文件系统抽象，它依赖路径真实归属，这点必须想清楚
调试时断点不命中？检查 sourceRoot 和 webpack.config.js 的 devtool
WSL 下调试前端项目（尤其 Vue/React）容易断点灰掉，根本原因是 sourcemap 路径写死了 Windows 格式（如 C:/dev/app/src/main.js），而 Chrome DevTools 在 WSL 环境里实际加载的是 file:///mnt/c/dev/app/src/main.js，路径对不上就找不到源码。
- Webpack 里显式配置
devtool: 'source-map'并加上output.devtoolModuleFilenameTemplate，例如：info.absolutePath.replace(/\/g, '/').replace(/^(/mnt/[a-z])//, 'file://$1/') - Vite 用户需在
vite.config.ts中设置resolve.alias和build.rollupOptions.output.sourcemapPathTransform，否则 HMR 更新后 sourcemap 会错乱 - WebStorm 的「JavaScript Debug」配置里，勾选
Enable source maps是基础，但更重要的是确认「Web server root URL」填的是http://localhost:3000，不是file://协议路径
WSL 路径映射是隐式的，不是透明的。很多问题表面是 WebStorm 配置不对，实际是开发工具链（npm/yarn/webpack/vite）没适配 WSL 的文件系统语义。别急着调 IDE 设置，先确认 node -v、which node、ls -la node_modules 这三步在 WSL 终端里是否干净利落。
