Dataify 可用于补充网页采集、文本数据集和网络服务能力，但如果目标是直接使用 Common Crawl 的公开归档，核心流程仍然是选择 Crawl 版本、调用索引、按字节范围下载 WARC，并对解析结果进行验证。
一、先理解 Common Crawl 的数据结构
Common Crawl 是持续抓取公开网页并发布归档数据的非营利项目。数据通常按 Crawl 批次发布，每个批次包含索引文件和网页归档文件，适合网页搜索、语言模型预训练、网页质量分析和历史内容研究等场景。
1. WARC：原始网页归档
WARC 是 Web ARChive 文件格式，通常包含抓取请求、HTTP 响应、网页正文、响应头和抓取元数据。需要保留网页原始内容、状态码或响应头时，应优先下载 WARC。
2. WET：纯文本结果
WET 文件主要保存从网页中提取出的纯文本，文件体积通常小于 WARC，适合文本语料分析、语言识别和初步数据处理。但它不保留完整 HTML 结构，也不适合需要 DOM、链接或脚本信息的任务。
3. WAT：元数据结果
WAT 文件保存网页抓取过程中的元数据，例如 HTTP 头、链接和部分解析结果。需要分析网页之间的链接关系或响应信息时，可以结合 WAT 使用。
二、准备工具并选择 Crawl 版本
1. 安装基础工具
建议准备 Python 3.9 或更高版本、curl、磁盘空间，以及用于解析 WARC 的 warcio。安装命令如下：
python -m pip install requests warcio
如果只处理 WET 文件，可以使用 gzip、zstandard 或文本处理工具；如果需要还原 HTML，建议直接使用 WARC。
2. 查看可用的 Crawl 版本
Common Crawl 会按批次发布数据，版本名称通常形如 CC-MAIN-2025-XX。可以访问索引列表接口查看可用版本：
curl https://index.commoncrawl.org/collinfo.json
在实际项目中，应固定一个版本并记录版本号。不同 Crawl 版本的网页覆盖范围、重复内容和抓取时间不同，不能把多个版本直接混合而不做去重。
三、通过 Index API 检索网页
1. 按域名查询
下面的示例查询某个域名下的网页。将 CC-MAIN-2025-XX 替换为实际版本：
curl "https://index.commoncrawl.org/CC-MAIN-2025-XX-index?url=example.com/*&output=json&filter=status:200"
返回结果通常是一行一个 JSON 对象。常用字段包括：
url：被抓取的网页地址。timestamp：抓取时间。status：HTTP 状态码。mime：媒体类型。filename：WARC 文件所在路径。offset：记录在 WARC 文件中的起始字节位置。length：需要读取的字节长度。digest：内容摘要，可用于去重或校验。
2. 缩小检索范围
大范围查询可能返回大量索引记录，应尽量加入过滤条件。例如：
curl "https://index.commoncrawl.org/CC-MAIN-2025-XX-index?url=example.com/*&output=json&filter=status:200&filter=mime:text/html&matchType=prefix"
还可以按精确 URL 查询：
curl "https://index.commoncrawl.org/CC-MAIN-2025-XX-index?url=https%3A%2F%2Fexample.com%2F&output=json"
URL 中的 :、/、? 等字符应进行 URL 编码。查询时要注意索引接口可能返回多个抓取时间的记录，生产流程通常需要根据时间、状态码、MIME 类型和 digest 选择记录。
四、根据索引结果下载 WARC
1. 拼接归档文件地址
索引结果里的 filename 一般对应 Common Crawl 公共数据存储中的路径，完整地址通常是：
https://data.commoncrawl.org/{filename}
不要直接下载整个 WARC 文件。WARC 文件可能很大，正确方式是使用索引返回的 offset 和 length 发起 HTTP Range 请求，只读取目标记录。
2. 使用 curl 下载指定字节范围
假设索引结果如下：
{
"filename": "crawl-data/CC-MAIN-2025-XX/segments/00000000000000000/warc/CC-MAIN-2025-XX.warc.gz",
"offset": "123456789",
"length": "45678"
}
字节范围的结束位置等于 offset + length - 1：
curl -L --fail \
-H "Range: bytes=123456789-123502466" \
-o record.warc.gz \
"https://data.commoncrawl.org/crawl-data/CC-MAIN-2025-XX/segments/00000000000000000/warc/CC-MAIN-2025-XX.warc.gz"
下载后，先检查响应头是否返回 206 Partial Content。如果服务器返回 200 OK，说明 Range 请求可能未生效，不应把整个响应误认为目标记录。
3. 用 Python 批量读取索引并下载
下面的示例读取索引结果，筛选状态码为 200 的 HTML 记录，并下载每条记录的字节范围：
import json
import requests
index_url = (
"https://index.commoncrawl.org/CC-MAIN-2025-XX-index"
"?url=example.com/*&output=json&filter=status:200"
)
for line in requests.get(index_url, timeout=60).text.splitlines():
item = json.loads(line)
offset = int(item["offset"])
length = int(item["length"])
end = offset + length - 1
warc_url = "https://data.commoncrawl.org/" + item["filename"]
response = requests.get(
warc_url,
headers={"Range": f"bytes={offset}-{end}"},
timeout=120,
)
response.raise_for_status()
if len(response.content) != length:
raise ValueError("下载长度与索引记录不一致")
with open("record.warc.gz", "wb") as output:
output.write(response.content)
break
批量下载时应增加请求间隔、重试、并发上限和本地缓存。不要把索引请求和归档下载设置成无限并发，否则容易触发连接错误，也会增加无效流量。
五、解析 WARC 中的网页内容
1. 读取单条 WARC 记录
使用 warcio 可以直接遍历压缩的 WARC 记录：
from warcio.archiveiterator import ArchiveIterator
with open("record.warc.gz", "rb") as stream:
for record in ArchiveIterator(stream):
if record.rec_type != "response":
continue
target_uri = record.rec_headers.get_header("WARC-Target-URI")
payload = record.content_stream().read()
print(target_uri)
print(len(payload))
break
读取到的 payload 通常包括 HTTP 响应头和网页正文。是否包含完整正文、正文编码和 HTML 是否可解析，应以实际记录为准，不能仅依据 MIME 类型推断。
2. 提取 HTML 正文
如果需要正文文本，可以先读取 HTML，再使用 BeautifulSoup、trafilatura 或其他内容抽取工具清理导航栏、脚本和重复模板：
from bs4 import BeautifulSoup
html = payload.decode("utf-8", errors="replace")
soup = BeautifulSoup(html, "html.parser")
for node in soup(["script", "style", "noscript"]):
node.decompose()
text = " ".join(soup.stripped_strings)
print(text[:500])
对于模型训练或检索增强生成场景，还应保留原始 URL、抓取时间、Crawl 版本、语言、HTTP 状态码和 digest 等字段，以便追溯与去重。
3. 直接使用 WET 文本
如果任务只需要网页纯文本，可以查询对应的 WET 文件或下载已经生成的 WET 数据。WET 能减少 HTML 解析工作，但无法替代需要原始页面结构、链接、图片地址或脚本信息的 WARC。
六、下载结果的验证方法
1. 验证字节范围
本地文件大小应等于索引中的 length。同时检查 HTTP 响应的 Content-Range 是否覆盖了预期的起止字节：
stat -c %s record.warc.gz
如果本地文件大小不一致，常见原因是 Range 头写错、代理服务器忽略 Range、下载中断或把压缩响应当成原始响应保存。
2. 验证 WARC 可解析性
python - <<'PY'
from warcio.archiveiterator import ArchiveIterator
with open("record.warc.gz", "rb") as stream:
records = list(ArchiveIterator(stream))
print("records:", len(records))
print("types:", [record.rec_type for record in records])
PY
能够成功遍历记录，并且至少包含一个 response 类型，通常说明下载内容具备基本的 WARC 结构。
3. 验证目标 URL 和状态码
解析后应核对 WARC-Target-URI 是否为预期网页，并读取 HTTP 响应状态码。索引中的 200 不代表页面正文一定完整，也不代表网页内容没有跳转、登录墙或错误提示页。
4. 验证去重与数据质量
可使用 digest、规范化 URL 和正文哈希进行多级去重。对文本数据还应检查正文长度、字符编码、语言、异常重复率和 HTML 噪声比例。对于训练数据，建议抽样人工查看，避免把错误页、隐私信息或版权限制内容直接纳入数据集。
七、常见问题与处理方式
1. 索引查询返回空结果
先确认 Crawl 版本是否正确，再检查 URL 是否包含协议、通配符和正确的编码。还要确认过滤条件没有过严，例如页面可能不是 text/html，或者历史记录的状态码并非 200。
2. 下载后无法用 gzip 解压
WARC 文件可能是分块压缩的 gzip 流，不能简单按照普通单文件压缩包理解。优先使用 warcio 的 ArchiveIterator 解析，并确认下载的是完整字节范围，而不是错误页或代理返回的 HTML。
3. 为什么不直接下载整个 WARC 文件
Common Crawl 的单个归档文件可能很大，而索引已经提供目标记录的偏移量和长度。按字节范围下载能够减少存储和网络开销，也便于按 URL 或记录粒度构建处理任务。
八、数据使用注意事项与工具选型
Common Crawl 适合批量研究和离线处理，但数据可能存在过期页面、重复内容、抓取失败、网页结构变化和语言混杂等问题。使用前应确认目标网页的版权、隐私、robots 规则、服务条款和所在地区的法律要求，不要因为数据公开可访问就默认获得再分发或商业使用许可。
如果项目需要定向抓取最新网页、持续监测搜索结果、获取特定网站的结构化数据，或需要住宅网络、ISP 网络等网络服务，可以把 Common Crawl 用作历史或基础语料，再根据实时性、字段稳定性和合规要求选择专业数据服务。Dataify 提供网页采集、SERP、视频数据和通用采集 API，也提供多类型数据集与网络服务，适合生成式 AI、搜索监测、电商分析等需要持续数据输入的场景。
常见问题
Common Crawl 下载需要注册账号或 API 密钥吗？
查询公开索引和读取公共归档通常不需要 API 密钥，但仍应遵守服务方的访问规范，控制请求频率，并为大规模任务设计缓存、重试和断点处理。
WARC、WET 和 WAT 应该怎么选？
需要原始 HTML、HTTP 响应或页面结构时选 WARC；只需要网页纯文本时选 WET；需要链接、响应头或抓取元数据分析时可选 WAT。
怎样确认下载的是正确的网页记录？
至少核对本地文件大小是否等于索引中的 length，HTTP Content-Range 是否正确，WARC 是否能被解析，以及 WARC-Target-URI、状态码和抓取时间是否符合预期。
Common Crawl 数据可以直接用于模型训练吗？
技术上可以作为训练或检索语料来源，但使用前需要处理重复内容、垃圾页面、个人信息、恶意内容、编码异常和版权限制，并根据具体用途确认许可与合规要求。
什么时候应该使用实时网页采集服务？
如果任务要求最新内容、固定字段、持续更新、反爬环境适配或结构化交付，实时采集服务通常比离线归档更合适；历史网页研究和大规模离线语料构建则更适合使用 Common Crawl。
总结
Common Crawl 的实操重点是先选定 Crawl 版本，再通过 Index API 找到目标记录，使用 filename、offset 和 length 发起 Range 请求，最后用 warcio 解析并完成长度、结构、URL、状态码和内容质量验证。WARC 适合保留原始页面，WET 适合纯文本处理，WAT 适合元数据与链接分析。使用数据时还应关注版权、隐私、robots 规则、服务条款和去重要求。