# https://github.com/adbar/trafilatura 项目说明书

生成时间：2026-06-19 18:30:13 UTC

## 目录

- [Overview & System Architecture](#page-1)
- [Text & Metadata Extraction Engine](#page-2)
- [Web Crawling, Downloads & URL Discovery](#page-3)
- [CLI, Configuration & Known Issues](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### 相关页面

相关主题：[Text & Metadata Extraction Engine](#page-2), [Web Crawling, Downloads & URL Discovery](#page-3), [CLI, Configuration & Known Issues](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/adbar/trafilatura/blob/main/README.md)
- [HISTORY.md](https://github.com/adbar/trafilatura/blob/main/HISTORY.md)
- [CONTRIBUTING.md](https://github.com/adbar/trafilatura/blob/main/CONTRIBUTING.md)
- [trafilatura/__init__.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/__init__.py)
- [trafilatura/core.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/core.py)
- [trafilatura/settings.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py)
- [trafilatura/readability_lxml.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/readability_lxml.py)
</details>

# Overview & System Architecture

## 1. 项目定位与设计目标

Trafilatura 是一个面向网络文本发现与提取的 Python 库及命令行工具，由语言学家 Adrien Barbaresi 发起，最初为柏林-勃兰登堡科学院的语料库项目（DWDS 与 ZDL）服务。包元信息显示当前版本为 `2.1.0`，遵循 Apache-2.0 许可证 资料来源：[trafilatura/__init__.py:1-15]()。

项目的高层目标可以归纳为三点：

- **网页抓取与正文提取**：从真实网页中精准识别主体内容、标题、作者、日期、站点名、分类与标签等元数据 资料来源：[README.md:1-40]()。
- **多格式输出**：支持 TXT、Markdown、CSV、JSON、HTML、XML 与 XML-TEI 共七种输出格式 资料来源：[README.md:30-60]()。
- **可配置的召回/精度权衡**：通过参数与配置文件，让用户在“少而准”和“多而全”之间灵活切换 资料来源：[trafilatura/settings.py:1-40]()。

在生态层面，Trafilatura 被 HuggingFace、IBM、Microsoft Research、Allen Institute、Stanford 等机构与公司集成使用，是学术与工业界数据采集的常见组件 资料来源：[README.md:80-100]()。

## 2. 系统架构总览

整个系统的处理流程可以抽象为“输入 → 解析 → 提取 → 输出”四个阶段。下图展示从原始 URL 或 HTML 字符串到最终文档的核心数据流：

```mermaid
flowchart LR
    A[URL / HTML 字符串] --> B[downloads.fetch_url / load_html]
    B --> C[lxml HTML Tree]
    C --> D[core._internal_extraction]
    D --> E{配置与启发式}
    E --> F[主提取器<br/>XPath + fallback]
    F --> G[readability_lxml 备选]
    F --> H[jusText 备选]
    F --> I[baseline 备选]
    F --> J[元数据抽取<br/>metadata.extract_metadata]
    J --> K[输出格式化<br/>txt / md / json / xml / xmltei / csv / html]
    K --> L[最终结果]
```

入口函数 `extract`、`bare_extraction`、`extract_with_metadata` 全部委托给 `_internal_extraction`，后者统一加载 HTML 树、按选项执行剪枝、调用正文提取器，并按 `output_format` 序列化结果 资料来源：[trafilatura/core.py:1-80]()。当主提取器不确定时，readability、jusText 与 baseline 作为“备份提取器”接力兜底，从而在精度与召回之间形成多层防线 资料来源：[trafilatura/readability_lxml.py:1-40]()。

## 3. 核心模块与职责

| 模块 | 关键导出 | 职责 |
|------|---------|------|
| `trafilatura`（包入口） | `extract`、`bare_extraction`、`extract_with_metadata`、`extract_metadata`、`fetch_url`、`fetch_response`、`load_html`、`baseline`、`html2txt` | 暴露顶层 API；统一对外签名 资料来源：[trafilatura/__init__.py:20-40]() |
| `core` | `_internal_extraction` | 串联 HTML 解析、剪枝、提取、格式化全流程 资料来源：[trafilatura/core.py:1-120]() |
| `settings` | `DEFAULT_CONFIG`、`Options` 协议 | 集中维护默认参数、XPath 规则、语言映射与黑名单 资料来源：[trafilatura/settings.py:1-40]() |
| `readability_lxml` | `Document`、`Candidate` | 实现可读性打分，作为主提取失败时的备选路径 资料来源：[trafilatura/readability_lxml.py:1-60]() |
| `metadata` | `extract_metadata` | 从 JSON-LD、meta 标签、正文上下文中提取作者/日期/标题等 资料来源：[trafilatura/core.py:60-100]() |
| `downloads` | `fetch_url`、`fetch_response` | 网络层抓取，支持 sitemap、feed 抓取与礼貌爬取 资料来源：[trafilatura/__init__.py:20-35]() |

`settings.py` 中的常量定义了清理策略：例如 `MANUALLY_STRIPPED` 列出应直接剔除的元素，`BASIC_CLEAN_XPATH` 用于在树层面移除 `<script>`、`<style>`、`<footer>` 等噪声 资料来源：[trafilatura/settings.py:1-40]()。

## 4. 配置、可扩展点与已知问题

Trafilatura 提供三种配置途径：

1. **函数参数**：在 `extract()` 中直接传入 `favor_precision`、`favor_recall`、`include_comments`、`include_tables`、`include_images`、`include_links` 等 资料来源：[trafilatura/core.py:1-60]()。
2. **配置文件**：`DEFAULT_CONFIG` 是 `ConfigParser` 解析对象，可被 `config=` 或 `settingsfile=` 覆盖 资料来源：[trafilatura/settings.py:1-30]()。
3. **自定义剪枝**：`prune_xpath` 支持字符串或字符串列表，在提取前删除指定子树 资料来源：[trafilatura/core.py:1-60]()。

### 社区关注的常见故障

- **LXML 兼容性**：5.2.0 起 `lxml.html.clean` 被拆分为独立包 `lxml_html_clean`，可能触发 `ImportError`，需单独安装 资料来源：[HISTORY.md:1-10]()。
- **表格输出异常**：HTML `<table><thead><tr><th>` 在 XML 输出中可能被改写为 `<row span="4"><cell role="head">`，结合 `--links` 选项时尤甚；2.1.0 已修复部分 table extraction bug 资料来源：[HISTORY.md:1-20]()。
- **版本与依赖更新**：在 2.0.0 → 2.1.0 期间存在发布节奏问题，社区曾呼吁及时升级 lxml 以规避 CVE 资料来源：[HISTORY.md:1-15]()。

### 贡献与扩展

`CONTRIBUTING.md` 指出，PR 须通过 `pip install trafilatura[dev]` 后运行 `pytest` 才能被接受；项目欢迎 bug 报告、文档改进与新功能提交 资料来源：[CONTRIBUTING.md:1-20]()。

## See Also

- [Core Python Functions](core-functions.md)
- [Configuration & Settings](configuration.md)
- [Output Formats](output-formats.md)
- [Downloads & Crawling](downloads.md)

---

<a id='page-2'></a>

## Text & Metadata Extraction Engine

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [CLI, Configuration & Known Issues](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [trafilatura/__init__.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/__init__.py)
- [trafilatura/core.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/core.py)
- [trafilatura/settings.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py)
- [trafilatura/metadata.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/metadata.py)
- [trafilatura/readability_lxml.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/readability_lxml.py)
- [trafilatura/xml.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/xml.py)
</details>

# Text & Metadata Extraction Engine

## 概述与设计目标

Trafilatura 的「文本与元数据提取引擎」是其核心子系统，负责将原始 HTML 内容转换为结构化的正文文本、文档元数据以及多格式输出（TXT、Markdown、CSV、JSON、HTML、XML、XML-TEI）。该引擎在包级别对外暴露的 API 由 [`trafilatura/__init__.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/__init__.py) 统一定义，主要包含 `extract`、`bare_extraction`、`extract_with_metadata`、`extract_metadata`、`baseline`、`html2txt`、`load_html`、`fetch_url`、`fetch_response` 等函数。

设计目标围绕三个核心原则：

1. **召回率与精确率的平衡**：通过 `precision` / `recall` / `fast` 三类预设参数控制启发式规则的强度，以适配不同的下游任务。参数列表详见 [`trafilatura/core.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/core.py) 的 docstring。
2. **可选元素的可配置化**：评论（`include_comments`）、表格（`include_tables`）、图片（`include_images`）、链接（`include_links`）、格式（`include_formatting`）等均以开关方式提供，便于在不同场景下裁剪输出。
3. **多格式输出与 TEI 校验**：默认输出 TXT，可通过 `output_format` 切换至 XML 或 XML-TEI，并对后者提供可选的 DTD/RelaxNG 校验逻辑（参考 [`trafilatura/xml.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/xml.py) 中的 `control_xml_output`）。

## 整体数据流与组件协作

提取引擎的内部数据流可概括为「HTML → DOM 树 → 启发式剪枝 → 主干文本/后备提取 → 元数据抽取 → 格式化输出」六个阶段。`bare_extraction` 是这一流程的中央调度函数（封装在 `_internal_extraction` 内部），其它高层 API（`extract`、`extract_with_metadata`）均在调用它之后做格式转换与字段筛选。

```mermaid
flowchart TD
    A[原始 HTML/filecontent] --> B[load_html 解析 lxml DOM]
    B --> C[prune_unwanted_nodes 剪枝]
    C --> D{主干启发式评估}
    D -- 通过 --> E[extract_metadata 元数据抽取]
    D -- 失败 --> F[后备提取: readability_lxml / justext / baseline]
    F --> E
    E --> G[Document 对象: body + commentsbody + meta]
    G --> H{output_format}
    H -- txt/markdown/csv/json --> I[文本/结构化输出]
    H -- xml/xmltei --> J[xml.py 构建 TEI 树]
    J --> K[control_xml_output 校验与序列化]
```

## 核心提取函数与配置体系

`extract()` 是最常用的入口，其参数集涵盖了内容形态（`filecontent` 或 `url`）、运行模式（`fast` / `favor_precision` / `favor_recall`）、输出形态（`output_format`、`include_*` 系列）以及外部配置覆盖（`settingsfile`、`config`、`options`）等多个维度。详细的参数含义可参考 [`trafilatura/core.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/core.py) 的 docstring。

`bare_extraction()` 返回结构化的 Python 字典（`Document` 类型），是 `extract` 与 `extract_with_metadata` 的共同前置步骤。`Document` 数据模型集中定义在 [`trafilatura/settings.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py) 中，字段涵盖正文段落（`body`）、评论段落（`commentsbody`）、标题、作者、日期、站点名、分类、标签、描述、许可证等元数据。下表列出了主要可调配置项：

| 配置项 | 默认值 | 作用 |
| --- | --- | --- |
| `min_output_size` | 由 settings 决定 | 低于该字节数直接判定为提取失败 |
| `min_extracted_size` | 由 settings 决定 | 启发式评估的最小有效段落长度 |
| `max_file_size` / `min_file_size` | 由 settings 决定 | 输入尺寸边界，防止异常输入 |
| `max_tree_size` | 由 settings 决定 | DOM 树规模上限，触发后备路径 |
| `include_tables` | True | 是否纳入 `<table>` 内容（见社区 #777、#794） |
| `include_links` | False | 是否保留链接（与表格处理存在交互） |
| `include_formatting` | False | 是否保留加粗、斜体等行内格式（XML 有意义） |
| `dedup` | False | 段落级去重开关 |

如果用户未显式传入，配置由 `_add_config` 与 `DEFAULT_CONFIG` 组合填充，详见 [`trafilatura/settings.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py)。

## 元数据抽取与后备路径

元数据抽取独立成模块，由 [`trafilatura/metadata.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/metadata.py) 负责。该模块通过预编译的 XPath（`TITLE_XPATHS`、`AUTHOR_XPATHS`、`CATEGORIES_XPATHS`、`TAGS_XPATHS` 等）扫描 `<meta>`、JSON-LD、`<title>`、microdata 等多种来源；日期字段则委托给 [htmldate](https://github.com/adbar/htmldate) 完成，作者字段会经过 `normalize_authors` 做标准化与去重。

当主干启发式评估结果不可信（例如段落过短、密度过低）时，引擎会按顺序回退到后备提取器：

- **readability_lxml**：基于文本密度与标签权重的打分机制，实现见 [`trafilatura/readability_lxml.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/readability_lxml.py)；
- **justext**：通过段落分类定位正文；
- **baseline**：最朴素的 `<p>` 聚合，作为兜底。

需要注意，自 1.12.0 起 baseline **不再作为后备提取器**（参见 `HISTORY.md` 中 1.12.0 条目），这一调整显著降低了误召回率。

## 输出格式与已知问题

输出层由 [`trafilatura/xml.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/xml.py) 统一处理 XML 与 TEI：先构建 `<doc>` / `<TEI>` 根节点，挂载正文与评论子树，再调用 `sanitize_tree`、`control_xml_output` 进行属性清洗与可选的 TEI 校验（启用 `tei_validation=True` 时）。非 XML 格式则走独立的文本与 Markdown 序列化路径。

社区中常见的几类问题与引擎直接相关：

- **依赖兼容性问题**：[Issue #532](https://github.com/adbar/trafilatura/issues/532) 报告 `lxml 5.2.0` 之后 `lxml.html.clean` 被剥离为独立包 `lxml_html_clean`，`HISTORY.md` 显示 1.7.0 已移除 `lxml.html.Cleaner` 依赖，2.1.0 进一步完成依赖升级。
- **表格与链接的交互**：[Issue #777](https://github.com/adbar/trafilatura/issues/777) 与 [Issue #794](https://github.com/adbar/trafilatura/issues/794) 指出 `include_tables=True` 与 `include_links=True` 同时启用时，`<table><thead><tr><th>` 等嵌套结构在 XML 输出中可能错位（`<row>` / `<cell role="head">`）。2.1.0 的发布说明中专门包含 "fix table extraction bugs"。
- **维护节奏**：[Issue #846](https://github.com/adbar/trafilatura/issues/846) 关注项目活跃度与 lxml CVE 升级，2.1.0 已将 lxml 升级至可缓解 CVE-2026-41066 的版本范围。

## 使用建议与失败模式

- 若需要最高吞吐，先尝试 `fast=True`；若结果过短或过空，去掉 `fast` 并启用后备路径。
- 抓取学术或新闻页面时，组合 `favor_recall=True` + `include_tables=True` 往往更稳妥。
- 启用 `include_links=True` 时务必对表格做后处理校验，避免嵌套表头被错误展平。
- 输入非 UTF-8 编码时，应使用 `fetch_response` 获取 `Response` 对象以便显式解码（`HISTORY.md` 中 1.7.0 引入）。
- 调整行为前优先复用 [`trafilatura/settings.py`](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py) 的字段定义，避免与 `Document` 数据模型脱节。

## See Also

- [Web Crawling & Downloads Module](https://github.com/adbar/trafilatura/wiki)
- [Configuration & Settings Reference](https://github.com/adbar/trafilatura/wiki)
- [Output Formats Guide (TXT / Markdown / XML / TEI / JSON / CSV)](https://github.com/adbar/trafilatura/wiki)
- [CLI Reference](https://github.com/adbar/trafilatura/wiki)

---

<a id='page-3'></a>

## Web Crawling, Downloads & URL Discovery

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [CLI, Configuration & Known Issues](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [trafilatura/__init__.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/__init__.py)
- [trafilatura/downloads.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/downloads.py)
- [trafilatura/sitemaps.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/sitemaps.py)
- [trafilatura/feeds.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/feeds.py)
- [trafilatura/spider.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/spider.py)
- [trafilatura/utils.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/utils.py)
- [trafilatura/deduplication.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/deduplication.py)
- [trafilatura/settings.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py)
- [trafilatura/core.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/core.py)
- [README.md](https://github.com/adbar/trafilatura/blob/main/README.md)
</details>

# Web Crawling, Downloads & URL Discovery

## 概述

Trafilatura 提供了一套面向研究型抓取的下载与发现栈，与正文提取能力相辅相成。该子系统负责从 Web 上“找到页面 → 下载响应 → 规范化 URL → 去重 → 进入下游提取流水线”，由五个协同模块构成：`downloads.py` 负责 HTTP 抓取与响应处理，`sitemaps.py` 与 `feeds.py` 负责链接发现，`spider.py` 负责站点级遍历，`utils.py` 与 `deduplication.py` 提供 URL 规范化、内容哈希与去重支持。

资料来源：[trafilatura/__init__.py:1-39]()、[README.md](README.md)

在公共 API 层面，`fetch_url`、`fetch_response`、`load_html` 是下载与解析的入口，而 `focused_crawler()` 则承担起多页面爬取的主控角色。

资料来源：[trafilatura/__init__.py:26-37]()

## URL 发现：Sitemaps 与 Feeds

URL 发现分为两类被动信号：

- **Sitemap 协议**：支持 TXT 与 XML 两种格式，允许从 `robots.txt` 中推断入口并批量提取候选 URL。`max_sitemaps` 参数用于限制遍历深度，避免巨型站点耗尽资源。
- **Web Feeds**：支持 ATOM、JSON Feed 与 RSS，读取 `feedparser` 解析后的条目字段，挑选出 `is_live_page()` 判定为有效的内容页。

两类入口均由 `URL_STORE` 这类去重结构管理，确保同一链接不会被重复入队。

资料来源：[trafilatura/spider.py:1-50]()、[HISTORY.md:1.12.x](HISTORY.md)

## 下载与响应处理

`downloads.py` 通过底层的 `urllib3` 自定义请求封装，并可选启用 `pycurl` 以获得更高吞吐。模块对外暴露两条主线 API：

| API | 用途 | 关键特性 |
| --- | --- | --- |
| `fetch_url(url)` | 同步抓取单个 URL，返回 HTML 字符串 | 自动重定向跟随、解码、UA 设置 |
| `fetch_response(url)` | 返回 `Response` 对象，保留 headers 与元数据 | 支持 HEAD 探测与 `is_live_page()` 检查 |
| `load_html(htmlstring)` | 将本地 HTML/`.gz` 字符串解析为 `lxml` 树 | 与下载输出无缝衔接，便于离线复现 |

`MAX_REDIRECTS` 与 `SLEEP_TIME` 等参数在配置文件中可调，前者限制重定向次数，后者控制礼貌性退避。

资料来源：[trafilatura/settings.py:1-80]()、[HISTORY.md:1.7.0](HISTORY.md)

## 站点级爬取：`spider.py`

爬取逻辑由 `focused_crawler()` 驱动，循环结构清晰：

```mermaid
flowchart TD
    A[homepage URL] --> B[probe_alternative_homepage]
    B --> C{是否可解析?}
    C -- 否 --> Z[结束]
    C -- 是 --> D[process_links 抽取候选]
    D --> E[URL_STORE 去重与入队]
    E --> F[crawl_page 抓取下一条]
    F --> G{达到 max_seen_urls?}
    G -- 否 --> F
    G -- 是 --> H[focused_crawler 返回 todo/known_links]
```

`focused_crawler()` 的关键参数包括 `max_seen_urls`、`max_known_urls`、`lang`、`rules`（`RobotFileParser`）以及 `prune_xpath`，分别控制访问上限、语言过滤、礼貌性策略与树级剪枝。返回值为 `(todo, known_links)`，便于后续迭代或断点续爬。

资料来源：[trafilatura/spider.py:1-100]()

## 去重、规范化与配置

下载与发现栈的去重由两层组成：

1. **URL 层**：`utils.py` 通过 `courlan` 的 `normalize_url()` 与 `validate_url()` 抹平跟踪参数与大小写差异；`URL_STORE.find_unvisited_urls()` 在爬取循环中按域名切片回填。
2. **内容层**：`deduplication.py` 计算段落级哈希，按 `min_duplcheck_size` 与 `max_repetitions` 阈值剔除重复片段，对 `--dedup` CLI 选项与 `deduplicate=True` 编程接口均生效。

`settings.py` 中 `_CONFIG_MAPPING` 统一管理 `SLEEP_TIME`、`MAX_REDIRECTS` 等网络相关字段，并支持用户自定义配置文件覆盖默认值，便于在大规模批量抓取时进行工程化调优。

资料来源：[trafilatura/settings.py:1-60]()、[trafilatura/core.py:1-80]()

## 常见失败模式与社区关注

社区反馈集中在两个方向：

- **依赖与发布节奏**：`lxml 5.2.0` 移除了 `lxml.html.clean`，社区 issue #532 要求安装独立的 `lxml_html_clean`。最新 2.1.0 版本已完成依赖升级，但部分旧部署需手动迁移。
- **维护活跃度**：issue #846 关注项目是否仍活跃；2.1.0 已通过 XSLT 扩展优化 XPath 性能，并修复了节点剪枝 `AttributeError`（#761）与图片/表格提取缺陷，建议用户升级以获得稳定性收益。

资料来源：[HISTORY.md:2.1.0](HISTORY.md)

## See Also

- [Core Extraction & Output Formats](Core-Extraction-and-Output-Formats.md)
- [Metadata Extraction](Metadata-Extraction.md)
- [CLI Usage](CLI-Usage.md)
- [Configuration & Settings](Configuration-and-Settings.md)

---

<a id='page-4'></a>

## CLI, Configuration & Known Issues

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Text & Metadata Extraction Engine](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [trafilatura/__init__.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/__init__.py)
- [trafilatura/cli.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/cli.py)
- [trafilatura/cli_utils.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/cli_utils.py)
- [trafilatura/settings.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py)
- [trafilatura/settings.cfg](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.cfg)
- [trafilatura/core.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/core.py)
- [trafilatura/metadata.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/metadata.py)
- [trafilatura/readability_lxml.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/readability_lxml.py)
- [HISTORY.md](https://github.com/adbar/trafilatura/blob/main/HISTORY.md)
- [README.md](https://github.com/adbar/trafilatura/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/adbar/trafilatura/blob/main/CONTRIBUTING.md)
</details>

# CLI、配置与已知问题

Trafilatura 提供三种使用入口：Python API、命令行工具（CLI）以及 R 绑定。本页聚焦于 CLI 的调用方式、配置机制以及社区中频繁出现的已知问题，旨在帮助用户快速定位参数、避免常见陷阱并理解项目的演进状态。

## 1. 项目当前状态

当前最新版本为 `2.1.0`（见 [trafilatura/__init__.py:11](https://github.com/adbar/trafilatura/blob/main/trafilatura/__init__.py)），按照 [HISTORY.md](https://github.com/adbar/trafilatura/blob/main/HISTORY.md) 的说明，此版本主要更新了依赖（特别是 `lxml`），并通过 XSLT 扩展优化了 XPath 性能。社区中曾出现 "项目是否已停止维护" 的讨论（参考 Issue #846），但 `2.1.0` 的发布表明维护工作仍在继续，只是发布节奏较缓。

> 资料来源：[trafilatura/__init__.py:11-12]()、[HISTORY.md: 2.1.0 条目]()

## 2. 命令行接口（CLI）

CLI 模块位于 [trafilatura/cli.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/cli.py)，对外暴露的核心函数包括 `main` 与 `parse_args`。其典型调用形式为：

```bash
trafilatura -u "https://example.com" -o output.txt --with-metadata
```

### 2.1 主要参数

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `--format` / `-f` | 输出格式：`txt`、`markdown`、`json`、`csv`、`html`、`xml`、`xmltei` | `txt` |
| `--precision` / `--recall` | 在精度与召回之间取舍 | 平衡模式 |
| `--no-comments` | 不提取评论 | 提取评论 |
| `--with-metadata` | 同时输出元数据 | 否 |
| `--links` | 保留链接 | 否 |
| `--images` | 保留图片（实验性） | 否 |
| `--tables` / `--no-tables` | 是否包含表格 | 是 |
| `--target-language` | 按 ISO 639-1 过滤语言 | 无 |
| `--config-file` | 指定自定义配置 | 使用默认 |

> 资料来源：[trafilatura/core.py: extract() 文档字符串]()

### 2.2 CLI 工作流程

```mermaid
flowchart LR
    A[用户输入 URL/文件] --> B[cli.py 解析参数]
    B --> C{输入类型}
    C -->|URL| D[downloads.fetch_url]
    C -->|文件| E[utils.load_html]
    D --> F[core.extract]
    E --> F
    F --> G[settings.cfg 合并配置]
    G --> H[输出到文件/stdout]
```

> 资料来源：[trafilatura/__init__.py:7-9]()、[trafilatura/cli.py]()

## 3. 配置体系

Trafilatura 的配置分为两层：Python `ConfigParser` 对象与外部 INI 配置文件。

### 3.1 `Settings` 类

[trafilatura/settings.py](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.py) 中定义的 `Settings` 数据类封装了所有可调参数，包括：

- **输出控制**：`output_format`、`fast`、`focus`、`comments`、`formatting`、`links`、`images`、`tables`
- **尺寸阈值**：`min_extracted_size`、`min_output_size`、`min_output_comm_size`、`min_extracted_comm_size`
- **去重**：`min_duplcheck_size`、`max_repetitions`
- **文件/树大小**：`max_file_size`、`min_file_size`、`max_tree_size`
- **元数据相关**：`with_metadata`、`only_with_metadata`、`tei_validation`、`date_params`、`author_blacklist`、`url_blacklist`

构造函数支持通过 `config=ConfigParser(...)` 直接注入外部配置，从而实现 INI 文件与代码传参的混合。

> 资料来源：[trafilatura/settings.py: 字段列表]()

### 3.2 默认配置文件

[trafilatura/settings.cfg](https://github.com/adbar/trafilatura/blob/main/trafilatura/settings.cfg) 是与包一同分发的默认配置。`Settings.__init__` 在未显式提供 `config` 参数时使用 `DEFAULT_CONFIG` 加载该文件。用户可复制并修改该文件后通过 `--config-file` 引用。

## 4. 已知问题与解决方案

以下问题在社区讨论中出现频率较高，使用前请留意。

### 4.1 `lxml` 兼容性问题

Issue #532 报告：`lxml 5.2.0` 起，`lxml.html.clean` 模块被拆分到独立包 `lxml_html_clean`，直接 import 会抛出 `ImportError`。`2.1.0` 版本已更新 `lxml` 依赖以规避该问题（见 [HISTORY.md: 2.1.0](https://github.com/adbar/trafilatura/blob/main/HISTORY.md)），升级到最新版本即可解决。

### 4.2 PyPI 发布延迟

Issue #813 指出 GitHub 上的修复未及时发布到 PyPI。建议通过 `pip install --upgrade trafilatura` 显式检查版本，确认环境运行的是 `2.1.0` 而非旧的 `2.0.0`。

### 4.3 表格输出错误

Issue #777 反映：在 HTML 格式化输出中，原生 `<thead>/<tr>/<th>` 结构被改写为 `<row span="4">` 与 `<cell role="head">`。这是 XML 输出规范（XSLT 转换）的有意行为，与 HTML 表格不等价。如需保留原始 HTML 表格，请改用 `--format html` 或关闭表格提取 `--no-tables`。

### 4.4 `--links` 标志破坏表格

Issue #794 报告：启用 `--links` 后某些维基百科数据表格出现结构错乱。`2.1.0` 的修复说明中提到 "Refine img src url and fix table extraction bugs"（见 [HISTORY.md](https://github.com/adbar/trafilatura/blob/main/HISTORY.md)），升级版本通常可解决；若仍存在，可结合 `--no-tables` 绕过。

### 4.5 节点剪枝 `AttributeError`

在某些情况下，调用 `prune_xpath` 会抛出 `AttributeError`。`2.1.0` 中由 @PLPeeters 提交的 #761 修复了此问题。资料来源：[HISTORY.md: 2.1.0 修复条目]()。

## 5. 测试与贡献

[CONTRIBUTING.md](https://github.com/adbar/trafilatura/blob/main/CONTRIBUTING.md) 指出，提交 Pull Request 前需运行 `pip install trafilatura[dev]` 安装开发依赖，并执行 `pytest`。`realworld_tests.py` 是针对真实网页的回归测试套件，是复现上述已知问题的重要工具。

---

## See Also

- [Core Python Functions](https://trafilatura.readthedocs.io/en/latest/corefunctions.html) — 深入理解 `extract`、`bare_extraction` 等 API
- [Installation Guide](https://trafilatura.readthedocs.io/en/latest/installation.html) — 包含可选依赖 `py3langid`、`htmldate` 的安装说明
- [Tutorials](https://trafilatura.readthedocs.io/en/latest/tutorials.html) — 实战案例与 Notebook
- [Project README](https://github.com/adbar/trafilatura/blob/main/README.md) — 特性总览与基准评测结果

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：adbar/trafilatura

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/adbar/trafilatura | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/adbar/trafilatura | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/adbar/trafilatura | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/adbar/trafilatura | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/adbar/trafilatura | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/adbar/trafilatura | release_recency=unknown

<!-- canonical_name: adbar/trafilatura; human_manual_source: deepwiki_human_wiki -->