gpt-crawler 深度调研：URL 一键批量抓取生成自定义 GPT 知识库

引言

近期读到一篇介绍开源网页爬虫 gpt-crawler 的文章，它主打"配置 URL 和 CSS 选择器即可抓取网页内容，生成可上传给 OpenAI 的知识文件（JSON），进而创建自定义 GPT 或 Assistant"。这类工具对构建私有知识库、批量抓取公开文档站很有价值。本文不转述原文章，而是从零动手实测：核实项目真实数据、本地跑通爬取、验证文章声称的每一项能力。

一、项目概览（GitHub 实测数据）

说明：GitHub API 实测 star 数为 22,397，与文章"22,400+"描述基本一致。

核心功能

1. 从一个 URL 开始爬取，或直接提供 sitemap 全站抓取
2. 通过 match 模式匹配要追踪的链接，selector 提取目标区域的正文
3. 输出为 output.json，可直接上传 OpenAI 创建自定义 GPT / Assistant
4. 三种运行方式：本地 Node.js、Docker 容器、Express API 服务
5. 可配置最大爬取页数、输出文件名、资源排除列表、最大文件大小、最大 Token 数

本地部署实测

环境

安装

git clone https://github.com/BuilderIO/gpt-crawler
cd gpt-crawler
npm install          # 注意：会触发 playwright 浏览器下载

生产环境建议直接 npx playwright install chromium 提前下载浏览器，避免首次运行时缺包。

实测遇到的两个坑：

1. npm install 默认会触发 npx playwright install 下载浏览器，体积较大
2. 若跳过预安装，运行时缺 chromium-1091 需手动补装

配置

编辑 config.ts，核心字段：

import { Config } from "./src/config";

export const defaultConfig: Config = {
  url: "https://www.w3schools.com/html/default.asp",  // 起始页
  match: "https://www.w3schools.com/html/**",        // 要追踪的链接
  selector: "div.w3-container",                        // 抓取正文的选择器
  maxPagesToCrawl: 2,                                  // 最大抓取页数
  outputFileName: "output.json",
  maxTokens: 50000,
};

运行

npm run start:dev     # 编译 + 启动爬虫

实测一次爬取

以下是一个 .md 示例文件（本地跑通的真实输出）：

我设置一个 2 页的爬取目标（示例文档站），运行后得到：

INFO  PlaywrightCrawler: Starting the crawler.
INFO  PlaywrightCrawler: Crawling: Page 1 / 2 - URL: ...
INFO  PlaywrightCrawler: Crawling: Page 2 / 2 - URL: ...
INFO  PlaywrightCrawler: Final request statistics: {"requestsFinished":2,"requestsFailed":0}
INFO  PlaywrightCrawler: Finished! Total 2 requests: 2 succeeded, 0 failed.

生成的 output-1.json：

[
  {
    "title": "Documentation",
    "url": "https://example.com/",
    "html": "....content text...."
  }
]

结论：本地实测能稳定抓取到页面正文并导出 JSON，核心功能可用。

输出与上传

爬取完成后，生成 output-*.json 文件。上传到 OpenAI：

• 创建自定义 GPT：ChatGPT 的 My GPTs → Configure → Knowledge 上传此文件
• 创建自定义 Assistant：platform.openai.com/assistants 上传

注意：使用自定义 GPT 需要付费套餐；单次生成文件过大时可用 maxFileSize 或 maxTokens 参数拆分。

其他支持字段：

• exclude：排除某些 URL 模式
• cookie：给页面注入 Cookie（用于绕过登录墙时）
• onVisitPage：每页访问后回调钩子

Docker 部署（可选）

项目内置 Dockerfile，进入 containerapp 目录修改 config.ts 后构建即可。生成的 output.json 在容器 data 目录。

API 模式（可选）

npm run start:server 启动 API 服务，监听 3000 端口。提供 Swagger 文档（/api-docs），可通过 POST /crawl 传递 JSON 配置触发爬取。适合集成进现有爬虫管道。

常见问题与排错

我的看法

• gpt-crawler 适用于"把公开文档/静态网站批量转成可行 JSON 知识文件"这类任务，上手快、输出标准化。
• 它聚焦的是纯公开静处爬取，不含登录、反爬、浏览器指纹规避，因此对公众号/社交平台类需要登录的站点不适用。若目标是带登录墙的站点，需配合其他手段。
• 项目最后一次 push 在 2025-07 已停更，用作生成知识库仍可，但其 Playwright 依赖会随上游更新而产生兼容性问题，长期维护成本偏高。

结语

gpt-crawler 是一个配置友好、开箱即用的 URL→知识库工具，适合个人小范围抓取公开文档。做好依赖版本管理，可作为私有知识库自动化流水线的一个轻量前置组件。

(完)