Biome 配置踩坑实录：当用户名遇上特殊字符

又是一个差点放弃，最后完成的事情。虽然一般情况下用不着，但是还是记录一下，以防万一。

问题背景

在 Windows 系统中配置 Biome 作为代码格式化工具时，遇到了一个看似简单却极其棘手的问题：

Error: spawn C:\Users\<用户名>\AppData\Roaming\Cursor\...\biome.exe ENOENT

根本原因：Windows 用户名包含特殊字符（中文、日文符号、括号等），导致 Node.js 的 spawn 系统调用无法正确解析路径。

---

曲折的解决历程

方案一：使用项目本地 node_modules（失败）

"biome.lsp.bin": "./node_modules/@biomejs/biome/bin/biome"

结果：扩展依然尝试将文件复制到用户目录缓存，路径问题依旧。

---

方案二：npm 全局安装到自定义路径（失败）

npm install -g @biomejs/biome --prefix C:/tools/biome

"biome.lsp.bin": "C:\\tools\\biome\\node_modules\\@biomejs\\biome\\bin\\biome"

结果：npm 安装的 biome 会在 node_modules/@biomejs/.biome-xxx 目录下解压平台特定的二进制文件，扩展内部逻辑仍可能触发路径问题。即使删除用户目录缓存，扩展也会重新创建。

---

方案三：手动下载独立可执行文件（成功）

直接从 Biome GitHub Releases 页面下载 Windows 版本的 biome-win32-x64.exe，重命名为 biome.exe，放到完全没有特殊字符的路径：

C:\tools\biome.exe

配置：

{
  "biome.lsp.bin": "C:\\tools\\biome.exe",
  "biome.runFromTemporaryLocation": false
}

关键配置：runFromTemporaryLocation: false 禁止扩展将文件复制到临时/缓存目录。

---

核心教训

问题	原因	解决方案
ENOENT 错误	用户名含特殊字符	避开用户目录
npm 安装无效	扩展内部有额外的路径处理逻辑	使用独立可执行文件
配置不生效	runFromTemporaryLocation 默认为 true	显式设置为 false

---

最终配置

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "biome.lsp.enabled": true,
  "biome.runFromTemporaryLocation": false,
  "biome.lsp.bin": "C:\\tools\\biome.exe"
}

---

总结

这个问题的本质不在 Biome，而在于整个 Node.js/npm 生态对 Windows 特殊字符路径的支持不完善。当你的用户名包含中文、日文、特殊符号时，最稳妥的方案是：

1. 绕开用户目录 - 把关键工具放到纯 ASCII 路径
2. 使用独立二进制 - 而非依赖 npm 的安装结构
3. 禁用临时目录 - 防止工具自作聪明地复制文件

这是一个工具链与国际化用户名之间的经典冲突，希望这篇记录能帮助后来者少走弯路。