defuddle 如何精准剔除站点 Logo 而不误伤正文——selectors--logo-substring-wrapper 测试样本全解析

原创2026-10-14 18:41:191,679 阅读
文章标签:网页爬虫开发工具

defuddle 如何精准剔除站点 Logo 而不误伤正文——selectors--logo-substring-wrapper 测试样本全解析

在网页正文提取场景中,「Logo」是最常见也最容易误判的页面噪声:几乎所有站点都会把站标放在 <header> 里,而部分站点又习惯用 logo 作为 class 命名的一部分。当正文容器的 class 恰好也包含 logo 子串时(例如 a-content--logo-end),一个粗糙的子串匹配规则会把整篇正文误删。本文以 defuddle 仓库中的测试样本 selectors--logo-substring-wrapper.html 及其期望输出 selectors--logo-substring-wrapper.md 为切入点,逐行拆解 defuddle 的选择器清理机制:精确选择器与部分选择器如何分工、logo 词边界正则如何做到"该删的删、该留的留",以及这一行为如何被 fixture 测试体系固化下来。读完本文,你将掌握 defuddle 选择器规则的判定边界,也能学会如何为自己的站点排查"正文被误删"这类问题。

测试样本要验证什么:一个"名字里藏着 logo"的正文容器

先看这个 fixture 对应的原始 HTML(tests/fixtures/selectors--logo-substring-wrapper.html),它的结构非常典型:

<!DOCTYPE html>
<html>
<head>
<title>City Approves Transit Expansion - Example Daily</title>
<meta name="author" content="Jordan Blake">
</head>
<body>
<header class="site-header">
<div class="logo"><a href="/"><img src="/img/logo.svg" alt="Example Daily"></a></div>
</header>
<main class="page-main">
<article class="article-body">
<h1>City Approves Transit Expansion</h1>

<div class="key-points">
<p>The council approved three new transit lines ...</p>
<!-- 若干关键要点段落 -->
</div>

<div class="a-content a-content--logo-end">
<div class="body-copy">
<p>The vote clears the way for construction to begin ...</p>
<!-- 正文主体段落 -->
</div>
</div>
</article>
</main>
</body>
</html>

页面上存在两个敏感目标:

  1. <header class="site-header"> 内的 <div class="logo">——这是真正的站点 Logo 容器,必须被剔除;
  2. <div class="a-content a-content--logo-end">——这是正文的外层包装容器,它的 class 里含有 logo 子串(a-content--logo-end 中的 logo),但它承载的是文章主体,绝不能因为子串匹配被误删。

测试文件名 selectors--logo-substring-wrapper 正是对这一场景的精确概括:"logo-substring"(logo 子串)与 "wrapper"(正文包装层)。期望输出 selectors--logo-substring-wrapper.md 证明了 defuddle 的正确行为:Logo 容器消失,而正文完好无损地保留下来:

{
  "title": "City Approves Transit Expansion",
  "author": "Jordan Blake",
  "site": "Example Daily",
  "published": ""
}

The council approved three new transit lines on a nine-to-four vote after a hearing that ran past midnight, ending a debate that has occupied the chamber in one form or another for the better part of two decades without ever reaching a binding decision.

Bonds issued by the transit authority will cover roughly two thirds of the projected cost, with the remainder drawn from a state matching fund that lawmakers renewed earlier this year over the objections of the rural caucus, which wanted the money spent on highway resurfacing instead.

Two members who voted against the measure have asked for an independent audit of the ridership projections before any bonds are issued, and a third said she would support the audit even though she voted in favor of the expansion on the merits of the eastern alignment.

Construction on the first line is scheduled to begin in March and to reach the eastern terminus in four years, though the authority has cautioned that the schedule assumes it can acquire the last right-of-way parcels without going to court over the price of two industrial lots.

The county commission still has to ratify the cost-sharing agreement, a step the mayor's office describes as a formality but that at least two commissioners have said they intend to use as leverage for a station stop that the current alignment leaves out entirely.

The vote clears the way for construction to begin next spring on lines that will connect the eastern suburbs to the downtown core for the first time since the original system opened, when the eastern edge of the built-up area stopped several miles short of where it stands today.

Officials estimate that the first of the three lines will carry passengers within four years of groundbreaking, assuming the environmental review now underway concludes on schedule and the authority is able to acquire the last of the right-of-way parcels without resorting to condemnation proceedings.

Opponents argued that the projections rest on optimistic assumptions about population growth in corridors that have seen very little new housing built since the last comprehensive plan, and that the authority has historically overestimated demand on precisely the kind of suburban extension now proposed.

Transit advocates who packed the chamber called the vote long overdue. Earlier proposals collapsed over disputes about which neighborhoods would host maintenance yards and how the costs would be shared between the city and the surrounding county, whose commission has yet to schedule its own vote on the funding agreement.

The authority's chief engineer told the council that early utility relocation work could begin as soon as the environmental review concludes, and that the agency has already begun the procurement process for the rolling stock it expects to need by the time the eastern line opens for revenue service.

A spokesperson for the mayor said the administration considers the funding agreement settled and does not expect the county commission to reopen the cost-sharing formula, which was negotiated over eighteen months and signed by both executives before the council took up the measure this spring.

Construction is expected to begin in March, pending final environmental review.

对比 HTML 与期望输出可以发现三件事:站点 Logo(div.logo)被删除;key-points 与 a-content a-content--logo-end 两层包装被解除(解包而非保留),正文段落以纯 Markdown 段落形式输出;标题、作者、站点名被正确提取到元数据中。

选择器清理在 defuddle 处理管线中的位置

在深入规则细节之前,先明确这段逻辑所处的处理阶段。defuddle 的主流程位于 src/defuddle.ts,其中 removeBySelector 是内容清理管线中的确定性清除步骤:

  • removeHiddenElements:按计算样式剔除隐藏元素;
  • removeEyebrowLabel:剔除标题上方的分类标签;
  • removeBySelector:按 class/id/属性选择器确定性剔除已知非内容元素(导航、页脚、侧栏、Logo 等),在 src/defuddle.ts 中调用,入口函数定义于 src/removals/selectors.ts;
  • removeLowScoring:基于链接密度等启发式打分剔除低分块,运行在 removeBySelector 之后,因此选择器阶段清理得越干净,打分阶段看到的 DOM 越纯净。

removeBySelector 的调用还受两个开关控制:removeExactSelectors 与 removePartialSelectors(默认均为 true,定义见 src/types.ts),分别对应下面要讲的精确匹配与部分匹配两条路径。

第一道防线:精确选择器直接命中 Logo 容器

defuddle 将"特征非常明确"的元素写死在 EXACT_SELECTORS 数组中(src/constants.ts),运行前用 join(',') 拼成一个巨型选择器字符串 EXACT_SELECTORS_JOINED,在 src/removals/selectors.ts 中通过一次 querySelectorAll 全部取出。

与 Logo 相关的精确规则有三条(src/constants.ts):

// logos
'[class="logo" i]',
'#logo',
'#Logo',

注意第一条用的是完全相等的属性选择器 [class="logo" i],即只有当 class 属性值恰好是 logo(不区分大小写)时才命中。本 fixture 中的 <div class="logo"> 正是这种情况,因此它在精确匹配阶段就被标记删除,与后面的部分匹配逻辑无关。而 a-content--logo-end 的 class 值不是 logo,不会被这条规则命中。

精确匹配阶段还有若干保护性跳过逻辑,避免误伤正文:

  • 跳过代码块内的元素(el.closest('pre, code')),防止语法高亮 span 被误删;
  • 跳过带响应式显示类(如 Tailwind 的 hidden sm:flex)的隐藏元素;
  • 跳过 mainContent 的祖先元素,防止正文容器本身被拔除。

第二道防线:部分选择器按词边界匹配 logo

仅仅处理 class="logo" 显然不够,现实中大量站点使用 site-logo、logo-wrapper、header-logo 这类组合类名。这些靠 PARTIAL_SELECTORS 数组中的子串模式处理,其中 logo 的规则是整条数组里最"精密"的一条(src/constants.ts):

// Matches 'logo' only at a class-token edge ('site-logo', 'logo-wrapper').
'(?:(?<![\\w-])logo|logo(?![\\w-]))',

这是一个词边界式正则,含义是:logo 要么出现在 class token 的开头(后面不能跟 \w 或 -,即后面是 token 结束),要么出现在 token 的结尾(前面不能是 \w 或 -,即前面是 token 开始)。用这个规则验证本 fixture 中的两个候选:

class 值 是否匹配 原因
logo(已在精确阶段删除) — 精确选择器 [class="logo" i] 命中
site-logo 匹配 logo 在 token 末尾,前面是 -,lookahead logo(?![\\w-]) 成功
logo-wrapper 匹配 logo 在 token 开头,lookbehind (?<![\\w-])logo 成功
a-content--logo-end 不匹配 logo 前后都是 -,两个方向的边界断言均失败

关键就在 a-content--logo-end:logo 前面是 -、后面也是 -,既不是 token 开头也不是 token 结尾,于是两条分支((?<![\\w-])logo 与 logo(?![\\w-]))全部落空,正文容器得以存活。这正是该 fixture 名称中 "substring" 一词的深意——规则并非简单的"包含 logo 就删",而是"logo 作为一个独立词元出现才删",从而在 logo 作为其他单词组成部分(如 catalog、dialogue,以及本场景的 BEM 风格 --logo-end 修饰符)时保持克制。

如果改成朴素子串匹配 logo,那么 a-content--logo-end 会被命中并整体删除,整篇正文随之丢失——本 fixture 就是用来永久防止这类回归的。

部分匹配的完整判定流程

removeBySelector 的部分匹配阶段(src/removals/selectors.ts)并不只检查 class,而是把多个"测试属性"拼接后统一做正则测试。测试属性定义在 src/constants.ts:

export const TEST_ATTRIBUTES = [
	'class',
	'id',
	'data-component',
	'data-test',
	'data-testid',
	'data-test-id',
	'data-qa',
	'data-cy'
];

运行时会拼成 <a href="https://link.gitcode.com/i/087a6f0e62e8aaee3d7e2094a982134f" target="_blank">class],[id],[data-component],... 这样的属性选择器 TEST_ATTRIBUTES_SELECTOR([src/constants.ts),一次性取出所有候选元素。对每个候选元素:

  1. 跳过已标记删除的元素、[data-defuddle] 提取器输出内的元素,以及 code/pre 及其内部元素——语法高亮、内联代码的类名(如 language-name、meta-)很容易命中噪声词,必须先排除;
  2. 非标题元素把 class + data-component + data-test + data-testid + data-test-id + data-qa + data-cy 拼接成小写字符串做子串匹配;
  3. 标题元素(H1-H6)只检查 class——因为标题的 id 是自动生成的 slug,data-testid="article-header" 这类值会造成大量误报(src/removals/selectors.ts);
  4. id 单独处理:带分隔符的 id(如 feedback-form)走子串匹配;不带分隔符的 id(如 theroleofthings、loopsandfeedback,通常由发布系统把标题词拼接而成)必须走锚定匹配 PARTIAL_SELECTORS_ANCHORED_REGEX,即整个 id 必须完整等于某个选择器词元才删除(src/constants.ts)。原因正如源码注释所写:theroleofthings 内含 hero[_\\-a-z] 的匹配片段 herol,loopsandfeedback 内含 feedback,子串匹配会误删真实章节标题生成的锚点。

对 a-content--logo-end 而言,class 拼接后为 a-content a-content--logo-end,由于 logo 正则的两条边界分支均失败,最终不进入删除集合,正文容器安全。

元数据提取:标题、作者与站点名从何而来

期望输出中的元数据同样值得对照源码验证:

  • title:getBestTitle(src/metadata.ts)按 og:title、twitter:title、schema.org headline、<title>、<h1> 的顺序取候选。本 fixture 没有 og 标签,<title> 为 "City Approves Transit Expansion - Example Daily",<h1> 为 "City Approves Transit Expansion"。随后 cleanTitle(src/metadata.ts)识别出末尾的站点名片段 Example Daily(与检测到的 site name 匹配)并将其剥离,最终标题为 "City Approves Transit Expansion";
  • author:取自 <meta name="author" content="Jordan Blake">(对应 src/metadata.ts 的 byline 提取链路之外、meta 标签优先的路径);
  • site:getSiteName(src/metadata.ts)按 og:site_name、schema.org publisher.name 等候选提取;本 fixture 中站点名 "Example Daily" 由标题剥离流程反向确认(cleanTitle 检测到后缀与站点名一致时返回 detectedSiteName);
  • published:页面无任何日期标记,输出为空字符串——如实反映,不猜测。

这一行为如何被测试体系永久固化

selectors--logo-substring-wrapper 的期望输出并不是手写的,而是 defuddle fixture 测试体系的产物。测试入口在 tests/fixtures.test.ts:

  1. getFixtures()(tests/helpers.ts)自动扫描 tests/fixtures/ 下所有 .html 文件;
  2. 每个 fixture 用 linkedom(或通过 DOM=jsdom 环境变量切换为 jsdom)解析后,以 { separateMarkdown: true, fetch: offlineFetch } 调用 Defuddle,其中 offlineFetch 强制拒绝网络请求,保证测试完全封闭、可复现(tests/fixtures.test.ts);
  3. 结果被序列化为"JSON 元数据前导块 + Markdown 正文"的单文件,即 tests/expected/ 下的 .md;
  4. 若期望文件不存在,则作为基线自动生成;若已存在,则逐字符比较——两侧先经 normalizeMarkdownHtml 归一化(tests/helpers.ts,保持代码块内字节不变、仅归一化正文中的 SVG 属性顺序),任何行为漂移都会导致测试失败。

因此,当你修改 src/constants.ts 中的选择器规则或 src/removals/selectors.ts 的判定逻辑时,只要动到 logo 相关的边界行为,本 fixture 就会立即报警。新增/更新样本的标准流程是:向 tests/fixtures/ 添加 HTML → 运行测试生成基线 → 人工审查 tests/expected/ 下的输出 → 提交两者作为回归护栏。

实战建议:用同一个模型排查自己的页面

理解了这个 fixture 的判定边界后,可以将其直接迁移到自己的内容提取场景:

  1. 排查"正文被误删":先检查正文外层容器(尤其是 CMS 生成的 BEM 类名,如 post--logo-end、article__logo-block)是否被部分选择器命中。命中条件不是"包含某词",而是"该词以独立词元出现"——若容器 class 中噪声词被 -/_ 夹在中间,理论上不会命中,但一旦出现 post-logo 这类组合,就会踩中边界正则;
  2. 排查"Logo 没删干净":若站点 Logo 使用 header-logo、site-logo、logo-wrapper 等组合类,[class="logo" i] 精确规则不会命中,需要依赖部分规则 (?:(?<![\\w-])logo|logo(?![\\w-]));若 Logo 元素本身没有 class/id 特征(例如纯 <svg> 或 <img> 包裹在 <a> 内),通常由 header/nav 等祖先的精确规则连带清除;
  3. 利用调试输出:CLI 运行 npx defuddle parse page.html --debug(命令说明见 README.md),或编程时传入 { debug: true },removeBySelector 会把每一步删除的元素及命中原因写入 debug.removals(src/removals/selectors.ts),字段含义(step、selector、reason、text)在 README.md 中有对应说明,可以直接看到某元素是因为"exact selector match"还是"partial match: 某模式"被删,从而判断是规则过宽还是过窄。

小结

selectors--logo-substring-wrapper 这个样本体积虽小,却浓缩了 defuddle 选择器清理模块的两个核心设计原则:精确规则管"特征明确"的元素([class="logo" i] 直接命中 Logo 容器),部分规则管"命名模糊"的元素但必须严守词元边界(logo 只在 token 边缘匹配),二者叠加才实现了"删掉站标、保住正文"的精确效果。对使用 defuddle 或自研正文提取器的开发者而言,本样本与 src/constants.ts、src/removals/selectors.ts 共同构成了一套可复现、可审计的判定标准:任何选择器改动,都应该先过一遍 fixture 测试,再上线到真实页面。

登录后查看全文
defuddle