调查 Biome 运行缓慢的问题

Biome 的目标是快速运行。速度非常快。然而，有时我们无法兑现承诺。通常，问题是由特定文件或依赖引起的。或者有时你会不小心忘记忽略某个 dist/ 或 build/ 文件夹。无论原因是什么，找出导致速度变慢的原因可能很困难，因此本指南旨在帮助你找到原因。

¥Biome is intended to be fast. Very fast. And yet, sometimes it happens that we fail to live up to that promise. Most often, the cause is a specific file or a dependency that is causing woes. Or sometimes you accidentally forget to ignore a dist/ or a build/ folder. Whichever the cause, it can be rough to find out what is causing this slowness, so this guide is intended to help you figure it out.

入门指南

¥First things first

在深入探讨之前，我们可以执行以下几个步骤，看看问题是否由以下原因之一引起：

¥Before going too deep, we can perform a few steps to see if our issue is caused by one of the following:

• 如果你有包含输出文件的 dist/ 或 build/ 文件夹，或其他包含压缩文件的文件夹，请验证在 files.includes 中使用 !! 语法忽略这些文件夹是否会产生影响。

  ¥If you have a dist/ or build/ folder with output files, or other such folders with minified files, please verify if ignoring those using the !! syntax in files.includes makes a difference.

• 你是否启用了 项目规则？已知它们会造成性能开销，但作为回报，它们可以提供更高级的分析。另请参阅我们关于此主题的 常见问题解答。尝试禁用它们，看看是否有所改善。

  ¥Do you have project rules enabled? They are known to cause performance overhead, in return for more advanced analysis. Also see our FAQ entry on this topic. See if disabling them makes a difference.

  • 如果禁用它们确实有所帮助，但你想找出导致速度变慢的具体原因，第一步是使用 !! 语法将 **/node_modules 添加到 files.includes 中。这有帮助吗？太棒了！但你可能不想保留这种设置，因为依赖的类型信息将不再可用。你可以进一步调整 files.includes，使其忽略特定依赖而不是整个 node_modules/ 文件夹，但你可能需要继续阅读以了解要忽略哪个依赖……

    ¥If disabling them does help, but you want to find out what specifically made it so slow, a first step can be to add **/node_modules to files.includes with the !! syntax. Did that help? Great! But you probably don’t want to keep it like this, because type information from dependencies won’t be available anymore. You can tweak files.includes further to ignore a specific dependency instead of the entire node_modules/ folder, but you will probably want to read on to figure out which dependency to ignore…

如果以上方法均无效，或者有效但你想深入挖掘，我们可以使用跟踪功能来查找是否存在导致问题的特定文件……

¥If none of the above helped, or if they did help, but you want to dig deeper, we can use tracing to see if there is a specific file that might be the culprit…

跟踪

¥Tracing

自 2.0 版本起，Biome 改进了追踪功能，以协助进行此项调查。具体来说，我们将组合以下命令行参数：

¥Since version 2.0, Biome has improved tracing capabilities to help with this investigation. Specifically, we’ll combine the following command-line arguments:

• 每个 Biome CLI 命令都可以传递一个 --log-file=<path> 参数，该参数会将该次调用的所有日志消息写入指定的路径，而不是标准输出。

  ¥Every Biome CLI command can be passed a --log-file=<path> argument, which will write all log messages for that invocation to the given path instead of stdout.

• --log-level=<level> 参数接受 tracing 值。使用 --log-level=tracing 时，Biome 还会将跟踪跨度的计时信息打印到日志中。

  ¥The --log-level=<level> parameter accepts a tracing value. When --log-level=tracing is used, Biome also prints timing information from tracing spans to the log.

• 使用 --log-kind=json，我们可以请求 Biome 以 JSON 格式写入日志。

  ¥Using --log-kind=json we can request Biome to write its logs in JSON format.

如果我们结合这三个参数，我们可以创建一个日志文件，其中包含 Biome 所有相关的计时信息，并以 JSON 消息的形式呈现。例如：

¥If we combine these three arguments, we can create a log file with JSON messages containing all relevant timing information for Biome. For instance:

biome lint --log-level=tracing --log-kind=json --log-file=tracing.json

这段代码会写入一个 tracing.json 文件，但它可能包含大量数据。因此，我们将使用 jq 来筛选此信息。

¥This writes a tracing.json file, but it can contain a lot of data. So we’ll use jq to filter through this information.

例如，如果你想找出构建模块图时哪些路径耗时最长，可以使用以下命令：

¥For example, if you want to figure out which paths take the longest when building the module graph, you can use the following command:

cat tracing.json | jq 'select(.span.name == "update_module_graph_internal") | { path: .span.path, time_busy: .["time.busy"], time_idle: .["time.idle"] }' > filtered.json

现在，你将拥有一个名为 filtered.json 的文件，其中包含所有相关的计时信息以及调用期间使用的路径。

¥Now you will have a file called filtered.json with all the relevant timings, together with the paths used during the invocations.

同样地，如果你想找出分析速度最慢的文件，可以使用以下命令：

¥Similarly, if you want to figure out which files were slowest to analyse, you can use the following command:

cat tracing.json | jq '. | select(.span.name == "pull_diagnostics") | { path: .span.path, time_busy: .["time.busy"], time_idle: .["time.idle"] }' > filtered.json

其他可能值得关注的 span 名称：

¥Other span names that might be interesting to pull info from:

• format_file 会告诉你文件格式化所需的时间。

  ¥format_file tells you how long files take to format.

• open_file_internal 会告诉你文件打开所需的时间，包括解析时间。它有一个 reason 字段，该字段还可以告诉你文件打开的原因：诊断信息可能由扫描器发出，也可能由监视器更新，或者由客户端请求发出（通常用于代码检查或格式化）。（自 Biome 2.1.2 起）

  ¥open_file_internal tells you how long files take to open, including parsing. It has a reason field that also can tell you why a file is opened: either by the scanner, updated by the watcher, or a client request, which is usually for linting or formatting. (since Biome 2.1.2)