Biome 嵌套配置扫描时 panic:path is expected to be under the root
Biome 2.5.15 在嵌套配置下匹配根外文件,可能把绝对路径交给相对路径匹配器。明确 vcs.root 或缩小扫描范围,同时检查忽略规则没有扩大。
Biome 一启动语言服务就反复崩溃,输出 path is expected to be under the root;同目录里的文件能检查,指向相邻目录就 panic。若 biome.json 放在 web/,编辑器却打开整个仓库,先核对 VCS 忽略规则的根目录。
Biome 2.5.15 的具体触发组合包括:开启 vcs.enabled、vcs.useIgnoreFile,使用 Git,未明确 vcs.root,同时在配置目录及仓库根目录存在忽略文件。CLI 检查 ../backend/file.ts,或 LSP 扫描配置目录外的文件时,可能把绝对路径交给要求相对路径的忽略匹配器。
项目配置目录不一定等于仓库根
例如目录关系如下:
repo/
.gitignore
backend/file.ts
web/
.gitignore
biome.json
file.ts
2.5.15 的相关实现先尝试去掉忽略根前缀;失败时保留原路径,再调用 matched_path_or_any_parents。目标在根外时,这个回退仍可能是绝对路径,最终触发断言。它不是普通的 lint 规则诊断,也不能通过修改 backend/file.ts 的代码风格解决。
2.6.2 正式源码中仍保留这段根匹配逻辑,所以不能只看到版本更新就假定这条路径已经修复。
让 VCS 根覆盖实际扫描范围
如果 web/biome.json 本来就负责整个 repo 的相关文件,可以在原配置中明确指向仓库根:
{
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true,
"root": "../"
}
}
只合并需要的配置键,不覆盖已有规则。相对 vcs.root 以这份配置文件所在目录解析;上述 ../ 针对的正是 web 目录,不适合直接复制到更深层配置。
同时核对编辑器的 biome.configurationPath、工作区目录和 CLI 的执行位置。若配置只服务 web 子项目,就把扫描入口限制在这个子项目,不必让它处理整个仓库后再用忽略模式兜底。
调整 VCS 根还会影响忽略规则和变更文件选择,应检查根及嵌套 .gitignore 的预期范围。不能为了让进程不崩溃,顺手关闭所有忽略规则,导致依赖目录、生成文件或不应处理的文件被格式化。
先用不写文件的检查验收
保留配置原版,先通过 lint 等不带写入的入口检查原来触发故障的文件,再观察 LSP 能否结束扫描并稳定提供诊断。还应覆盖配置目录内的正常文件和一份本来应该被忽略的文件,确认修正根目录没有扩大处理范围。
确认进程没有 panic 只是第一步。预期文件应得到检查,忽略文件仍保持忽略;若当前工具明确拒绝跨项目文件,应按项目边界调整调用,而不是要求每一个根外路径都必须被接受。


