GPT-Crawler：爬取网站一键生成你的专属 GPT
想做一个"懂你们公司文档/产品"的 AI 助手？传统做法是手动把网页内容复制粘贴喂给 ChatGPT，但一个文档站动辄几百个页面，根本复制不过来。BuilderIO 的 gpt-crawler 正是为此而生——配置一个起始 URL 和 CSS 选择器，它就用 Playwright 无头浏览器自动爬取整站、提取每页正文、聚合成一个知识文件，上传到 OpenAI 即可得到一个专属的 Custom GPT 或 Assistant。本文介绍它的原理、配置、三种运行方式与上传流程。参考 GitHub 仓库。
1、概述：gpt-crawler 是什么
gpt-crawler 是一个 Node.js 工具，目标是"爬取网站生成知识文件，用于创建你自己的自定义 GPT"。它底层基于 crawlee + Playwright 无头浏览器，因此能爬取 JS 渲染的动态文档站（如 VuePress、Docusaurus），把分散在几百个页面的文档聚合成一个可直接喂给 GPT 的文件。
能力 说明
--------------------------------------------------------------------
自动爬取 从起始 URL 出发，按 match 模式递归爬取整站
正文提取 selector 提取每页正文 innerText，过滤导航/侧边栏/广告
JS 渲染 crawlee + Playwright 无头浏览器，能爬 SPA 动态文档站
体积控制 maxPages / maxFileSize / maxTokens 三重限制
多种运行 本地 npm start / Docker 容器 / Express API 服务核心实现（为什么用它）：
1. 自动递归爬整站，省去手动复制每个网页的低效劳动
2. selector 精准提取正文，过滤掉导航、侧边栏、广告等噪音
3. 基于 Playwright，能爬 JS 动态渲染的文档站（普通 HTTP 请求爬不了 SPA）
4. 输出文件直接对接 OpenAI，上传即可创建 Custom GPT 或 Assistant
2、环境准备与安装
gpt-crawler 需要 Node.js 16 及以上。克隆仓库后装依赖即可——npm i 会自动触发 Playwright 浏览器的安装（package.json 的 preinstall 脚本）。
# 前置：Node.js >= 16
git clone https://github.com/builderio/gpt-crawler
cd gpt-crawler
npm i # preinstall 会自动执行 npx playwright install 安装无头浏览器核心实现：
1. 确保本机 Node.js >= 16，否则 Playwright/crawlee 可能跑不起来
2. clone 仓库后 npm i 安装依赖
3. 无需手动装浏览器：preinstall 脚本会自动 npx playwright install
4. 如果浏览器下载失败（网络问题），可单独执行 npx playwright install
3、核心配置 config.ts
爬什么、怎么爬、爬多少，全由 config.ts 决定。最关键的是 url（起点）、match（范围）、selector（正文容器）、maxPagesToCrawl（页数上限）四项：
// config.ts
export const defaultConfig: Config = {
url: "https://www.builder.io/c/docs/developers", // 起始爬取 URL
match: "https://www.builder.io/c/docs/**", // 后续爬取的链接匹配模式（glob）
selector: ".docs-builder-container", // 提取正文的 CSS 选择器
maxPagesToCrawl: 50, // 最大爬取页数
outputFileName: "output.json", // 输出文件名
};
// 完整可选配置
type Config = {
url: string; // 起始 URL（若有 sitemap 则改用 sitemap 全量爬）
match: string; // 链接匹配模式，决定爬哪些页面
selector: string; // 提取 innerText 的 CSS 选择器
maxPagesToCrawl: number; // 最大爬取页数
outputFileName: string; // 输出文件名
resourceExclusions?: string[]; // 排除的资源扩展名（图片/视频/字体…）
maxFileSize?: number; // 输出文件最大体积（MB）
maxTokens?: number; // 输出最大 token 数（配合 gpt-tokenizer 精确切分）
};核心实现：
1. url 是爬取起点；若站点提供 sitemap，会自动改用 sitemap 全量爬取所有页面
2. match 用 glob 模式限定范围，** 匹配任意层级，避免爬到站外或无关页面
3. selector 决定提取哪部分正文，是去噪的关键（见第 5 节）
4. maxPagesToCrawl / maxFileSize / maxTokens 三重保险，防止输出文件超 OpenAI 上传限制
4、本地运行爬取
配置好后，一条命令启动爬取。完成后会在项目根目录生成 output.json，这就是要上传到 OpenAI 的知识文件。
npm start
# 执行流程：构建 TS → 启动 Playwright → 按 url/match 递归爬取
# → selector 提取正文 → 汇总写入根目录 output.json
# 爬取过程中终端会打印进度；结束即可在项目根目录找到 output.json核心实现：
1. npm start 等价于 start:dev，会先 tsc 构建再运行
2. 爬取时 Playwright 以无头浏览器方式打开每个页面，等待渲染后提取 selector 内容
3. 终端实时打印已爬页数，便于观察进度
4. 最终产物是 output.json，结构符合 OpenAI 知识文件要求，可直接上传
5、selector 与 match：精准控制爬取范围
config.ts 里有两项最容易写错：selector 决定"每页提取什么"，match 决定"爬哪些页"。写对这两项，是产出高质量知识文件的关键。
// selector：如何确定？打开目标页面 → F12 开发者工具 → 选中正文容器 → 看 class
// 常见正文选择器：article / main / .markdown-body / .docs-content
// 例：爬 Vue 官方文档
export const defaultConfig: Config = {
url: "https://vuejs.org/guide/introduction.html",
match: "https://vuejs.org/guide/**", // 只爬 /guide/ 下的页面，** 匹配任意层级
selector: ".content", // Vue 文档正文容器
maxPagesToCrawl: 100,
outputFileName: "output.json",
};
// 常见坑：
// 1. selector 太宽（如 body）：会把导航、广告、页脚全收进来，污染知识
// 2. match 不加 **：只爬单页，达不到整站效果
// 3. match 不限域名：可能爬到外链站，污染数据且浪费配额核心实现：
1. 确定 selector：F12 选中正文区块，复制它的 class/标签作为选择器
2. selector 宁窄勿宽：用具体的 .content / article，避免用 body 收进导航和广告
3. match 用 "域名/路径/**" 限定爬取范围，** 匹配任意层级子路径
4. 不确定时先设 maxPagesToCrawl: 5 小范围试爬，检查 output.json 内容再放大
6、替代运行方式：Docker 与 API
除了本地 npm start，gpt-crawler 还提供两种运行方式，分别适合"环境隔离"和"集成进后端服务"。
// ① Docker 容器化运行（环境隔离）
// 进入 containerapp 目录，改其中的 config.ts，按其 README 构建运行
cd containerapp
// 构建运行后，output.json 生成在 data 文件夹（注意 containerapp 的 outputFileName 已适配容器）
// ② 作为 API 服务运行（适合集成进产品）
npm run start:server // 启动 Express 服务，默认端口 3000
// 接口：
// POST /crawl body 是 config json，触发一次爬取
// GET /api-docs Swagger 文档（由 swagger-ui-express 提供）
// POST /crawl 请求体示例：
// {
// "url": "https://example.com/docs",
// "match": "https://example.com/docs/**",
// "selector": "main",
// "maxPagesToCrawl": 20,
// "outputFileName": "output.json"
// }核心实现：
1. Docker：进 containerapp 目录改 config.ts，适合不想污染本机 Node 环境的场景
2. API 服务：npm run start:server 启动 Express，端口 3000
3. POST /crawl 接收 config json 动态触发爬取，便于"用户填表 → 后端爬取"的产品化
4. /api-docs 由 Swagger 提供，方便联调；可用 .env 覆盖端口等配置
7、上传 OpenAI：创建 GPT / Assistant
拿到 output.json 后，上传到 OpenAI 就能生成专属 AI。两条路线：Custom GPT（UI 分享用）和 Assistant（API 集成用）。文件太大时用 maxFileSize / maxTokens 处理。
// ① 创建 Custom GPT（UI 访问，可分享给他人；需付费 ChatGPT 套餐）
// 1. 打开 https://chat.openai.com/
// 2. 左下角点你的名字 → My GPTs → Create a GPT
// 3. 进入 Configure 标签 → Knowledge → Upload a file → 上传 output.json
// 4. 文件过大报错？用 maxFileSize 拆成多个文件分次上传，
// 或用 maxTokens 配合 gpt-tokenizer 按 token 裁剪体积
// ② 创建 Assistant（API 访问，可集成进你自己的产品）
// 1. 打开 https://platform.openai.com/assistants
// 2. 点击 + Create
// 3. 选择 upload，上传 output.json
// 4. 拿到 assistant_id，即可在代码里调用 Assistants API 实现"专属客服"核心实现：
1. Custom GPT：UI 访问、可分享，适合内部使用或公开分享，需付费 ChatGPT 套餐
2. Assistant：API 访问，适合集成进自家产品（如"文档客服"Bot）
3. 上传报"文件过大"时，maxFileSize 拆分成多个文件分次上传
4. 或用 maxTokens 配合 gpt-tokenizer 按 token 精确裁剪，保证不超模型上下文预算
8、总结
gpt-crawler 把"让 GPT 学会一个网站"这件事自动化了：配置 url/match/selector 三件套，一行命令爬整站、提取正文、生成知识文件，上传即得专属 AI。
关键要点：
- 本质：crawlee + Playwright 无头浏览器爬取整站，提取正文聚合为 output.json
- 安装：Node>=16，clone + npm i（自动装 Playwright 浏览器）
- 配置：url 起点、match 范围（glob **）、selector 正文、maxPagesToCrawl 上限
- 运行：本地 npm start / Docker 容器 / Express API（POST /crawl）三选一
- 上传：Custom GPT（UI/分享，需付费）或 Assistant（API/集成）；大文件用 maxFileSize/maxTokens
- 诀窍：selector 宁窄勿宽去噪、match 限定域名防外爬、先小批量试爬再放大
对于想快速搭建"产品文档客服""内部知识助手""私有化问答 Bot"的开发者而言，gpt-crawler"爬取 → 聚合 → 上传"的三步工作流是非常实用的起点——它把最繁琐的"数据收集与清洗"自动化了，让你把精力放在 GPT 的提示词调优和业务集成上。配合它的 API 模式，甚至能做出"用户输入网址、实时生成专属助手"的 SaaS 产品。把 selector/match 的调试技巧掌握好，再大的文档站也能高效地转化为 GPT 的专属知识。
