Defuddle 使用教程：一条命令提取网页正文为 Markdown

【免费下载链接】defuddleGet the main content of any page as Markdown.项目地址: https://gitcode.com/gh_mirrors/de/defuddle

Defuddle 是一个网页内容提取工具：给它一个 URL 或本地 HTML 文件，它会自动认出文章主体，把侧边栏、广告位、评论区剥掉，返回干净的内容和标题、作者、发布日期等元数据。写代码的开发者可以把它当库集成，只想把网页快速变成 Markdown 的人也能零代码跑通。

🚀 一条命令出结果，先不装任何东西

最省事的方式是用npx，跳过全局安装、当场运行。它接受三种输入：本地文件、URL、或者从 stdin 管道喂进来的 HTML。

# 本地 HTML 文件，输出 Markdown 正文 npx defuddle parse article.html --markdown # 直接给 URL，Defuddle 自己负责抓取页面 npx defuddle parse https://example.com/article --markdown # 把已有的 HTML 从管道喂进去 cat page.html | npx defuddle parse --markdown

默认输出是 HTML 正文，加--markdown（或-m）才得到 Markdown。需要长期在 Node.js 项目里用时再执行npm install defuddle，或者npm install -g defuddle把defuddle命令装到全局。

📄 读懂输出：Defuddle 给你什么

不确定提取结果长什么样时，先用--json跑一遍，所有字段一目了然。

# 以 JSON 输出完整结果，含元数据 npx defuddle parse article.html --json

日常最常用的几个字段：

• content/contentMarkdown：清洗后的正文，分别是 HTML 和 Markdown
• title、author、published：标题、作者、发布日期
• wordCount、parseTime：正文字数、解析耗时（毫秒）
• schemaOrgData：页面里嵌入的 schema.org 结构化数据

结果想进笔记软件，把元数据挂到头部就行：

# 在开头附上 YAML frontmatter，直接写入 note.md npx defuddle parse article.html --markdown --frontmatter -o note.md

只想要某一个字段的话，--property一步到位：

# 只输出标题 npx defuddle parse article.html --property title

换到 Node.js 或浏览器里用

作为库集成时，两个环境的 API 形态一致：传入文档，拿回内容和元数据。

Node.js 需要一个 DOM 实现（linkedom 或 jsdom），且package.json里要声明"type": "module"：

// Node.js：用 linkedom 解析 HTML 字符串，请求 Markdown 输出 import { parseHTML } from 'linkedom'; import { Defuddle } from 'defuddle/node'; const { document } = parseHTML(html); const result = await Defuddle(document, 'https://example.com/article', { markdown: true }); console.log(result.content); // Markdown 正文 console.log(result.title, result.author);

浏览器端则完全不用装 DOM 库：

// 浏览器：直接解析当前页面 import Defuddle from 'defuddle'; const result = new Defuddle(document).parse();

包内有三个入口：默认的defuddle面向浏览器；defuddle/full额外提供 MathML 与 LaTeX 互转；defuddle/node面向 Node.js、功能最全。想读源码可以git clone https://gitcode.com/gh_mirrors/de/defuddle拉下来翻。

⚙️ 调行为：一张表看懂选项和调试

默认配置就能用，只在"没认出正文"或"不想保留图片"时才需要动手。

想知道"它为什么选这一段"，开调试模式：

npx defuddle parse article.html --debug

结果的debug字段里包含正文元素最终选中的 CSS 选择器（contentSelector）、被移除元素的清单和原因（removals）、以及捕获到的错误（errors）。如果某个清理环节误伤内容，API 里还能单独关掉对应步骤，比如removeLowScoring: false会跳过基于评分的剔除。

三个用得上的实战做法

批量归档一个目录的 HTML。for 循环加 frontmatter，笔记可以直接入库：

for f in articles/*.html; do npx defuddle parse "$f" --markdown --frontmatter -o "notes/$(basename "$f" .html).md" done

接进管道喂给别的工具。stdin 支持意味着它可以插在任意流程中间：

# curl 拉页面后直接提取正文 curl -sL https://example.com/post | npx defuddle parse --markdown

处理特殊站点。内置了 YouTube、Reddit、X、维基百科等站点的专用提取器，甚至能拉取视频字幕；规则都在 src/extractors/ 目录里。遇到对默认 UA 返回 403 的站点，给 URL 加上--user-agent换成浏览器 UA 即可。

🔍 答疑

正文靠 JS 渲染才出现怎么办？Node 端默认走的parseAsync()会在 HTML 里找不到正文时退回站点专用异步提取器，比如 YouTube 页面会去拉字幕。不想发任何网络请求就设useAsync: false。

正文识别不对怎么办？先加--debug看选中的选择器和移除清单定位原因；站点结构固定的话，直接指定contentSelector更稳。

数学公式和脚注支持吗？支持，MathJax/KaTeX 会统一转成标准 MathML，脚注引用也会被标准化；需要 MathML 与 LaTeX 互转时改用 full 版打包。

和 Readability 比有什么差别？定位是同类替代品，但策略更保守：拿不准的少删，用移动端样式辅助判断哪些是干扰元素，元数据提取得更全。

收尾

一句话总结：Defuddle 把"杂乱的网页"变成"干净正文 + 结构化元数据"，命令行应付一次性需求，API 应付长期流水线。想深入的话，从 README 开始，再看 主提取逻辑、清理规则 和 元素标准化实现 三条线就够覆盖全貌。

核心关键词：Defuddle 网页内容提取

长尾关键词：网页转 Markdown、npx defuddle parse、Defuddle 命令行用法、文章正文提取、网页清理工具

【免费下载链接】defuddleGet the main content of any page as Markdown.项目地址: https://gitcode.com/gh_mirrors/de/defuddle