HTMLRewriter - Bun 中文文档

HTMLRewriter 允许你使用 CSS 选择器转换 HTML 文档。它可用于 Request、Response，以及 string。Bun 的实现基于 Cloudflare 的 lol-html。

用法

一个常见的使用场景是重写 HTML 内容中的 URL。以下示例将图片源和链接 URL 重写为 CDN 域名：

// 将所有图片替换为 rickroll
const rewriter = new HTMLRewriter().on("img", {
  element(img) {
    // 著名的 rickroll 视频缩略图
    img.setAttribute("src", "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg");

    // 在图片外围套一个指向视频的链接
    img.before('<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">', {
      html: true,
    });
    img.after("</a>", { html: true });

    // 添加一些有趣的 alt 文本
    img.setAttribute("alt", "绝对不是一个 rickroll");
  },
});

// 示例 HTML 文档
const html = `
<html>
<body>
  <img src="/cat.jpg">
  <img src="dog.png">
  <img src="https://example.com/bird.webp">
</body>
</html>
`;

const result = rewriter.transform(html);
console.log(result);

此代码将所有图片替换为 Rick Astley 的缩略图，并将每个 <img> 包裹在一个链接中，生成的差异如下：

<html>
  <body>
    <img src="/cat.jpg" /> 
    <img src="dog.png" /> 
    <img src="https://example.com/bird.webp" /> 
    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank"> 
      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="绝对不是一个 rickroll" /> 
    </a> 
    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank"> 
      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="绝对不是一个 rickroll" /> 
    </a> 
    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank"> 
      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="绝对不是一个 rickroll" /> 
    </a> 
  </body>
</html>

现在页面上的每张图片都会被 Rick Astley 的缩略图替换，点击任意图片都会跳转到一个非常著名的视频。

输入类型

HTMLRewriter 可以转换来自多种来源的 HTML。输入类型会被自动识别和处理：

// 从 Response
rewriter.transform(new Response("<div>内容</div>"));

// 从字符串
rewriter.transform("<div>内容</div>");

// 从 ArrayBuffer
rewriter.transform(new TextEncoder().encode("<div>内容</div>").buffer);

// 从 Blob
rewriter.transform(new Blob(["<div>内容</div>"]));

// 从 File
rewriter.transform(Bun.file("index.html"));

请注意，Cloudflare Workers 中的 HTMLRewriter 仅支持 Response 对象。

元素处理器

on(selector, handlers) 方法让你为匹配 CSS 选择器的 HTML 元素注册处理器。解析时每个匹配元素都会调用对应处理器：

rewriter.on("div.content", {
  // 处理元素
  element(element) {
    element.setAttribute("class", "new-content");
    element.append("<p>新内容</p>", { html: true });
  },
  // 处理文本节点
  text(text) {
    text.replace("新文本");
  },
  // 处理注释
  comments(comment) {
    comment.remove();
  },
});

这些处理器支持异步，返回 Promise。注意异步操作会阻塞转换，直到完成：

rewriter.on("div", {
  async element(element) {
    await Bun.sleep(1000);
    element.setInnerContent("<span>替换内容</span>", { html: true });
  },
});

CSS 选择器支持

on() 方法支持丰富的 CSS 选择器：

// 标签选择器
rewriter.on("p", handler);

// 类选择器
rewriter.on("p.red", handler);

// ID 选择器
rewriter.on("h1#header", handler);

// 属性选择器
rewriter.on("p[data-test]", handler); // 含有该属性
rewriter.on('p[data-test="one"]', handler); // 精确匹配
rewriter.on('p[data-test="one" i]', handler); // 不区分大小写
rewriter.on('p[data-test="one" s]', handler); // 区分大小写
rewriter.on('p[data-test~="two"]', handler); // 单词匹配
rewriter.on('p[data-test^="a"]', handler); // 以...开头
rewriter.on('p[data-test$="1"]', handler); // 以...结尾
rewriter.on('p[data-test*="b"]', handler); // 包含...
rewriter.on('p[data-test|="a"]', handler); // 借字号分隔

// 组合选择器
rewriter.on("div span", handler); // 后代
rewriter.on("div > span", handler); // 直接子元素

// 伪类选择器
rewriter.on("p:nth-child(2)", handler);
rewriter.on("p:first-child", handler);
rewriter.on("p:nth-of-type(2)", handler);
rewriter.on("p:first-of-type", handler);
rewriter.on("p:not(:first-child)", handler);

// 通配符选择器
rewriter.on("*", handler);

元素操作

元素提供多种操作方法，所有修改方法返回元素实例以支持链式调用：

rewriter.on("div", {
  element(el) {
    // 属性操作
    el.setAttribute("class", "new-class").setAttribute("data-id", "123");

    const classAttr = el.getAttribute("class"); // "new-class"
    const hasId = el.hasAttribute("id"); // 布尔值
    el.removeAttribute("class");

    // 内容操作
    el.setInnerContent("新内容"); // 默认会转义 HTML
    el.setInnerContent("<p>HTML 内容</p>", { html: true }); // 解析 HTML
    el.setInnerContent(""); // 清空内容

    // 位置操作
    el.before("前面的内容").after("后面的内容").prepend("第一个子节点").append("最后一个子节点");

    // 插入 HTML 内容
    el.before("<span>before</span>", { html: true })
      .after("<span>after</span>", { html: true })
      .prepend("<span>first</span>", { html: true })
      .append("<span>last</span>", { html: true });

    // 移除
    el.remove(); // 移除元素及其内容
    el.removeAndKeepContent(); // 仅移除元素标签，保留内容

    // 属性
    console.log(el.tagName); // 标签名小写
    console.log(el.namespaceURI); // 元素的命名空间 URI
    console.log(el.selfClosing); // 是否自闭合标签（如 <div />）
    console.log(el.canHaveContent); // 是否可以包含内容（void 元素如 <br> 为 false）
    console.log(el.removed); // 是否被移除

    // 遍历属性
    for (const [name, value] of el.attributes) {
      console.log(name, value);
    }

    // 结束标签处理
    el.onEndTag(endTag => {
      endTag.before("结束标签之前");
      endTag.after("结束标签之后");
      endTag.remove(); // 移除结束标签
      console.log(endTag.name); // 标签名小写
    });
  },
});

文本操作

文本处理器提供文本操作方法，文本片段代表文本节点中一部分内容，并提供该部分的位置等信息：

rewriter.on("p", {
  text(text) {
    // 内容
    console.log(text.text); // 文本内容
    console.log(text.lastInTextNode); // 是否文本节点中的最后一段
    console.log(text.removed); // 是否已被移除

    // 操作
    text.before("文本之前").after("文本之后").replace("新文本").remove();

    // 插入 HTML 内容
    text
      .before("<span>before</span>", { html: true })
      .after("<span>after</span>", { html: true })
      .replace("<span>replace</span>", { html: true });
  },
});

注释操作

注释处理器允许操作注释节点，方法与文本节点类似：

rewriter.on("*", {
  comments(comment) {
    // 内容
    console.log(comment.text); // 注释文本
    comment.text = "新的注释文本"; // 设置注释文本
    console.log(comment.removed); // 是否已被移除

    // 操作
    comment.before("注释之前").after("注释之后").replace("新注释").remove();

    // 插入 HTML 内容
    comment
      .before("<span>before</span>", { html: true })
      .after("<span>after</span>", { html: true })
      .replace("<span>replace</span>", { html: true });
  },
});

文档级处理器

onDocument(handlers) 方法允许处理文档级事件，这些事件发生于文档层面，而不是特定元素内：

rewriter.onDocument({
  // 处理文档类型声明
  doctype(doctype) {
    console.log(doctype.name); // "html"
    console.log(doctype.publicId); // 如果有则为公有标识符
    console.log(doctype.systemId); // 如果有则为系统标识符
  },
  // 处理文本节点
  text(text) {
    console.log(text.text);
  },
  // 处理注释
  comments(comment) {
    console.log(comment.text);
  },
  // 处理文档结尾
  end(end) {
    end.append("<!-- 页脚 -->", { html: true });
  },
});

Response 处理

转换 Response 时：

保留状态码、头部和其他响应属性
转换 body，保持流式能力
自动处理内容编码（如 gzip）
转换后标记原始响应体为已使用
头部被克隆到新响应上

错误处理

HTMLRewriter 操作可能因多种情况抛出错误：

on() 方法中的选择器语法无效
转换方法中 HTML 内容无效
处理 Response 流时出现错误
内存分配失败
输入类型无效（例如传入 Symbol）
响应体已被使用错误

应当捕获并妥善处理错误：

try {
  const result = rewriter.transform(input);
  // 处理结果
} catch (error) {
  console.error("HTMLRewriter 错误:", error);
}

参考链接

你也可以阅读 Cloudflare 文档，该 API 旨在与之兼容。

Documentation Index

​用法

​输入类型

​元素处理器

​CSS 选择器支持

​元素操作

​文本操作

​注释操作

​文档级处理器

​Response 处理

​错误处理

​参考链接

用法