调试 - Bun 中文文档

Bun 使用 WebKit Inspector Protocol，因此你可以使用交互式调试器来调试你的代码。为了演示效果，请考虑下面的示例 Web 服务器。

调试 JavaScript 和 TypeScript

server.ts

Bun.serve({
  fetch(req) {
    console.log(req.url);
    return new Response("Hello, world!");
  },
});

`--inspect`

要在使用 Bun 运行代码时启用调试，请使用 --inspect 标志。此标志会在可用端口上启动一个 WebSocket 服务器，用于检查正在运行的 Bun 进程。

terminal

bun --inspect server.ts

--------------------- Bun Inspector ---------------------
Listening:
  ws://localhost:6499/0tqxs9exrgrm
Inspect in browser:
  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
--------------------- Bun Inspector ---------------------

`--inspect-brk`

--inspect-brk 标志的行为与 --inspect 完全相同，不同之处在于，它会在执行脚本的第一行注入一个断点。对于运行速度很快并会立即退出的脚本，可以使用此标志进行调试。

`--inspect-wait`

--inspect-wait 标志的行为与 --inspect 完全相同，不同之处在于，直到调试器连接到正在运行的进程后，代码才会执行。

为调试器设置端口或 URL

无论使用哪个标志，都可以指定端口号、URL 前缀，或同时指定两者。

terminal

bun --inspect=4000 server.ts
bun --inspect=localhost:4000 server.ts
bun --inspect=localhost:4000/prefix server.ts

调试器

Several debugging tools can connect to this server.

`debug.bun.sh`

Bun 在 debug.bun.sh 上提供了一个基于 Web 的调试器。它是 WebKit 的 Web Inspector Interface 的修改版本，Safari 用户会对它感到熟悉。在浏览器中打开提供的 debug.bun.sh URL，即可开始调试会话。在此界面中，你可以查看正在运行的文件的源代码、查看和设置断点，并使用内置控制台执行代码。

打开 Sources 标签页；你应该能看到之前的代码。点击行号 3，在 console.log(req.url) 语句上设置断点。

然后在 Web 浏览器中访问 http://localhost:3000。页面会一直加载，因为程序已在断点处暂停。注意界面发生的变化。

暂停期间，使用底部的控制台在程序上下文中运行任意代码，并可以完全访问断点处作用域内的变量。

Sources 面板的右侧会列出当前作用域内的所有局部变量。展开其中一个变量，例如这里的 req，即可查看其属性和方法。

Sources 面板左上方的控件用于控制程序的执行。

每个按钮的功能如下：

继续执行脚本 — 运行至下一个断点或异常处。
单步跳过 — 执行至下一行。
单步进入 — 如果当前语句包含函数调用，则进入被调用的函数。
单步跳出 — 如果当前语句是函数调用，则执行完该调用，然后返回调用它的位置。

Visual Studio Code 调试器

Visual Studio Code 对 Bun 脚本的调试支持仍处于实验阶段。要使用此功能，请安装 Bun VSCode 扩展。

调试网络请求

设置 BUN_CONFIG_VERBOSE_FETCH 环境变量，以记录通过 fetch() 或 node:http 发出的网络请求。

值	描述
`curl`	将请求打印为 `curl` 命令
`true`	打印请求和响应信息
`false`	不打印任何内容（默认）

以 curl 命令打印 fetch 和 node:http 请求

将 BUN_CONFIG_VERBOSE_FETCH 设置为 curl，即可将每个 fetch() 和 node:http 请求打印为单行 curl 命令。你可以将其复制并粘贴到终端中，以复现该请求。

index.ts

process.env.BUN_CONFIG_VERBOSE_FETCH = "curl";

await fetch("https://example.com", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ foo: "bar" }),
});

[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.3.3" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
[fetch] > HTTP/1.1 POST https://example.com/
[fetch] > content-type: application/json
[fetch] > Connection: keep-alive
[fetch] > User-Agent: Bun/1.3.3
[fetch] > Accept: */*
[fetch] > Host: example.com
[fetch] > Accept-Encoding: gzip, deflate, br
[fetch] > Content-Length: 13

[fetch] < 200 OK
[fetch] < Accept-Ranges: bytes
[fetch] < Cache-Control: max-age=604800
[fetch] < Content-Type: text/html; charset=UTF-8
[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
[fetch] < Etag: "3147526947"
[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
[fetch] < Server: EOS (vny/044F)
[fetch] < Content-Length: 1256

以 [fetch] > 标记的行是本地代码发出的请求，以 [fetch] < 标记的行是远程服务器的响应。若要在不打印 curl 命令的情况下输出日志，请将 BUN_CONFIG_VERBOSE_FETCH 设置为 true。

index.ts

process.env.BUN_CONFIG_VERBOSE_FETCH = "true";

await fetch("https://example.com", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ foo: "bar" }),
});

[fetch] > HTTP/1.1 POST https://example.com/
[fetch] > content-type: application/json
[fetch] > Connection: keep-alive
[fetch] > User-Agent: Bun/1.3.3
[fetch] > Accept: */*
[fetch] > Host: example.com
[fetch] > Accept-Encoding: gzip, deflate, br
[fetch] > Content-Length: 13

[fetch] < 200 OK
[fetch] < Accept-Ranges: bytes
[fetch] < Cache-Control: max-age=604800
[fetch] < Content-Type: text/html; charset=UTF-8
[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
[fetch] < Etag: "3147526947"
[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
[fetch] < Server: EOS (vny/044F)
[fetch] < Content-Length: 1256

堆栈跟踪和 sourcemaps

Bun 会转译每个文件，这可能导致堆栈跟踪指向转译后的输出。为避免这种情况，Bun 会为它转译的每个文件生成并提供带 sourcemap 的文件。当你在控制台中看到堆栈跟踪时，可以点击文件路径并跳转到原始源代码，即使该代码是用 TypeScript 或 JSX 编写的，或者经过了其他转换。 Bun 会在运行时按需转译文件时加载 sourcemap，也会在使用 bun build 预先编译文件时加载 sourcemap。

带语法高亮的源代码预览

Bun 会在发生未处理的异常或拒绝时打印一小段源代码预览。要自行生成相同的输出，请调用 Bun.inspect(error)：

// 创建一个错误
const err = new Error("Something went wrong");
console.log(Bun.inspect(err, { colors: true }));

输出内容包括发生错误位置的带语法高亮的源代码预览，以及错误消息和堆栈跟踪。

1 | // 创建一个错误
2 | const err = new Error("Something went wrong");
                ^
error: Something went wrong
      at file.js:2:13

V8 堆栈跟踪

Bun 使用 JavaScriptCore 作为其引擎，但 Node.js 生态系统中的许多工具以及 npm 都期望使用 V8，而不同的 JavaScript 引擎对 error.stack 的格式化方式各不相同。由于 Bun 旨在成为 Node.js 的直接替代品，因此它会按照 V8 的方式格式化 error.stack。当你使用期望 V8 堆栈跟踪的库时，这一点尤为重要。

V8 堆栈跟踪 API

Bun 实现了 V8 堆栈跟踪 API，这是一组用于操作堆栈跟踪的函数。

`Error.prepareStackTrace`

定义一个全局的 Error.prepareStackTrace 函数，以自定义堆栈跟踪输出。它接收错误对象和一个 CallSite 对象数组，其返回值会成为 error.stack。

Error.prepareStackTrace = (err, stack) => {
  return stack.map(callSite => {
    return callSite.getFileName();
  });
};

const err = new Error("Something went wrong");
console.log(err.stack);
// [ "error.js" ]

CallSite 对象的可用方法如下：

方法	返回值
`getThis`	函数调用中的 `this` 值
`getTypeName`	`this` 的类型名
`getFunction`	函数对象
`getFunctionName`	函数名称，字符串
`getMethodName`	方法名称，字符串
`getFileName`	文件名或 URL
`getLineNumber`	行号
`getColumnNumber`	列号
`getEvalOrigin`	`undefined`
`getScriptNameOrSourceURL`	源码 URL
`isToplevel`	如果函数在全局作用域中，返回 `true`
`isEval`	如果函数是 `eval` 调用，返回 `true`
`isNative`	如果函数是原生的，返回 `true`
`isConstructor`	如果函数是构造函数，返回 `true`
`isAsync`	如果函数是 `async`，返回 `true`
`isPromiseAll`	尚未实现
`getPromiseIndex`	尚未实现
`toString`	返回调用位置的字符串描述

如果 Function 对象已经被垃圾回收，其中一些方法会返回 undefined。

`Error.captureStackTrace(error, startFn)`

Error.captureStackTrace 会在代码中的特定位置捕获堆栈跟踪，而不是在抛出错误的位置捕获。当回调或异步代码使错误来源难以确定时，这会很有帮助。Error.captureStackTrace 的第 2 个参数是你希望堆栈跟踪从其开始的函数。在以下示例中，err.stack 指向调用 fn() 的代码，尽管错误是在 myInner 中抛出的。

index.ts

const fn = () => {
  function myInner() {
    throw err;
  }

  try {
    myInner();
  } catch (err) {
    console.log(err.stack);
    console.log("");
    console.log("-- captureStackTrace --");
    console.log("");
    Error.captureStackTrace(err, fn);
    console.log(err.stack);
  }
};

fn();

Error: here!
    at myInner (file.js:4:15)
    at fn (file.js:8:5)
    at module code (file.js:17:1)
    at moduleEvaluation (native)
    at moduleEvaluation (native)
    at <anonymous> (native)

-- captureStackTrace --

Error: here!
    at module code (file.js:17:1)
    at moduleEvaluation (native)
    at moduleEvaluation (native)
    at <anonymous> (native)

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

调试

调试 JavaScript 和 TypeScript

`--inspect`

`--inspect-brk`

`--inspect-wait`

为调试器设置端口或 URL

调试器

`debug.bun.sh`

Visual Studio Code 调试器

调试网络请求

以 curl 命令打印 fetch 和 node:http 请求

堆栈跟踪和 sourcemaps

带语法高亮的源代码预览

V8 堆栈跟踪

V8 堆栈跟踪 API

`Error.prepareStackTrace`

`Error.captureStackTrace(error, startFn)`

​调试 JavaScript 和 TypeScript

​--inspect

​--inspect-brk

​--inspect-wait

​为调试器设置端口或 URL

​调试器

​debug.bun.sh

​Visual Studio Code 调试器

​调试网络请求

​以 curl 命令打印 fetch 和 node:http 请求

​堆栈跟踪和 sourcemaps

​带语法高亮的源代码预览

​V8 堆栈跟踪

​V8 堆栈跟踪 API

Error.prepareStackTrace

Error.captureStackTrace(error, startFn)

调试 JavaScript 和 TypeScript

`--inspect`

`--inspect-brk`

`--inspect-wait`

为调试器设置端口或 URL

调试器

`debug.bun.sh`

Visual Studio Code 调试器

调试网络请求

以 curl 命令打印 fetch 和 node:http 请求

堆栈跟踪和 sourcemaps

带语法高亮的源代码预览

V8 堆栈跟踪

V8 堆栈跟踪 API

`Error.prepareStackTrace`

`Error.captureStackTrace(error, startFn)`