~/utility/rag-web-crawler
RAG Web Crawler——网页转 Markdown 与文本切片
把公开网页抓成干净的 Markdown、纯文本和相互重叠的文本切片，每个切片带来源 URL 与字符偏移，可直接向量化用于 RAG。
RAG 数据
TypeScriptMozilla ReadabilityjsdomTurndown
全球
分类utility / RAG 数据
语言TypeScript
技术栈TypeScript, Mozilla Readability, jsdom, Turndown
市场全球
输出干净、RAG 就绪的 JSON
核心特性
每个页面输出干净的 Markdown 和纯文本，保留标题、列表、链接、代码块和简单表格
可直接向量化的切片：相互重叠，尽量在段落或句子边界断开，每个切片都有稳定的 id、来源 URL 与标题，以及用于引用的精确字符偏移
只取正文：菜单、页眉、页脚和侧边栏会被去掉，你指定的其他元素也可以用 CSS 选择器移除
在每个站点内跟随链接，最多五层，每个页面只抓一次
用搜索代替 URL：查询结果里的每个页面都像起始 URL 一样抓取（需要 Apify 付费计划）
默认遵守 robots.txt，对同一站点的请求保持礼貌的间隔
页面保持原文语言——英文、中文等——不做翻译
每个页面都有状态和错误码，每次运行都有汇总，包含各项计数和停止原因
应用场景
- 用文档和帮助中心页面搭建 RAG 聊天机器人的知识库
- 让 AI Agent 基于当下的网页内容作答，并能给出引用来源
- 把一批文章转成向量，用于语义搜索
- 按主题搜索，收集搜到的页面，并保留原文语言
- 定期刷新向量库：页面不变时，切片 id 也保持不变
- 通过 Apify 的 MCP 服务器，把网页以 Markdown 形式提供给 AI Agent
输入参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
startUrls | array | 可选 | 要抓取的公开网页 URL，最多 1,000 个 |
query | string | 可选 | 搜索查询，抓取其结果页面（需要 Apify 付费计划） |
queries | array | 可选 | 更多搜索查询，与 query 合并 |
maxResultsPerQuery | number | 可选 | 每个查询抓取的搜索结果数（默认 5，最多 50） |
maxPages | number | 可选 | 一次运行最多安排的不同页面数（默认 20，最多 1,000） |
maxDepth | number | 可选 | 在每个站点内跟随链接的层数（默认 0 = 只抓起始 URL，最多 5） |
maxConcurrency | number | 可选 | 同时处理的页面数（默认 3） |
maxSearchRequests | number | 可选 | 每次运行的搜索请求数，含重试（默认 10，0 = 不搜索） |
maxFetchRequests | number | 可选 | 每次运行的全部网络请求，含 robots.txt 与重试（默认 100） |
requestTimeoutSecs | number | 可选 | 每个请求的超时时间，单位秒（默认 30） |
maxResponseBytes | number | 可选 | 接受的最大页面响应（默认 2 MiB） |
maxContentChars | number | 可选 | 每个页面保留的最长文本，单位字符（默认 50,000） |
maxOutputBytes | number | 可选 | 每次运行的总输出量（默认 20 MiB） |
respectRobotsTxt | boolean | 可选 | 抓取前先检查每个站点的 robots.txt（默认开启） |
onlyMainContent | boolean | 可选 | 只保留页面正文（默认开启） |
removeSelectors | array | 可选 | 提取前要移除的元素的 CSS 选择器 |
chunkSize | number | 可选 | 切片长度，按字符而非 token 计（默认 1,000） |
chunkOverlap | number | 可选 | 相邻切片共享的字符数（默认 150） |
输出示例
一次真实运行中保存的一个页面，文本做了截断，五个切片只展示其中一个：
1{
2 "schemaVersion": "1.0",
3 "url": "https://www.w3.org/WAI/tutorials/tables/one-header/",
4 "title": "Tables with One Header",
5 "description": "Accessibility resources free online from the international standards organization: W3C Web Accessibility Initiative (WAI).",
6 "languageCode": "en",
7 "canonicalUrl": "https://www.w3.org/WAI/tutorials/tables/one-header/",
8 "markdown": "# Tables with One Header\n\nin [Tables Tutorial](https://www.w3.org/WAI/tutorials/tables/)\n\n## Overview\n\n…",
9 "text": "Tables with One Header\n\nin Tables Tutorial\n\nOverview\n\nThis page covers tables that have one simple header for rows or one simple header for columns. …",
10 "chunks": [
11 {
12 "id": "495cb4e58e13bbf9b5cdbe922f7ea652973ca4dfda61b952aaa021db045a450c",
13 "index": 0,
14 "text": "Tables with One Header\n\nin Tables Tutorial\n\nOverview\n\nThis page covers tables that have one simple header for rows or one simple header for columns. …",
15 "startChar": 0,
16 "endChar": 988,
17 "sourceUrl": "https://www.w3.org/WAI/tutorials/tables/one-header/",
18 "title": "Tables with One Header"
19 }
20 ],
21 "contentTruncated": false,
22 "sources": [],
23 "crawl": {
24 "depth": 0,
25 "httpStatusCode": 200,
26 "loadedAt": "2026-10-19T07:03:53.643Z",
27 "contentType": "text/html",
28 "renderingMode": "http",
29 "extractionMethod": "main"
30 }
31}
切片偏移按 text 中的 Unicode 码点计算。每次运行还会写入 REQUESTS（每个页面一条结果，带状态和错误码）和 OUTPUT（运行汇总，包含各项计数、停止原因和已收费的事件）。
使用建议
- 把
id用作向量库中的记录 ID。 页面和切片设置不变时，它在多次运行之间保持不变，所以定期运行时按id写入切片，会覆盖旧的而不是多出副本。 - 先从少量页面开始。 先检查目标页面的 Markdown，再调大
maxPages或maxDepth；相关链接框之类的残留内容可以用removeSelectors去掉。 - 把
REQUESTS和 Dataset 一起看。 运行成功时也可能有页面被跳过或失败，每一条都会说明原因。
常见问题
它和普通网页爬虫有什么不同？
你给它 URL 或搜索查询，不用写选择器。它把每个页面的正文保存为 Markdown 和纯文本，再切成可直接向量化的切片，每个切片都带页面的 URL、标题和精确的字符偏移，回答可以据此注明出处。
需要 API 密钥吗？
不需要任何外部 API 密钥，抓取和搜索都不需要。你需要一个 Apify 账户；通过 Apify 的 API 调用这个 Actor 时使用你的 Apify token。
能渲染 JavaScript 吗？
不能。它通过 HTTP 读取页面，所以需要 JavaScript 才能显示文字的页面可能会报 NO_CONTENT，或者内容不完整。建议先用几个目标页面试一试。
能读取哪些页面？
公开的 HTML、Markdown 和纯文本页面。登录、Cookie、付费墙、验证码、代理、PDF 和图片都不在范围内；内网地址和带凭证的 URL 会被拒绝。
抓取网站合法吗？
抓取公开的非个人数据一般是合法的，但网页内容往往受版权保护，有些网站也在条款中限制抓取。爬虫默认遵守 robots.txt；你需要为如何使用所收集的内容负责。