> ## Documentation Index > Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt > Use this file to discover all available pages before exploring further. # HTMLRewriter > 使用 Bun 的 HTMLRewriter 通过 CSS 选择器转换 HTML 文档 HTMLRewriter 允许你使用 CSS 选择器转换 HTML 文档。它可用于 `Request`、`Response`，以及 `string`。Bun 的实现基于 Cloudflare 的 [lol-html](https://github.com/cloudflare/lol-html)。 *** ## 用法 一个常见的使用场景是重写 HTML 内容中的 URL。以下示例将图片源和链接 URL 重写为 CDN 域名： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} // 将所有图片替换为 rickroll const rewriter = new HTMLRewriter().on("img", { element(img) { // 著名的 rickroll 视频缩略图 img.setAttribute("src", "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"); // 在图片外围套一个指向视频的链接 img.before('', { html: true, }); img.after("", { html: true }); // 添加一些有趣的 alt 文本 img.setAttribute("alt", "绝对不是一个 rickroll"); }, }); // 示例 HTML 文档 const html = ` `; const result = rewriter.transform(html); console.log(result); ``` 此代码将所有图片替换为 Rick Astley 的缩略图，并将每个 `` 包裹在一个链接中，生成的差异如下： ```html theme={"theme":{"light":"github-light","dark":"dracula"}} 绝对不是一个 rickroll 绝对不是一个 rickroll 绝对不是一个 rickroll ``` 现在页面上的每张图片都会被 Rick Astley 的缩略图替换，点击任意图片都会跳转到[一个非常著名的视频](https://www.youtube.com/watch?v=dQw4w9WgXcQ)。 ### 输入类型 HTMLRewriter 可以转换来自多种来源的 HTML。输入类型会被自动识别和处理： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} // 从 Response rewriter.transform(new Response("
内容
")); // 从字符串 rewriter.transform("
内容
"); // 从 ArrayBuffer rewriter.transform(new TextEncoder().encode("
内容
").buffer); // 从 Blob rewriter.transform(new Blob(["
内容
"])); // 从 File rewriter.transform(Bun.file("index.html")); ``` 请注意，Cloudflare Workers 中的 HTMLRewriter 仅支持 `Response` 对象。 ### 元素处理器 `on(selector, handlers)` 方法让你为匹配 CSS 选择器的 HTML 元素注册处理器。解析时每个匹配元素都会调用对应处理器： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} rewriter.on("div.content", { // 处理元素 element(element) { element.setAttribute("class", "new-content"); element.append("

新内容

", { html: true }); }, // 处理文本节点 text(text) { text.replace("新文本"); }, // 处理注释 comments(comment) { comment.remove(); }, }); ``` 这些处理器支持异步，返回 Promise。注意异步操作会阻塞转换，直到完成： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} rewriter.on("div", { async element(element) { await Bun.sleep(1000); element.setInnerContent("替换内容", { html: true }); }, }); ``` ### CSS 选择器支持 `on()` 方法支持丰富的 CSS 选择器： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} // 标签选择器 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); ``` ### 元素操作 元素提供多种操作方法，所有修改方法返回元素实例以支持链式调用： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} 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("

HTML 内容

", { html: true }); // 解析 HTML el.setInnerContent(""); // 清空内容 // 位置操作 el.before("前面的内容").after("后面的内容").prepend("第一个子节点").append("最后一个子节点"); // 插入 HTML 内容 el.before("before", { html: true }) .after("after", { html: true }) .prepend("first", { html: true }) .append("last", { html: true }); // 移除 el.remove(); // 移除元素及其内容 el.removeAndKeepContent(); // 仅移除元素标签，保留内容 // 属性 console.log(el.tagName); // 标签名小写 console.log(el.namespaceURI); // 元素的命名空间 URI console.log(el.selfClosing); // 是否自闭合标签（如
） console.log(el.canHaveContent); // 是否可以包含内容（void 元素如
为 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); // 标签名小写 }); }, }); ``` ### 文本操作 文本处理器提供文本操作方法，文本片段代表文本节点中一部分内容，并提供该部分的位置等信息： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} 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("before", { html: true }) .after("after", { html: true }) .replace("replace", { html: true }); }, }); ``` ### 注释操作 注释处理器允许操作注释节点，方法与文本节点类似： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} rewriter.on("*", { comments(comment) { // 内容 console.log(comment.text); // 注释文本 comment.text = "新的注释文本"; // 设置注释文本 console.log(comment.removed); // 是否已被移除 // 操作 comment.before("注释之前").after("注释之后").replace("新注释").remove(); // 插入 HTML 内容 comment .before("before", { html: true }) .after("after", { html: true }) .replace("replace", { html: true }); }, }); ``` ### 文档级处理器 `onDocument(handlers)` 方法允许处理文档级事件，这些事件发生于文档层面，而不是特定元素内： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} 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） * 响应体已被使用错误 应当捕获并妥善处理错误： ```ts theme={"theme":{"light":"github-light","dark":"dracula"}} try { const result = rewriter.transform(input); // 处理结果 } catch (error) { console.error("HTMLRewriter 错误:", error); } ``` *** ## 参考链接 你也可以阅读 [Cloudflare 文档](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/)，该 API 旨在与之兼容。