acorn：纯Python零依赖的HTML解析库实战解析

做网页数据处理的人几乎都绕不开 HTML 解析这件事。提到 Python 里的 HTML 解析库大家第一反应通常是 BeautifulSoup 或者 lxml这没问题。但我在做一些受限环境的自动化任务时遇到过一个很实际的需求不能装任何带 C 扩展的包又要有一个能解析、能查询、能修改 HTML 的 DOM 库。于是我用到了 acorn——一个纯 Python 实现、零第三方依赖、API 贴近浏览器 DOM 标准的小型解析器。它的语法足够清爽参数设计也符合直觉处理不规范 HTML 时容错能力还不差。这篇文章就围绕 acorn 包的语法、常用参数和几个真实场景把我实际用到的经验完整写出来适合正在写爬虫、处理 HTML 模板或者想找一个比 html.parser 更好用的标准库替代方案的朋友参考。1. 为什么这个“冷门”的 Python HTML 解析器值得放进工具箱先交代一个背景。当时我在做一个离线环境下的网页信息采集模块Python 版本没问题但环境里不允许随便编译依赖lxml 装不上BeautifulSoup 依赖的 soupsieve 和标准库 html.parser 用起来又不够顺手。最后我翻到了 acorn才意识到 HTML 解析这个场景其实有第三条路可以走。1.1 纯 Python、零依赖意味着部署时省掉一堆烦恼acorn 最醒目的特点就是“零依赖”。你没有看错它连一个外部库都不需要不像 bs4 还依赖 soupsieve也不像 lxml 需要 C 编译器。你只需要通过 pip 安装 acorn或者直接把源码拷进项目目录就能在绝大多数 Python 3 环境里运行。这一点对生产环境价值非常大。很多企业内网机器、容器镜像、离线集群里装带 C 扩展的库会碰到 glibc 版本、gcc 缺失、pip 下载源受限等奇怪问题而 acorn 是纯 Python 代码基本不会出现这类兼容性故障。1.2 它不是又一个“简易爬虫工具”而是真正贴近 DOM 标准的解析器用过浏览器开发者工具的人都熟悉document.getElementById()、element.children、node.parentNode这一套 API。acorn 把浏览器 DOM 的那套结构搬到了 Python 里节点类型、父子关系、属性操作都按照 DOM 标准设计而不是像 BeautifulSoup 那样发明一套自己的find_all()体系。这带来一个很有意思的好处如果你本来就有前端经验或者写过 JavaScript 的 DOM 操作那你第一次打开 acorn 的文档时几乎不需要重新学习就能凭直觉写出正确的代码。我在团队里带过好几个新人他们上手 acorn 的速度明显比学 bs4 的选择器语法快因为“标签、文本、属性、兄弟节点”这些概念早就刻在脑子里了。1.3 和 BeautifulSoup、lxml 的定位差别不是性能而是“场景适配”做个简单对比方便你判断什么时候该选 acorn。维度acornBeautifulSoup lxmllxml依赖类型纯 Pythonbs4 纯 Pythonlxml 有 C 扩展C 扩展安装难度极低低但 lxml 在部分环境易出问题需要编译或预编译 wheelAPI 风格DOM 标准find/find_all 选择器风格DOM XPath 风格容错能力能修复常见不规范 HTML很强一般功能丰富度基础 DOM 操作很全面很全面性能中规中矩中等快从表格能看到acorn 并不是来取代 bs4 或 lxml 的。它的优势在“能把事情做对且不惹麻烦”需要快速解析、修改、序列化 HTML 的日常任务它都能优雅地完成。如果你要跑的爬虫数据量成千上万、对性能要求极高我当然建议你继续用 lxml但如果你要的是稳定、干净、文档好懂的解析器acorn 很值得你花十分钟试一把。2. 手把手摸清 Acorn 的语法骨架安装、解析入口、核心对象2.1 安装完直接导入几个常见切入点安装过程不啰嗦pip install acorn安装之后最核心的导入就是两个解析函数from acorn import parse_html, parse_fragment from acorn.errors import ParseError在使用前先弄明白这两个解析入口的关系。parse_html()专门用来解析一份完整的 HTML 文档它返回的是一个Document对象。文档里可以包含 doctype、html、head、body 这些结构而parse_fragment()用来解析一个 HTML 片段比如一段div.../div或者不带根节点的“碎片”返回的是DocumentFragment。2.2 第一次解析看懂 Document、Element、Text 的三层关系直接看代码感受一下 acorn 的语法长什么样from acorn import parse_html html_str !DOCTYPE html html headtitle测试页面/title/head body h1 idmainTitle欢迎/h1 p classintro这是一个 a hrefhttps://example.com链接/a 文本/p /body /html doc parse_html(html_str) html_el doc.document_element print(html_el.tag_name) # html print(doc.get_element_by_id(mainTitle).text) # 欢迎 p_el html_el.get_elements_by_tag_name(p)[0] print(p_el.get_attribute(class)) # intro print(p_el.text) # 这是一个 链接 文本 for child in p_el.children: print(child) # a href...链接/a运行之后你会发现几个关键点document_element指向html根元素。get_element_by_id()和get_elements_by_tag_name()是 Element 对象上的查找方法也可以从 document 上直接调用作用范围是整个文档。Element.children只返回元素子节点不会把文本节点和注释节点混进来。Element.text返回的是该元素下所有后代文本节点的拼接结果。2.3 四种常见的节点对象各管一摊acorn 的对象体系可以总结成下面这张表对象对应 DOM 节点常用属性/方法典型场景Documentdocumentdocument_element、get_element_by_id()整份 HTML 的入口Element元素节点tag_name、attributes、children、parent、text、outer_html、set_attribute()对标签的读取和修改Text文本节点data、parent处理文字内容Comment注释节点data过滤注释节点在绝大多数实际任务里你打交道最多的是Element。比如你在写爬虫时要定位一个 id 为content的 div用doc.get_element_by_id(content)就够要抓取所有.item类的元素先用get_elements_by_class_name(item)如果这个类名带空格、有多个类名直接传item active这样的字符串也没问题acorn 会把每个类名拆开匹配。3. 参数细节与序列化真正能提升效率的调用姿势3.1 解析函数的参数其实比想象中少但几个关键词值得留意parse_html()最常用的调用方式是只传一个 HTML 字符串。不过在实际项目中你大概率会遇到“页面字符编码不对”和“HTML 片段本身不完整”这两个问题。acorn 的解析器本身能处理常见的编码标记比如meta charsetutf-8同时也支持你显式传入编码信息。我一般会在拿到网络响应的 bytes 后先尝试用response.apparent_encoding或response.encoding做些标准化再转成字符串。还有一类情况是 HTML 里没有根节点只有一堆p.../pdiv.../div这时parse_html()也能把它包进一个虚拟的文档对象里你依然能通过doc.document_element去访问内容不会直接抛错。参数数量少是 acorn 的优点之一不容易出现“传错参数名”的问题。下面是我经常用到的几种调用模式from acorn import parse_html, parse_fragment # 最常见从一个网页字符串开始 doc parse_html(response_text) # 处理一堆没有完整文档头的片段 frag parse_fragment(li苹果/lili香蕉/li) items frag.get_elements_by_tag_name(li) for li in items: print(li.text)3.2 inner_html、outer_html 和 serialize()序列化的三个层次我在项目里最常踩的坑之一就是“明明改了节点但打印整个文档时发现没生效”。原因是很多初学者只会用str(doc)但 acorn 里序列化的入口有好几个使用场景不同。element.outer_html返回元素本身及其所有子内容的 HTML 字符串。element.inner_html只返回元素内部内容的 HTML 字符串。node.serialize()把任意节点包括元素、文本、注释、文档片段序列化成一个字符串。看一下实际用法from acorn import parse_html doc parse_html(divphello/p/div) div doc.document_element.get_elements_by_tag_name(div)[0] print(div.outer_html) # divphello/p/div print(div.inner_html) # phello/p print(div.serialize()) # divphello/p/div如果你把一个 Text 节点单独提取出来调用serialize()返回的只是纯文本字符串不会有标签包裹。理解这三个层次之后无论你是做“局部模板替换”还是“整页输出”都能快速选对方法。3.3 查找和属性操作的传参套路acorn 是 DOM 风格的 API所以它的方法参数往往比 bs4 的选择器更直白# 按 id 查找 el doc.get_element_by_id(app) # 返回单个元素或 None # 按标签名查找返回列表 links doc.get_elements_by_tag_name(a) # 按类名查找返回列表 cards doc.get_elements_by_class_name(card) # 获取属性 href link.get_attribute(href) # 设置属性 link.set_attribute(target, _blank) # 删除属性 link.remove_attribute(target)有一点值得注意get_elements_by_class_name()传入类名时不需要带点号多个类名之间用空格分隔。DOM 标准里这个参数本身可以是一个 DOMTokenListacorn 在 Python 里简化为字符串解析所以你传btn btn-primary也能正常工作。至于get_attribute()如果属性不存在多数情况下返回None写判断时可以直接用or 做兜底。4. 实际应用案例一把新闻页变成结构化字典4.1 提取标题和 meta 描述爬虫场景里最常见的需求就是“从网页里抓标题、链接、图片、描述”。我用 acorn 实现过一个新闻采集函数核心逻辑并不复杂。假设我们有一份新闻页源码html_str html head title某地突降暴雨 多条道路临时封闭/title meta namedescription content当地交警提醒市民减少外出 /head body article h1 classnews-title某地突降暴雨 多条道路临时封闭/h1 div classcontent p今天凌晨开始当地出现持续强降雨天气。/p pa href/2025/01/rain.html查看更多报道/a/p img src/images/rain.jpg>from acorn import parse_html doc parse_html(html_str) title doc.get_elements_by_tag_name(title)[0].text meta doc.get_elements_by_tag_name(meta) description for m in meta: if m.get_attribute(name) description: description m.get_attribute(content) or 这里有个小坑title标签在 acorn 里也能通过doc.get_elements_by_tag_name(title)找到但如果页面里既有title又有其他地方自定义了同名标签最好用doc.document_element.get_elements_by_tag_name(title)限定范围或者直接根据 HTML 结构判断。4.2 提取正文链接并处理相对路径新闻页面里的链接经常写成相对路径比如/2025/01/rain.html。如果你想把它变成完整 URL光靠 acorn 是不够的需要配合urllib.parse.urljoinfrom urllib.parse import urljoin, urlparse base_url https://news.example.com/local/index.html def extract_links(doc, base_url): result [] for a in doc.get_elements_by_tag_name(a): href a.get_attribute(href) if not href: continue full_url urljoin(base_url, href) # 过滤 javascript:、mailto: 这类协议 if full_url.startswith((http://, https://)): result.append({ text: a.text.strip(), url: full_url, }) return result用urljoin的好处是即使 base 地址是https://news.example.com/local/index.html而 href 是../images/rain.jpg它也能正确地拼出https://news.example.com/images/rain.jpg。4.3 提取图片 URL处理懒加载现在很多新闻站的图片用的是懒加载img标签里真实的图片地址不一定在src属性上而是在>def extract_images(doc, base_url): result [] for img in doc.get_elements_by_tag_name(img): src img.get_attribute(src) or img.get_attribute(data-src) or if not src: continue result.append({ src: urljoin(base_url, src), alt: img.get_attribute(alt) or , }) return result有两点心得一是很多页面在src里放一个 1x1 的占位图而真实地址在>from acorn import parse_html from urllib.parse import urljoin def parse_news_page(html_text, base_url): doc parse_html(html_text) # 标题 title if doc.get_elements_by_tag_name(title): title doc.get_elements_by_tag_name(title)[0].text.strip() # meta description description for m in doc.get_elements_by_tag_name(meta): if m.get_attribute(name) description: description m.get_attribute(content) or # 正文段落 paras [] for p in doc.get_elements_by_tag_name(p): text p.text.strip() if text: paras.append(text) # 链接和图片 links extract_links(doc, base_url) images extract_images(doc, base_url) return { title: title, description: description, paragraphs: paras, links: links, images: images, }这个函数我在实际采集任务里用了很久结构简单扩展也方便。如果你要处理的是复杂的网页比如正文藏在嵌套很深的div里可以直接用doc.get_element_by_id(content)先定位到正文容器再在容器内做全文提取效率更高。5. 实际应用案例二清洗 HTML 模板并批量改写属性除了网页采集acorn 在做“HTML 清洗”这件事上也非常顺手。比如从客户那边拿到一份包含大量内联样式、废弃标签、危险脚本的 HTML 模板你希望得到一份干净、标准、只保留必要结构的片段acorn 的 DOM 修改能力就派上用场了。5.1 一键删除 script、style、iframe 等不需要的节点先看一个删除不需要标签的例子from acorn import parse_html def clean_html(html_text): doc parse_html(html_text) root doc.document_element for tag in [script, style, iframe, noscript]: for el in root.get_elements_by_tag_name(tag): # 先把节点从父级中摘除 parent el.parent if parent is not None: parent.remove_child(el) return doc.document_element.outer_html注意一个关键点get_elements_by_tag_name()返回的是列表但它是实时查询后的快照。你在遍历root.get_elements_by_tag_name(script)的同时修改文档可能会影响后续索引位置。稳妥的做法是先把所有要删除的元素收集起来再统一删除。上面这种写法因为每一步都会重新检索root所以安全如果你把all_scripts root.get_elements_by_tag_name(script)存下来再遍历删除就要小心节点被移除后列表里的某些节点可能已经“脱离”文档parent变成 None。所以我的习惯是先收集再统一处理。to_remove [] for tag in [script, style, iframe]: to_remove.extend(root.get_elements_by_tag_name(tag)) for el in to_remove: if el.parent is not None: el.parent.remove_child(el)5.2 批量给元素加类名、改属性、做数据规整模板清洗的场景里最常见的是“把旧 class 换成新 class”“给所有外链加上relnoopener”。acorn 的set_attribute()可以直接实现# 给所有 a 标签加上 target 和 rel for a in root.get_elements_by_tag_name(a): href a.get_attribute(href) or if href.startswith(http): a.set_attribute(target, _blank) a.set_attribute(rel, noopener noreferrer) # 把所有 class 为 old-class 的元素改成 new-class for el in root.get_elements_by_class_name(old-class): el.set_attribute(class, new-class)如果你需要保留原有的多个类名只追加一个要先读出来再拼for el in root.get_elements_by_tag_name(div): class_name el.get_attribute(class) or if highlight not in class_name.split(): el.set_attribute(class, f{class_name} highlight.strip())5.3 只保留纯文本的“内容净化”有些时候我们希望把一份 HTML 变成一段可读的纯文本。acorn 的text属性可以直接取出所有文本但它会保留原始空白导致大量空行和缩进。我一般会再用正则做一次压缩import re def html_to_text(html_text): doc parse_html(html_text) text doc.document_element.text # 压缩连续空白 text re.sub(r\s, , text) # 在句号、问号后加换行方便阅读 text re.sub(r([。]), r\1\n, text) return text.strip()这样做出来的文本比直接.text干净得多用于摘要生成或全文索引都很合适。每次清洗完模板我会输出三个东西清洗后的 outer_html、纯文本、以及标签统计。统计可以帮你快速确认有没有残留脏标签def tag_stats(root): stats {} for el in root.get_elements_by_tag_name(*): tag el.tag_name stats[tag] stats.get(tag, 0) 1 return stats这招在接手历史遗留 HTML 时特别好用几分钟就能判断出模板里还藏着哪些不该出现的标签。6. 实际应用案例三爬虫采集中的异常处理、编码与性能优化6.1 ParseError 不能吞但要分场景处理acorn 是一个容错能力相当好的解析器但它并不是魔法。当 HTML 本身严重损坏、存在多层未闭合标签嵌套、或者被服务器返回了错误页面格式时解析过程仍有可能抛出异常。我的建议是该捕获的捕获该透传的透传。from acorn import parse_html from acorn.errors import ParseError def safe_parse(html_text): try: return parse_html(html_text) except ParseError as exc: # 记录日志方便以后回来排查 print(f解析失败前 200 个字符{html_text[:200]!r}) print(f错误信息{exc}) # 返回一个空文档调用方自行判断 return None不过说实话acorn 的容错设计比其他解析器更“宽厚”多数情况下即使 HTML 结构混乱它也能生成一棵可用的 DOM 树不会直接崩掉。真正会抛出 ParseError 的往往是很极端的输入比如空字节串、纯乱码、或者只有一个。所以捕获异常只是为了兜底不要让主逻辑被异常打断。6.2 字节字符串先解码再交给 acorn爬虫从网络拿到的内容大多是bytes如果不处理编码直接扔给 parse_html中文字符会变成乱码。我通常推荐用 requests 库的时候直接使用response.text因为它已经根据响应头帮你解码过了但如果拿的是原始字节就得自己处理def decode_html(content: bytes, guessed_charset: str utf-8): for encoding in [guessed_charset, utf-8, gb18030, latin1]: try: return content.decode(encoding) except (UnicodeDecodeError, LookupError): continue return content.decode(utf-8, errorsreplace)这里把gb18030放进来是因为国内不少老站仍然用 GB2312/GBK 编码gb18030是它们的超集能避免很多乱码问题。这部分其实和 acorn 本身无关但如果你不处理好编码acorn 解析得再漂亮也没用。6.3 缓存解析结果别反复 parse 同一段 HTMLacorn 解析速度属于“够用”级别但如果你在循环里反复对同一个 HTML 做 parse那纯粹是浪费。我实测过一个首页约 200KB 的新闻站点首次 parse 需要几十毫秒但如果我把Document对象缓存下来后续的查找和序列化都在毫秒级完成。做法很简单用functools.lru_cache做一层函数缓存from functools import lru_cache from acorn import parse_html lru_cache(maxsize128) def cached_parse(html_text): return parse_html(html_text)需要注意返回的Document对象是可变的如果你在一个任务里修改了它下一次拿到缓存的人看到的也是修改后的结果。所以我一般只在“只读提取”场景用缓存需要修改文档时直接新建实例。另外一个跟性能有关的细节如果你只需要页面的某一部分比如某个 id 明确的节点最好的做法不是对整个文档做全量解析而是先用正则或字符串方法切出目标区块再把区块交给 acorn 处理。虽然听上去不够“优雅”但实际提速效果非常明显。7. 三个实用建议和一个容易踩的坑7.1 什么时候不要用 acornacorn 不是万能钥匙。如果你的项目需要频繁使用 CSS 选择器、XPath、复杂的爬虫匹配规则bs4 或 lxml 的生态更成熟如果你要一次解析上百兆字节的超大 HTML 文件lxml 的 C 引擎在性能上明显占优。acorn 最适合的是“中等规模、偏重 DOM 操作、环境受限”的场景。我个人的选型标准很简单如果一个任务在 5 分钟内能用 acorn 写完我就不引入 bs4如果任务里的选择器复杂到让我怀疑人生我就老老实实回去用 bs4 或 lxml。工具是拿来解决问题的不是拿来信仰的。7.2 注意text属性和inner_html的边界这是新手最容易误解的地方。element.text返回的是该元素下所有后代文本节点的拼接它不会保留标签结构。假设有这样一个标签divphello/ppworld/p/divdiv.text的结果是helloworld中间没有任何换行或空格。如果你希望保留段落间距需要遍历div.get_elements_by_tag_name(p)单独取每个p的 text 再拼接。很多“为什么抓出来的文字挤在一起”的问题根源就在这里。7.3 模块源码不长值得直接翻acorn 的源码非常精炼它不像 lxml 那样有大量底层封装。遇到不理解的 API 或者不确定的边界行为直接打开 site-packages 里的 acorn 源码看一眼往往几分钟就能搞清楚。我甚至觉得任何一个想深入理解 DOM 解析原理的人都可以把 acorn 源码当作入门教材因为它把 HTML 解析的容错逻辑、节点树构建、序列化过程讲得清清楚楚。7.4 一个让我多花了一个小时的坑注释节点有一次我清洗模板发现意外把!-- 这是注释 --也当成文本输出了。后来才意识到node.text只包含文本节点和 CDATA 的内容不包含注释节点但如果我用正则去抓原始 HTML很容易把注释带上。所以在做纯文本抽取时最好在 parse 之前先用正则把!--.*?--删掉或者不要依赖正则去处理 HTML 结构只把原始 HTML 交给 acorn 之后再基于节点树做内容提取。说到底HTML 解析这个领域从来不缺选择缺的是“在正确场景用正确武器”的判断力。acorn 给我的感觉更像一把瑞士军刀——不占地方、关键时刻好用、细节经得起推敲。如果你正好在找一个不吵不闹、能落地解决问题的纯 Python 解析器不妨从这篇文章里的几个案例改一版出来跑跑看。真上了项目以后你可能也会和我一样慢慢习惯把 acorn 放进自己的默认工具箱。