WebView

Bun.WebView 是内置在运行时中的无头浏览器。使用它来加载页面、在其中运行 JavaScript、模拟真实用户输入，并截取屏幕截图 — 不需要 Puppeteer、Playwright，也不需要单独下载浏览器。

await using view = new Bun.WebView();

await view.navigate("https://example.com");
await view.click("a[href]"); // 等待链接变为可点击
const title = await view.evaluate("document.title");

await Bun.write("page.png", await view.screenshot());

在 macOS 上，Bun.WebView 使用系统的 WKWebView — 无需安装任何东西。在 Linux 和 Windows 上，它会通过 Chrome DevTools Protocol 驱动已安装的 Chrome、Chromium、Edge 或 Brave；在 Windows 上，预装的 Edge 就足够了。

每个视图都会在单独的渲染器进程中运行其页面。所有输入方法（click、type、press、scroll）都会分发原生浏览器事件，因此页面会看到 isTrusted: true — 与真实用户一致。

创建视图

const view = new Bun.WebView({
  width: 1280, // 视口宽度（CSS 像素，1-16384，默认 800）
  height: 720, // 视口高度（CSS 像素，1-16384，默认 600）
  url: "https://bun.sh", // 可选：立即开始导航
});

构造函数是同步的——它会立即返回，并在后台启动浏览器子进程。你 await 的第一个操作（例如 navigate() 或 evaluate()）会等待浏览器准备就绪。

如果传入 url，视图会在构造函数返回前开始导航，效果与在下一行调用 view.navigate(url) 相同。不同之处在于：构造函数会将导航的 promise 保留在内部，因此失败时不会产生拒绝。设置 onNavigationFailed 以便观察导航失败。

使用 using 的自动清理

Bun.WebView 实现了 Symbol.dispose 和 Symbol.asyncDispose，因此你可以使用 using 或 await using，当视图超出作用域时自动关闭：

{
  await using view = new Bun.WebView();
  await view.navigate("https://example.com");
  // ...
} // 这里会自动调用 view.close()

持久化存储

默认情况下，每个视图使用短暂的内存存储 — cookies、localStorage、IndexedDB 和缓存都会在视图关闭时丢弃。要在多次运行之间持久化状态，请传入目录：

const view = new Bun.WebView({
  dataStore: { directory: "./browser-profile" },
});

共享同一个 directory 的视图会共享 cookies 和存储。传入 dataStore: "ephemeral"（默认值）以显式回到内存存储。

后端

Bun.WebView 支持两种渲染引擎。默认取决于你的平台：

在 macOS 上，默认后端是 "webkit"；其他平台默认使用 "chrome"。在非 macOS 平台请求 backend: "webkit" 会抛出异常。"chrome" 后端每个进程驱动一个浏览器，且只能从主线程使用；在 Worker 中构造它会抛出异常。

// 在 macOS 上强制使用 Chrome
const view = new Bun.WebView({ backend: "chrome" });

WebKit 后端如何工作

Bun 会生成一个轻量级宿主子进程（即 bun 二进制文件本身，以特殊模式重新运行），由它在主线程上管理 WKWebView。你的 Bun 进程通过 Unix socket 使用紧凑的二进制协议与其通信。Bun 只生成一次宿主进程，你的程序中的每个 "webkit" 视图都会共用它。

Chrome 后端如何工作

Bun 要么连接到一个已经运行的 Chrome（通过 WebSocket），要么生成一个无头 Chrome 子进程，并通过管道与它通信（--remote-debugging-pipe）。无论哪种方式，通信都使用 Chrome DevTools Protocol。

Bun 每个进程只生成（或连接）一次 Chrome。每个 new Bun.WebView({ backend: "chrome" }) 都会在该 Chrome 实例中使用 Target.createTarget 创建一个新标签页。

查找 Chrome 可执行文件

当 Bun 需要生成 Chrome 时，它会按以下顺序搜索：

1. 你在 backend: { type: "chrome", path: "..." } 中传入的 path
2. BUN_CHROME_PATH 环境变量
3. $PATH（google-chrome-stable、google-chrome、chromium-browser、chromium、brave-browser、microsoft-edge、chrome；在 Windows 上为 chrome、chromium、brave、msedge）
4. 标准安装位置（/Applications/Google Chrome.app、~/Applications/...、/usr/bin/...、/snap/bin/...；在 Windows 上为 %ProgramFiles%、%ProgramFiles(x86)% 和 %LOCALAPPDATA% 下的 Application\*.exe 目录）
5. Playwright 的缓存（~/Library/Caches/ms-playwright、~/.cache/ms-playwright 或 %LOCALAPPDATA%\ms-playwright）中的 chrome-headless-shell

如果 Bun 找不到 Chrome，构造函数会抛出异常。

连接到已在运行的 Chrome

默认情况下，在生成浏览器之前，Bun 会从标准配置文件目录读取 DevToolsActivePort 文件，以检查是否已经有启用了远程调试的 Chrome 系浏览器在运行。如果找到，Bun 会通过 WebSocket 连接到该浏览器，而不是生成新浏览器 — 你的视图会作为标签页在现有浏览器中打开。

要在运行中的 Chrome 中启用远程调试，请访问 chrome://inspect/#remote-debugging 并打开开关，或者使用 --remote-debugging-port=9222 启动 Chrome。使用 chrome://inspect 开关时，Chrome 会在每次建立新连接时请求权限。

要显式控制这一行为，请使用 backend 的对象形式：

// 总是生成一个新的无头 Chrome；永远不自动连接
new Bun.WebView({
  backend: { type: "chrome", url: false },
});

// 连接到特定的 DevTools WebSocket URL
new Bun.WebView({
  backend: {
    type: "chrome",
    url: "ws://127.0.0.1:9222/devtools/browser/abc123...",
  },
});

如果自动探测发现过期的 DevToolsActivePort 文件（Chrome 崩溃或重启），WebSocket 连接将失败，并且 Bun 会透明地回退到生成自己的 Chrome。显式指定 url: "ws://..." 不会回退 — 连接失败会直接抛出异常。

启动参数

生成时，Bun 会传入一组最小的参数：

--user-data-dir=<temp> --remote-debugging-pipe --headless --no-first-run
--no-default-browser-check --disable-gpu --disable-extensions
--disable-background-networking --disable-background-timer-throttling
--disable-backgrounding-occluded-windows --disable-renderer-backgrounding
--disable-ipc-flooding-protection --no-startup-window

用 argv 把你自己的参数追加进去 — Chrome 处理重复开关时采用“最后生效”，因此你可以覆盖任意默认值：

new Bun.WebView({
  backend: {
    type: "chrome",
    argv: ["--headless=new", "--lang=ja-JP", "--window-size=1920,1080"],
  },
});

子进程输出

浏览器子进程的 stdout/stderr 默认会被静默处理。尤其是 Chrome，其 stderr 输出十分嘈杂（字体配置警告、GCM 注册、更新程序检查）。要查看这些输出 — 在 Chrome 静默崩溃时很有用 — 请传入 "inherit"：

new Bun.WebView({
  backend: { type: "chrome", stderr: "inherit", stdout: "inherit" },
});

"webkit" 后端也接受相同的 stdout/stderr 选项。

导航

await view.navigate("https://example.com");
await view.navigate("data:text/html,<h1>hello</h1>");
await view.navigate("file:///path/to/index.html");

当主框架的 load 事件触发时，navigate() 才会解析完成。解析完成后，view.url 和 view.title 会反映新页面，且 view.loading 为 false。

如果导航失败（DNS 失败、连接被拒绝、URL 无效），该 promise 会以描述失败原因的 Error 形式拒绝。

每个视图在任一时刻只能进行一个正在进行的导航。若在另一个 navigate() 仍待处理时再次调用 navigate()，会同步抛出 ERR_INVALID_STATE。

历史记录

await view.goBack(); // 类似浏览器的返回按钮
await view.goForward(); // 类似浏览器的前进按钮
await view.reload(); // 重新加载当前页面

在历史记录的起点（或终点）调用 goBack()（或 goForward()）会直接解析为 undefined，不进行导航 — 不会拒绝。

导航回调

设置 onNavigated 和 onNavigationFailed 来观察每一次导航，包括页面自身触发的导航（点击链接、location.href = ...、重定向）以及由 reload()/goBack()/goForward() 触发的导航：

view.onNavigated = (url, title) => {
  console.log("Loaded", url);
};

view.onNavigationFailed = error => {
  console.error("Navigation failed:", error.message);
};

这些回调会在对应的 navigate() promise 完成（settle）之前触发，因此当你 await view.navigate(...) 返回时，你的回调已经运行过了。设置为 null 可移除。

计算 JavaScript

在页面的主框架中运行一个表达式，并把结果作为原生 JavaScript 值返回：

const title = await view.evaluate("document.title");
const items = await view.evaluate("[...document.querySelectorAll('li')].map(li => li.textContent)");
const user = await view.evaluate("({ name: 'bun', ok: true })");

Bun 会将脚本包装为 await (<your script>)，因此：

• 它必须是一个表达式，而不是语句序列。若要运行多个语句，请将它们包装在 IIFE 中：evaluate("(() => { let x = foo(); return x + 1 })()")。
• 如果计算结果是一个 Promise，evaluate() 会等待该 promise，并返回其解析后的值。

结果会在页面侧通过 JSON.stringify，在 Bun 侧通过 JSON.parse 来往返传递。数组和普通对象会以真实结构返回；undefined、函数和 symbol 会解析为 undefined；循环引用会导致拒绝。

await view.evaluate("42"); // 42
await view.evaluate("[1, 2, 3]"); // [1, 2, 3]
await view.evaluate("undefined"); // undefined
await view.evaluate("() => 1"); // undefined（函数不会序列化）
await view.evaluate("fetch('/api').then(r => r.json())"); // 已等待

如果脚本抛出异常（或返回被拒绝的 promise），evaluate() 会拒绝，并把消息作为页面侧异常信息的一部分返回一个 Error。

每个视图在任一时刻只能进行一个正在进行的 evaluate()；第二个并发调用会同步抛出 ERR_INVALID_STATE。

截图

把当前视口捕获成图片：

const png = await view.screenshot();
await Bun.write("page.png", png);

图片格式

await view.screenshot({ format: "png" }); // 无损（默认）
await view.screenshot({ format: "jpeg", quality: 90 }); // 有损，quality 0-100（默认 80）
await view.screenshot({ format: "webp", quality: 75 }); // 仅 Chrome 后端

PNG 会忽略 quality。"webp" 只在 backend: "chrome" 时可用 — WebKit 后端会抛出异常。

返回类型

encoding 选项控制 Bun 如何返回图片字节：

const buf = await view.screenshot({ encoding: "buffer" });
console.log(buf[0] === 0x89); // PNG 魔术字节

const b64 = await view.screenshot({ encoding: "base64" });
console.log(`<img src="data:image/png;base64,${b64}">`);

终端图形的共享内存

encoding: "shmem" 专为 Kitty 的终端图形协议 t=s 传输模式设计。Bun 会将图片写入 POSIX 共享内存段并返回其名称。终端会直接读取它，并在完成后取消链接。无需通过管道复制。

const { name, size } = await view.screenshot({ encoding: "shmem" });
process.stdout.write(`\x1b_Gf=100,t=s,a=T,S=${size};${btoa(name)}\x1b\\`);
// Kitty 从共享内存读取 PNG 并取消链接该段

在 WebKit 上，shm 名称看起来像 /bun-webview-<pid>-<seq>；在 Chrome 上是 /bun-chrome-<pid>-<seq>。如果你请求 "shmem"，但没有把名称交给某个会执行 shm_unlink 的逻辑，那么共享内存段会在你的进程退出前一直泄漏。

输入模拟

所有输入方法都会分发原生浏览器事件。页面会收到 isTrusted: true 的 pointerdown/mousedown/keydown/wheel 事件。CSS :active 和 :hover 状态会生效。默认操作（表单提交、链接导航、文本选择）会与用户实际操作时完全一样地触发。

点击

在视口坐标处点击：

await view.click(150, 200);
await view.click(150, 200, { button: "right" });
await view.click(150, 200, { clickCount: 2 }); // 双击
await view.click(150, 200, { modifiers: ["Shift", "Meta"] });

promise 会在页面处理完完整的 mousedown → mouseup → click 序列（包括任何 JavaScript 处理程序）后解析。无需轮询 — 后续的 evaluate() 可以看到结果。

通过选择器点击

传入 CSS 选择器而不是坐标，Bun 会等待元素变为可操作，然后点击其中心：

await view.click("#submit");
await view.click("button.primary", { timeout: 5000 });

当元素满足以下条件时，它才是可操作的：

• 存在于 DOM 中
• 拥有非零的边界框
• 位于视口内
• 已保持稳定（在连续两帧动画中边界框未改变）
• 在其中心点处是最上层元素（没有被覆盖物遮挡）

该检查会在页面侧以 requestAnimationFrame 的频率运行。如果该元素在 timeout 毫秒内始终未变为可操作（默认 30000），promise 会以类似 timeout waiting for '#submit' to be actionable 的错误拒绝。

Bun 会将选择器作为数据传递，而不是将其插入脚本中，因此包含引号或 JavaScript 语法的选择器也是安全的。

输入文本

把文本插入到当前聚焦的元素中：

await view.click("input#email"); // 先聚焦
await view.type("hello@example.com");

type() 使用浏览器的 InsertText 编辑命令（与粘贴使用同一路径），而不是逐字符的按键模拟。它会触发带 isTrusted: true 的 beforeinput/input 事件，但不会触发 keydown/keyup 事件。不会进行 IME 处理，也不会进行智能引号替换 — 文本会被按原样精确写入。

按下按键

await view.press("Enter");
await view.press("Escape");
await view.press("ArrowDown");
await view.press("a", { modifiers: ["Meta"] }); // Cmd+A / Ctrl+A

命名的虚拟按键：Enter、Tab、Space、Backspace、Delete、Escape、ArrowLeft、ArrowRight、ArrowUp、ArrowDown、Home、End、PageUp、PageDown。

任意单个字符（例如 "a"）与 modifiers 组合使用时，会发送键盘组合键。

在 WebKit 后端上，大多数命名按键（不带修饰键）会映射到 DeleteBackward、MoveLeft 和 InsertNewline 等编辑命令，并在页面应用这些命令后解析。Escape、Space 和带有修饰键的任何按键都会回退到原始的 keydown/keyup 事件。这些按键会触发页面可观察到的 keydown，但没有完成屏障。如果需要观察结果，请接着调用 evaluate()。

修饰键名称："Shift"、"Control"（或 "Ctrl"）、"Alt"（或 "Option"）、"Meta"（或 "Cmd" / "Command"）。

滚动

按像素增量滚动 — 在视口中心触发一个原生 wheel 事件：

await view.scroll(0, 500); // 向下滚动 500px
await view.scroll(-100, 0); // 向左滚动 100px

正的 dy 会向下滚动（内容向上移动），与 window.scrollBy 一致。如果视口中心下方有可滚动元素，它会接收到 wheel 事件，而不是整个文档。

通过选择器把元素滚入视野：

await view.scrollTo("#footer"); // 居中显示（默认）
await view.scrollTo("#hero", { block: "start" }); // 让元素顶部对齐视口顶部
await view.scrollTo(".card", { block: "nearest" }); // 最小滚动

scrollTo() 会以 requestAnimationFrame 的频率等待元素存在，然后调用 element.scrollIntoView({ block, behavior: "instant" })。它会滚动所有可滚动祖先，而不仅仅是文档。默认 timeout 为 30000 ms。

调整大小

await view.resize(1920, 1080);

宽度和高度分别必须在 1 到 16384 之间。

控制台捕获

通过在构造函数中传入 console 选项，把页面侧的 console.* 调用转发到你的 Bun 进程。

镜像到 Bun 的控制台

传入 globalThis.console（实际对象，按引用传递）。页面侧的 console.log("hi") 会使用 Bun 的格式化程序将 hi 打印到 stdout，console.error 则会输出到 stderr。此路径通过 Bun 的控制台实现直接分发，不会产生每次调用都要承担的 JavaScript 开销。

const view = new Bun.WebView({
  console: globalThis.console,
});

自定义处理器

传入一个函数来接收每次调用：

const view = new Bun.WebView({
  console: (type, ...args) => {
    // type 是 "log" | "warn" | "error" | "info" | "debug" | ...
    if (type === "error") reportError(args);
  },
});

原始参数（字符串、数字、布尔值、null、undefined）会解包为它们的原始值。对象参数会以序列化描述符的形式到达：

• Chrome 后端：原始的 CDP RemoteObject — 一个包含 type、className、description，以及（在可用时）preview.properties 数组的对象。
• WebKit 后端：对象经过 JSON.stringify 往返后的结果。函数、循环引用以及其他不可序列化值会回退为 String(...) 的强制转换。

如果你没有传入 console，Bun 会丢弃页面侧的控制台输出。

原始 Chrome DevTools Protocol

当使用 backend: "chrome" 时，如果高层 API 没有覆盖你想要的能力，你可以直接切换到原始的 CDP 命令。

发送命令

const view = new Bun.WebView({ backend: "chrome" });
await view.navigate("https://example.com"); // 必需：设置 CDP 会话

await view.cdp("Emulation.setUserAgentOverride", {
  userAgent: "MyBot/1.0",
});

const { root } = await view.cdp("DOM.getDocument");
const { nodeId } = await view.cdp("DOM.querySelector", {
  nodeId: root.nodeId,
  selector: "input[name=q]",
});
await view.cdp("DOM.focus", { nodeId });

cdp(method, params?) 会返回 CDP 响应中的 result 对象。如果 Chrome 返回错误（未知方法、参数错误），该 promise 会以 error.message 拒绝。

命令会被限定在此视图的会话范围内（目标是此标签页）。在调用 cdp() 之前至少要 await navigate(...) 一次 — 第一次导航会建立会话。若在那之前调用 cdp() 会抛出 ERR_INVALID_STATE。

params 必须是可 JSON 序列化的对象；对于不带参数的命令可省略。每个视图同一时刻最多只能有一个 cdp() 调用正在进行。

订阅事件

Bun.WebView 扩展了 EventTarget。使用 Chrome 后端时，视图会将 CDP 事件作为 DOM 事件分发，其 type 为 CDP 方法名称，data 为解析后的 params 对象：

await view.navigate("about:blank");
await view.cdp("Network.enable"); // 仅 Chrome：只有启用了域才会发出事件

view.addEventListener("Network.responseReceived", event => {
  console.log(event.data.response.status, event.data.response.url);
});

await view.navigate("https://example.com");

对于没有注册监听器的事件，Bun 会在解析其 JSON params 之前就将其丢弃，因此如果你只监听一两种事件类型，启用像 Network 这样的高频事件域也不会造成开销。

在 WebKit 后端上，cdp() 会抛出 ERR_METHOD_NOT_IMPLEMENTED — 没有 DevTools Protocol 的桥接。EventTarget 接口仍然可用于你自己对 dispatchEvent() 的调用。

生命周期

关闭视图

view.close();

关闭操作是同步且幂等的。它会销毁页面的渲染器进程，以 Error("WebView closed") 拒绝该视图上所有待处理的 promise，并使之后的每次方法调用都抛出 ERR_INVALID_STATE。这些拒绝会被标记为已处理：你持有的 promise 仍可以捕获到拒绝，但没有被任何对象持有的待处理操作不会触发 unhandledRejection。

view[Symbol.dispose] 和 view[Symbol.asyncDispose] 都指向 close()，所以 using / await using 可以正常工作。

杀死所有浏览器

Bun.WebView.closeAll();

强制终止（SIGKILL）所有浏览器子进程（包括 Chrome 子进程和 WebKit 宿主子进程）。每个视图上的待处理 promise 会在下一次事件循环 tick 时拒绝。之后的 new Bun.WebView() 调用会在需要时重新生成。

Bun 会在进程退出时自动调用它，因此浏览器子进程不会在你的脚本之外存活。

事件循环行为

浏览器子进程本身不会让 Bun 的事件循环保持运行。打开的 WebView 仅会在存在待处理操作（例如尚未完成的 navigate() 或 evaluate()）时让进程保持运行。一旦你关闭最后一个视图，或最后一个待处理操作完成，Bun 就会自然退出。

子进程死亡

如果浏览器子进程意外死亡（崩溃、被 OOM-kill、SIGKILL），每个视图上所有待处理的 promise 都会以描述其死亡原因的错误拒绝（"Chrome killed by signal 9"、"WebView host process died"）。对这些视图进行后续操作会抛出异常。

并发模型

每个视图都有少量用于并发的独立“操作槽位”。同一种操作在任一时刻最多只有一个在执行：

• 一个 navigate()（在 Chrome 后端与 reload()/goBack()/goForward() 共享）
• 一个 evaluate()
• 一个 screenshot()
• 一个 cdp()（仅 Chrome）
• 一个“简单”操作 — click()、type()、press()、scroll()、scrollTo()、resize()（以及 WebKit 后端的 reload()/goBack()/goForward()）共享此槽位

在操作槽位被占用时启动第二个操作会同步抛出 ERR_INVALID_STATE — 它不会排队。实际上，请对每次调用使用 await。

不同视图之间的操作完全独立，并会并行运行 — 每个视图都有自己的渲染器进程。

参考

new Bun.WebView(options?)

backend 对象形式

实例属性

实例方法

click() 选项

press() 选项

scrollTo() 选项

screenshot() 选项

静态方法