调试 - Bun

Bun 支持 WebKit Inspector 协议，因此你可以使用交互式调试器调试代码。为演示目的，考虑以下 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

调试器

多种调试工具可以连接到该服务器。

`debug.bun.sh`

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

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

然后在浏览器中访问 http://localhost:3000。页面永远不会完成加载，因为程序已在断点处暂停。注意 UI 的变化。

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

Sources 窗格的右侧列出了当前范围内的所有局部变量。展开其中一个（如这里的 req）以查看其属性和方法。

Sources 窗格左上角的控件驱动程序的执行。

各按钮的作用：

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

Visual Studio Code 调试器

Visual Studio Code 对调试 Bun 脚本的支持是实验性的。要使用它，请安装 Bun VSCode 扩展。

调试网络请求

设置 BUN_CONFIG_VERBOSE_FETCH 环境变量以记录使用 fetch() 或 node:http 发起的网络请求。

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

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

将 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

堆栈跟踪与 source maps

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

语法高亮的源代码预览

当发生未处理的异常或拒绝时，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 Stack Trace API

Bun 实现了 V8 Stack Trace 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`	typeof `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 的第二个参数是你希望堆栈跟踪开始的函数。在以下示例中，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 调试器

调试网络请求

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

堆栈跟踪与 source maps

语法高亮的源代码预览

V8 堆栈跟踪

V8 Stack Trace API

`Error.prepareStackTrace`

`Error.captureStackTrace(error, startFn)`

​调试 JavaScript 和 TypeScript

​--inspect

​--inspect-brk

​--inspect-wait

​为调试器设置端口或 URL

​调试器

​debug.bun.sh

​Visual Studio Code 调试器

​调试网络请求

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

​堆栈跟踪与 source maps

​语法高亮的源代码预览

​V8 堆栈跟踪

​V8 Stack Trace API

Error.prepareStackTrace

Error.captureStackTrace(error, startFn)

调试 JavaScript 和 TypeScript

`--inspect`

`--inspect-brk`

`--inspect-wait`

为调试器设置端口或 URL

调试器

`debug.bun.sh`

Visual Studio Code 调试器

调试网络请求

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

堆栈跟踪与 source maps

语法高亮的源代码预览

V8 堆栈跟踪

V8 Stack Trace API

`Error.prepareStackTrace`

`Error.captureStackTrace(error, startFn)`