Node.js必须装在WSL2内部（推荐nvm）、code命令需在Windows端注册并重启WSL2、项目代码须存于WSL2文件系统（如/home/yourname/project）、locale须设为UTF-8，否则将引发路径错误、热重载失效、中文乱码及权限问题。
VSCode 能直接在 WSL2 里跑 Node.js 开发环境，但关键不是“能不能”，而是“在哪装 Node、在哪放代码、怎么调用 code 命令”——这三步错一步，就会出现 command not found、中文乱码、git log 显示八进制编码、热重载失效等问题。
Node.js 必须装在 WSL2 内部，不能复用 Windows 版本
WSL2 是独立 Linux 环境，Windows 上的 node 和 npm 在 WSL2 终端里根本不可见。强行跨文件系统调用（比如从 /mnt/c/Users/xxx/project 运行 Windows 的 Node）会导致：
• 模块路径解析错误（require() 找不到 native addon）
• fs.watch() 失效（尤其在 nodemon 或 webpack watch 场景）
• 权限异常（npm install 报 EACCES）
• 中文路径/文件名被截断或转义
正确做法是：在 WSL2 终端中安装 Node.js，推荐用 nvm：
- 运行
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash - 重启 shell 或执行
source ~/.bashrc - 安装指定版本：
nvm install 20.18.0（LTS 或项目所需版本） - 验证：
which node应返回/home/yourname/.nvm/versions/node/v20.18.0/bin/node
code 命令必须由 Windows VSCode 注册到 WSL2 PATH
很多人在 WSL2 终端里敲 code . 报 command not found，不是没装 VSCode，而是没完成注册。这个命令本质是 Windows 上 VSCode 安装时生成的一个 shell wrapper，需手动触发注册：
- 在 Windows 端打开 VSCode（不是从 WSL 启动）
- 按
Ctrl+Shift+P→ 输入Shell Command: Install 'code' command in PATH→ 回车 - 执行
wsl --shutdown彻底关闭 WSL2（别只关终端） - 重新打开 WSL2 终端，运行
which code，应返回/usr/bin/code - 若仍失败，检查
~/.bashrc是否漏加载：末尾加一行export PATH="$PATH:/mnt/c/Users/$(whoami)/AppData/Local/Programs/Microsoft VS Code/bin"（路径按实际调整）
项目目录必须放在 WSL2 文件系统内，避开 /mnt/c/
把项目放在 /mnt/c/Users/xxx/project 看似方便，实则埋雷：
- I/O 性能下降 3–5 倍（尤其
npm install、tsc --watch） -
chmod/chown不生效，导致npm权限错误 - Git 提交时换行符自动转换（
core.autocrlf失控） - VSCode 的文件监视器（File Watcher）频繁失活
正确路径只有两个选择：
生成Blender Python (bpy)脚本，该脚本使用node_groups API和GeometryNodeTree接口程序化地创建几何节点修改器树，用于参数化3D资产生成。
-
/home/yourname/project（最稳妥，默认挂载点） -
/opt/project（需手动sudo chown -R $USER:$USER /opt/project）
验证方式：在 VSCode 窗口右下角确认显示 WSL: Ubuntu，且打开的文件路径以 /home/... 开头。
Locale 和终端编码必须显式设为 UTF-8
WSL2 默认 locale 是 C，会导致 Node.js 进程读取中文路径失败、console.log('中文') 输出乱码、Git 日志变成 \344\273\245\344\270\212 这类八进制编码。
解决方法：编辑 /etc/wsl.conf（需 sudo），写入：
[boot] command = "sudo /usr/bin/locale-gen en_US.UTF-8 zh_CN.UTF-8" [user] default = yourusername [automount] enabled = true options = "metadata,uid=1000,gid=1000,umask=022,fmask=111"
然后 wsl --shutdown 重启。之后在 WSL2 终端运行 locale，输出中 LANG 和 LC_ALL 必须为 en_US.UTF-8 或 zh_CN.UTF-8。
VSCode 设置里也建议关掉 files.autoGuessEncoding，避免它误判 UTF-8 文件为 GBK。
最容易被忽略的其实是 /etc/wsl.conf 的 [automount] 配置——它决定了 Windows 文件挂载时的 uid/gid 和权限掩码。一旦设错，npm install 生成的 node_modules 就会变成 root 所有，后续所有操作都得加 sudo，彻底破坏开发流。
