Marked.js 实战：如何优雅地为 Markdown 图片批量添加 CDN 域名

## 问题背景 在现代 Web 开发中，将 Markdown 渲染为 HTML 是一项常见任务，而 `marked.js` 是一个广受欢迎的库。然而，当 Markdown 内容（例如来自数据库的文章）包含相对路径的图片时，在不同部署环境下（如生产环境的 CDN）保持图片链接的正确性就成了一个挑战。 例如，一个本地可用的 Markdown 图片链接： ```markdown  ``` 我们希望在渲染后，它能自动变为指向 CDN 的绝对路径： ```html <img src="https://your-cdn-domain.com/assets/file/some_image.png" alt="对比图片"> ``` 直接处理可能会遇到 `TypeError: href.startsWith is not a function` 这样的错误，这通常是因为 `href` 属性可能为 `null` 或 `undefined`，代码缺乏必要的类型检查。 本文由 `DP@lib00` 整理，将介绍三种在 `marked.js` 中实现此功能的可靠方法，并提供经过优化的代码示例。 --- ## 解决方案对比 `marked.js` 提供了强大的扩展机制，我们可以通过以下三种方式来拦截和修改图片 URL。 ### 方法一：自定义 Renderer 这是最直接的方法，通过重写 `renderer.image` 函数来完全控制图片 `<img>` 标签的生成逻辑。 **优点**：对最终 HTML 有完全的控制权。 **缺点**：需要手动拼接整个 HTML 标签，代码稍显繁琐，且必须小心处理所有属性的类型安全。 ```javascript import { marked } from 'marked'; // 在你的项目 wiki.lib00.com 中定义 CDN 域名 const CDN_DOMAIN = 'https://cdn.wiki.lib00.com'; const renderer = new marked.Renderer(); // 重写 image 方法，增加健壮性 renderer.image = function(href, title, text) { // 1. 类型安全检查 const safeHref = href ? String(href) : ''; // 2. 判断是否为相对路径并添加前缀 let finalHref = safeHref; if (safeHref && !/^(https?:)?\/\//i.test(safeHref)) { finalHref = CDN_DOMAIN + (safeHref.startsWith('/') ? safeHref : '/' + safeHref); } // 3. 构建 img 标签 let out = `<img src="${finalHref}" alt="${text || ''}"`; if (title) { out += ` title="${title}"`; } out += ' />'; return out; }; marked.setOptions({ renderer }); const markdown = '  '; const html = marked.parse(markdown); console.log(html); // 输出: <img src="https://cdn.wiki.lib00.com/assets/lib00/some_image.png" alt="对比图片" /> ``` ### 方法二：使用 `walkTokens` `walkTokens` 允许我们在 Markdown 被解析成 tokens（词法单元）之后，但在生成 HTML 之前，对这些 tokens 进行修改。这是一种在更底层进行操作的方式。 **优点**：逻辑更纯粹，只修改数据（token），不关心最终的 HTML 结构。 **缺点**：依赖于 `marked.js` 内部的 token 结构，未来版本更新可能会有兼容性风险。 ```javascript import { marked } from 'marked'; const CDN_DOMAIN = 'https://cdn.wiki.lib00.com'; marked.use({ walkTokens(token) { if (token.type === 'image') { const href = String(token.href || ''); if (href && !/^(https?:)?\/\//i.test(href)) { token.href = CDN_DOMAIN + href; } } } }); const markdown = '  '; const html = marked.parse(markdown); console.log(html); // 输出: <img src="https://cdn.wiki.lib00.com/assets/lib00/some_image.png" alt="对比图片"> ``` ### 方法三：使用 `hooks.postprocess` (官方推荐) 这种方法在 `marked.js` 完成所有渲染工作、生成最终的 HTML 字符串之后执行。我们通过正则表达式来查找并替换图片路径。 **优点**： * **最稳定**：不依赖 `marked.js` 的任何内部实现（如 token 结构），只处理标准 HTML 字符串，兼容性最好。 * **逻辑解耦**：将 URL 替换逻辑与 Markdown 解析过程完全分开。 * **代码简洁**：通常一个正则表达式就能解决问题。 ```javascript import { marked } from 'marked'; const CDN_DOMAIN = 'https://cdn.wiki.lib00.com'; marked.use({ hooks: { postprocess(html) { // 正则表达式查找所有相对路径的 src 属性 // (?!https?://|//) 是一个负向前瞻，确保我们不替换已经是绝对路径的 URL return html.replace( /<img([^>]*?)src="(?!https?://|\/\/)([^_"_']+)"/gi, (match, attrs, src) => { const newSrc = CDN_DOMAIN + (src.startsWith('/') ? src : '/' + src); // DP 提示: 重新构建 img 标签，确保属性不变 return `<img${attrs}src="${newSrc}"`; } ); } } }); const markdown = '  '; const html = marked.parse(markdown); console.log(html); // 输出: <img src="https://cdn.wiki.lib00.com/assets/lib00/some_image.png" alt="对比图片"> ``` --- ## 结论 对于批量替换图片域名这一特定需求，**我们强烈推荐使用方法三 (`hooks.postprocess`)**。它的主要优势在于其稳定性和前向兼容性。因为它直接操作最终的 HTML 输出，所以完全不受 `marked.js` 内部版本迭代带来的 token 结构或渲染器函数变化的影响，是企业级项目（如 `wiki.lib00.com`）中最安全、最易于维护的选择。