企业官网建设流程全解析

x-crawl 快速指南：用自然语言替代写死的 CSS 选择器，5 分钟跑通第一个采集任务

【免费下载链接】x-crawlFlexible Node.js AI-assisted crawler library项目地址: https://gitcode.com/gh_mirrors/xc/x-crawl

上周四你要上线一个竞品监控脚本，站点悄悄改版，前一天还生效的一二十个 CSS 选择器集体失效——这大概是维护爬虫最耗人的时刻。x-crawl 是一个灵活的 Node.js AI 辅助爬虫库：爬取部分不依赖 AI 也能独立工作，AI 部分则让你用一句话描述需要的数据，由模型从 HTML 中定位元素。适合需要采集动态页面、接口数据或图片，又不想长期维护选择器的开发者。

选择器"寿命"问题：x-crawl 值得试的原因

传统做法的代价藏在维护里：每想采集一个字段，就要在 DOM 里找一个稳定的选择器，再单独写解析代码；站点框架会给 class 名做混淆（官方示例的页面里满是 c1yo0219 这类命名），一次改版就全部作废，你得重新翻 DOM 找新名字。

x-crawl 的解法是把"找数据"从手写代码挪到模型侧：AI 应用实例提供parseElements方法，传入 HTML 片段和一句需求描述，它返回元素列表。你写的是"数据的含义"，而不是"数据的位置"。

收益可以验证：面对 class 名混淆的页面，你不用翻 DOM 找稳定选择器；站点再改版时，多数情况下只需调整那句话，而不是逐字段修选择器。

核心能力拆解：AI 元素提取与反封禁的三块拼图

parseElements 用法：让 AI 做 HTML 元素提取

AI 应用实例上的一个方法：传入 HTML 和一句自然语言需求，返回匹配的元素列表。它解决的具体麻烦：想拿"图片链接"这类字段，传统做法要把选择器写死，结构一变就得重写。关键实现思路：通过createCrawlOpenAI/createCrawlOllama分别接入 OpenAI 或本地 Ollama，把 HTML 交给大模型做语义解析，返回的 elements 可以直接转成 URL 数组传给crawlFile批量落盘。效果与边界：对"结构常变"的页面多数情况能直接出结果；但 HTML 越大 token 越多，官方 README 也建议只传目标容器的 HTML。

crawlPage、crawlData、crawlFile 配置：一套 API 覆盖页面、接口与文件

crawlPage（动态页面）、crawlHTML（静态页面）、crawlData（JSON 接口）、crawlFile（图片/PDF）四个方法成体系，且都支持从"一个 URL 字符串"到进阶配置的同一套四级写法。它解决的具体麻烦：传统项目里不同目标类型常要换不同库，重试、间隔、代理都要自己造轮子。关键实现思路：内部封装 puppeteer（动态页）与 HTTP 请求（数据、文件），targets 参数支持混合数组——统一默认配置，单个目标可单独覆盖。效果与边界：无头浏览器开销不小，纯接口数据建议直接走crawlData；文件下载传storeDirs即可批量落盘。

反封禁配置：设备指纹、轮换代理与失败重试

三组可叠加的设置：enableRandomFingerprint随机设备指纹、轮换代理、maxRetry失败重试。它解决的具体麻烦：同一 IP 与 UA 短时间高频请求，容易被限流或拦截。关键实现思路：指纹随机生成 UA 与平台组合；代理按switchByErrorCount错误次数或switchByHttpStatus状态码（如 401/403）自动切换；重试会等当前一轮目标跑完再补发。效果与边界：批量采集场景价值最大，低频单次请求用默认配置即可。

🚀 5 分钟快速上手：从安装到跑通第一个采集任务

第 1 步：安装

npm install x-crawl

这一步在做什么：从 npm 安装 x-crawl，要求 Node 18+；想读源码和完整示例，可克隆仓库git clone https://gitcode.com/gh_mirrors/xc/x-crawl。

第 2 步：跑通第一次爬取

import { createCrawl } from 'x-crawl' const crawlApp = createCrawl() crawlApp .crawlPage('https://www.example.com') .then((res) => { console.log(res.data) res.data.browser.close() })

这一步在做什么：启动浏览器打开目标页，res.data里拿到 page 与 browser 对象；用完记得browser.close()释放进程。

第 3 步：接上 AI 解析

import { createCrawlOpenAI } from 'x-crawl' const aiApp = createCrawlOpenAI({ clientOptions: { apiKey: process.env['OPENAI_API_KEY'] } }) const res = await aiApp.parseElements(html, '获取图片链接, 并去重')

这一步在做什么：AI 应用连上 OpenAI（本地运行就换createCrawlOllama），把 HTML 和一句话交给parseElements，拿回结构化元素。

第 4 步：批量落盘文件

await crawlApp.crawlFile({ targets: res.elements.map((item) => item.src), storeDirs: './upload' })

这一步在做什么：crawlFile把所有图片 URL 依次下载到./upload目录并返回下载结果。

图：上面 4 步串起来运行，浏览器打开页面，AI 提取图片链接，crawlFile 依次落盘

两个真实落地案例：房源图片采集与多接口监控

案例一：批量采集高评分度假屋的房源图片

业务目标：从度假屋列表页把"高评分"板块的房源图片批量保存到本地。

实现思路：crawlPage打开页面 → 等待列表容器加载完成 → 把容器 HTML 交给parseElements拿出去重后的图片链接 →crawlFile落盘。

关键代码：

import { createCrawl, createCrawlOpenAI } from 'x-crawl' const crawlApp = createCrawl({ maxRetry: 3, intervalTime: { max: 2000, min: 1000 } }) const aiApp = createCrawlOpenAI({ clientOptions: { apiKey: process.env['OPENAI_API_KEY'] } }) crawlApp .crawlPage('https://www.example.cn/s/select_homes') .then(async (res) => { const { page, browser } = res.data const sel = '[data-tracking-id="TOP_REVIEWED_LISTINGS"]' await page.waitForSelector(sel) const html = await page.$eval(sel, (el) => el.innerHTML) const src = await aiApp.parseElements(html, '获取图片链接, 不要source里面的, 并去重') browser.close() return crawlApp.crawlFile({ targets: src.elements.map((item) => item.src), storeDirs: './upload' }) })

图：上面代码的运行结果，高评分列表的房源图片被批量下载到本地

踩坑提示：waitForSelector之前不要急着取 HTML，动态列表可能还没加载完；用完记得browser.close()；AI 提示词"描述越详细越好"，只说"图片链接"不如说清"不要 source 里面的、并去重"。

案例二：用优先队列监控多个接口

业务目标：同时采多个数据源时，重要接口先跑。

实现思路：crawlData的目标配置里传priority，值越大越优先。

关键代码：

crawlApp .crawlData([ { url: 'https://www.example.com/api-1', priority: 1 }, { url: 'https://www.example.com/api-2', priority: 10 }, { url: 'https://www.example.com/api-3', priority: 8 } ]) .then((res) => {})

踩坑提示：intervalTime默认是 undefined（不间隔），多目标会同时发出；生产环境建议显式配一个随机间隔。

进阶与避坑：三档可直接套用的配置

• 入门（公开数据、低频）：createCrawl()零参数即可；纯接口用crawlData直接拿 JSON，不启动浏览器，路径最短。
• 进阶（动态页面、批量）：

createCrawl({ intervalTime: { max: 2000, min: 1000 }, maxRetry: 3 })

目标之间随机间隔 1~2 秒，失败最多补发 3 次。

• 高压（同站批量采集）：轮换代理与重试叠加，注意maxRetry必须大于该目标所有代理的switchByErrorCount总和：

crawlApp.crawlPage({ targets: [...], maxRetry: 10, proxy: { urls: ['proxy-1', 'proxy-2'], switchByErrorCount: 3, switchByHttpStatus: [401, 403] } })

• 💡常见问题：AI 慢、token 贵？只传目标容器的 HTML 而不是整页；不想花 API 费用就换createCrawlOllama本地跑模型。
• 💡常见问题：某个目标要关掉指纹或代理？在详细目标配置里传fingerprint: null/proxy: null；完整选项见 设备指纹 与 轮换代理。

跑完上面 4 步，多数单页采集需求就够用了；全部配置项见仓库 docs/cn/guide/ 目录，入口是 快速上手。

使用 x-crawl 时请遵守目标网站的 robots.txt 与服务条款，控制请求频率，只采集你有权获取的数据。

【免费下载链接】x-crawlFlexible Node.js AI-assisted crawler library项目地址: https://gitcode.com/gh_mirrors/xc/x-crawl