网页爬虫【免费下载链接】node-crawlerWeb Crawler/Spider for NodeJS server-side jQuery ;-)项目地址https://gitcode.com/gh_mirrors/no/node-crawler点击查看免费下载导读node-crawlernpm 包名crawler是构建在got之上的 Node.js 生产级爬虫框架内置任务队列、连接池、多级限速器、自动重试、代理轮换、字符集检测与 Cheerio 服务端解析能力。本文以官方 options.md 为骨架逐项拆解全部配置选项的语义、默认值与底层实现并结合 src/options.ts、src/crawler.ts、src/rateLimiter 等源码说明每个参数在内部如何生效。读完本文你将能根据目标站点的并发策略、限速诉求、代理拓扑与响应编码编写出可投入生产运行的爬虫配置。选项传递的两个层级构造函数全局项与add()任务项选项可以在两个位置设置且层级关系明确构造函数全局项new Crawler({ ... })中的选项作为所有任务的默认配置保存在实例的this.options上见 src/crawler.ts 中defaultOptions与用户传入项合并的{ ...defaultOptions, ...options }add()任务级项crawler.add({ ... })中的选项仅作用于该任务并通过setDefaults(options, this.options)以任务级优先的方式覆盖全局默认值。除层级外add()还支持三种入参形态纯 URL 字符串c.add(https://example.com)内部经getValidOptions转换为{ url }选项对象数组c.add([https://a.com, https://b.com])一次批量入队多个任务flattenDeep还支持嵌套数组选项对象c.add({ url, callback, ... })。getValidOptions见 src/options.ts还接受JSON 字符串形式的选项若字符串不是合法 URL则尝试JSON.parse解析失败会抛出TypeError: Invalid options。另一个关键点是透传所有 got 原生选项如url、method、headers、body、searchParams、form、cookieJar、decompress、parseJson等都会被接受并原样传递给底层请求。alignOptions见 src/options.ts只剥离 Crawler 专属选项和已废弃选项其余原样交给 got。下表列出 Crawler 专属选项下文逐一展开分类选项全局专属silence、maxConnections、priorityLevels、rateLimit、skipDuplicates、homogeneous、userAgents通用全局 任务级forceUTF8、jQuery、encoding、rateLimiterId、retries、retryInterval、timeout、priority、skipEventRequest、html、proxies、proxy、http2、autoSelectFamily、autoSelectFamilyAttemptTimeout、referer、userParams、preRequest、callback全局专属选项Global-only Options以下选项只能在构造函数中设置任务级传入会被合并但语义上仍以全局为准。它们与 src/options.ts 中的globalOnlyOptions列表一一对应。silence类型boolean默认值false设为true后爬虫将静默所有警告与错误日志但请求错误仍会通过 callback 的error参数上报不会吞掉业务错误。源码证据构造函数中if (this.options.silence) log.settings.minLevel 7;见 src/crawler.ts即把日志级别调到最高屏蔽 debug/warn/error 输出。maxConnections类型number默认值10最大并发请求数。注意类型注释中的关键约束只有当全局rateLimit为 0 时maxConnections 1才真正生效一旦rateLimit 0maxConnections会被强制改为1见 src/crawler.ts。实现层面该值被传入Cluster为每个限速器RateLimiter实例设定maxConnections见 src/rateLimiter/cluster.tsRateLimiter._schedule中runningSize maxConnections才派发任务见 src/rateLimiter/rateLimiter.ts。priorityLevels类型number默认值10优先级级数只能在构造时指定。它决定了内部multiPriorityQueue的队列条数见 src/lib/multiPriorityQueue.ts数值越大任务可按更细粒度排队。任务优先级priority的有效范围是[0, priorityLevels)越界值会被钳制Math.min(priority, priorityLevels - 1)见 src/rateLimiter/rateLimiter.ts。rateLimit类型number默认值0默认限速器id 为 0上相邻两次请求的最小间隔毫秒。文档强调三点它只设定limiter 0 的默认值运行时需通过crawler.setLimiter()调整不要在任务级选项里重复传rateLimit任务级应该用options.rateLimiterId指定走哪个限速器rateLimit 0时maxConnections被强制为1与前述一致。源码实现RateLimiter._schedule中nextRequestTime Date.now() delay rateLimit用setTimeout(delay)保证最小间隔见 src/rateLimiter/rateLimiter.ts。官方示例在schedule事件里按任务动态分配限速器crawler.on(schedule, options { options.rateLimiterId Math.floor(Math.random() * 15); });skipDuplicates类型boolean默认值false为true时已存在于队列中的任务按 URL 判重将被跳过不再重复入队。源码证据add()中当skipDuplicates为真时会先经seenreq实例的exists()查重见 src/crawler.ts判重能力由seenreq模块提供可在选项里通过seenreq配置其存储后端。homogeneous类型boolean默认值false为true时当某个队列因队首阻塞如单一代理拖慢而无法前进任务会被动态重新分配到其他队列避免头部阻塞拖垮整体吞吐。源码证据Cluster构造时把自身传给各RateLimiter作为cluster引用见 src/rateLimiter/cluster.ts当一个限速器无等待任务时dequeue()会回落到cluster.dequeue()借调其他队列的任务见 src/rateLimiter/rateLimiter.ts 与 src/rateLimiter/cluster.ts且limiterChange事件会在任务换队列时发出。userAgents类型string | string[]默认值文档标注undefined设置后每个请求轮换 User-Agent。必须传数组才会轮换。补充说明与源码的差异点文档将默认值标为undefined但源码的defaultOptions实际内置了一个固定 Chrome UA 字符串见 src/crawler.ts即未配置时使用固定 UA只有传入数组时_execute才按_UAIndex逐请求轮换见 src/crawler.ts。通用选项General Options这类选项既可在构造函数设置也可在add()中按任务覆盖。got 原生选项透传url | method | headers | body | searchParams | form | ...标准 got 选项直接透传到底层请求。常见用法包括c.add({ url: https://api.example.com/items, method: POST, form: { page: 1, size: 50 }, // v2 中提交表单用 form不再用 body headers: { Authorization: Bearer xxx }, searchParams: { t: Date.now() }, });注意两点来自 SKILL.md 的 GotchasPOST 表单数据必须用form而非bodyalignOptions会把timeout包装成{ request: timeout }、把rejectUnauthorized映射到https.rejectUnauthorized并设置responseType: buffer见 src/options.ts。forceUTF8类型boolean默认值false为true时从 HTTP 响应头或 HTMLmeta标签中检测字符集并转码为 UTF-8。源码证据_execute中if (options.forceUTF8 || options.isJson) options.encoding utf8见 src/crawler.ts_handler中先用getCharset(headers)解析响应头content-type的charset缺失时再对 body 正则匹配meta charset见 src/crawler.ts最后用iconv-lite解码见 src/crawler.ts。jQuery类型boolean默认值true为true时用 Cheerio 解析响应体并通过res.$暴露 jQuery 风格选择器。源码证据_handler中调用load(response.body)注入见 src/crawler.ts仅当响应体非空、content-type匹配xml|html且isJson为假时才注入。抓取二进制或 JSON 时建议设为false以避免无谓解析开销与警告日志。encoding类型string | null默认值utf8响应体编码设为null时保持 body 为Buffer用于二进制下载否则输出会被转码损坏。源码证据_handler中options.encoding ! null时才会走 iconv 解码见 src/crawler.ts。二进制下载的完整示例见 examples.mdconst c new Crawler({ encoding: null, // 保持 Buffer jQuery: false, // 跳过 Cheerio 解析 callback: (err, res, done) { if (err) { console.error(err); done(); return; } fs.writeFileSync(res.options.userParams.filename, res.body); done(); }, }); c.add({ url: https://example.com/image.png, userParams: { filename: ./downloads/image.png } });rateLimiterId类型number默认值0该任务使用哪个限速器常用于按代理分组限速不同代理池走不同限速器互不拖累。任务级示例c.add({ url: https://site/page/1, rateLimiterId: 1, proxy: http://p1:port }); c.add({ url: https://site/page/2, rateLimiterId: 2, proxy: http://p2:port });源码证据Cluster.getRateLimiter(id ?? 0)按 id 惰性创建 RateLimiter 并复用见 src/rateLimiter/cluster.ts因此不同 id 的限速器拥有独立的nextRequestTime与并发窗口。retries类型number默认值2失败重试次数。_handler中错误路径会打印剩余重试次数并按retryInterval延迟重跑_execute见 src/crawler.ts同时alignOptions会把 got 自身的retry.limit设为 0重试逻辑完全由 Crawler 接管见 src/options.ts。retryInterval类型number默认值3000重试前等待的毫秒数见 src/crawler.ts 的setTimeout(..., options.retryInterval)。timeout类型number默认值20000请求超时毫秒。alignOptions将其转换为 got 的timeout: { request }见 src/options.ts。priority类型number默认值5任务优先级有效范围[0, priorityLevels)。值越大越先出队。源码证据RateLimiter.submit将任务按priority放入multiPriorityQueue的对应队列见 src/rateLimiter/rateLimiter.tsdequeue()从最高优先级队列开始取任务见 src/lib/multiPriorityQueue.ts。test/priority.js 用 nock 模拟的用例验证了高优先级先执行分别以优先级 4、3、2、1 入队四个任务drain时执行顺序为[0, 3, 2, 1]即按优先级从高到低。skipEventRequest类型boolean默认值false为true时该任务不触发request事件。注意该选项在源码中已被列入deprecatedOptions见 src/options.tssend()内部会强制将其置为true见 src/crawler.ts新代码不建议使用。html类型boolean默认值true为true时把响应体当作 HTML 解析。特殊用法传入html: titleTest/title可以注入原始 HTML 字符串而不发网络请求_schedule中if (options.html)分支直接调用_handler见 src/crawler.ts非常适合测试与本地处理。proxies类型string[]默认值[]代理 URL 数组按请求轮换。官方建议优先用schedule事件做动态分配控制力更强见下文事件章节。源码证据_execute中当未显式指定proxy时按_proxyIndex轮换取用见 src/crawler.ts。proxy类型string默认值undefined单任务代理 URL覆盖proxies。源码中alignOptions会为代理创建hpagent的HttpProxyAgent/HttpsProxyAgent见 src/options.ts。http2类型boolean默认值false使用 HTTP/2 协议。与代理组合时alignOptions通过http2-wrapper创建Http2OverHttp/Http2OverHttpsagent见 src/options.ts。抓取带自签名证书的目标如 Charles 代理环境时需配合rejectUnauthorized: falsec.add({ url: https://example.com, http2: true, proxy: http://127.0.0.1:8888, rejectUnauthorized: false, callback: (e, res, done) { done(); }, });autoSelectFamily类型boolean默认值trueNode 默认控制 Node 的 Happy Eyeballs同时竞速 IPv6 与 IPv4。在 IPv6 网络异常/缓慢的环境下应设为false避免无谓的ETIMEDOUT。重要该选项是Node 进程级设置。源码在alignOptions中通过net.setDefaultAutoSelectFamily()全局生效而非逐请求传入 got见 src/options.ts因此会影响进程内所有在途请求。autoSelectFamilyAttemptTimeout类型number默认值250Node 默认Happy Eyeballs 等待单一地址族的毫秒数高延迟主机可调大如5000避免 250ms 内 TCP/TLS 握手未完成就被判定超时。同样是进程级设置见 src/options.ts源码注释明确说明 got 会剥离未知选项、无法按请求透传故只能在此提前应用到 Node 默认值。referer类型string默认值undefined请求的 HTTPReferer头。alignOptions中若未设置referer头则取options.referer否则自动以 URL 的协议 域名作为Referer见 src/options.ts。userParams类型any默认值undefined附加到任务的任意业务数据回调中通过res.options.userParams读取。这是官方唯一支持的传自定义数据方式不要直接在 options 对象上挂自定义字段会被alignOptions剥离。用法示例c.add({ url: https://site/item/42, userParams: { id: 42, category: books } }); // 回调内 const { id, category } res.options.userParams;preRequest类型(options, done) void默认值undefined每次请求前的钩子仅队列模式生效send()不触发。options是最终交给 got 的请求配置修改后必须调用done()放行done(err)传错则直接进入错误回调。源码证据_execute中检测到preRequest后以回调形式调用成功才继续发请求见 src/crawler.ts。任务级preRequest可覆盖全局钩子示例见 examples.mdc.add({ url: https://example.com/special, preRequest: (options, done) { options.headers[X-Custom] value; done(); }, });callback类型(error, res, done) void任务回调是数据消费的核心出口。三个参数error—— 错误对象由爬虫捕获并传入即使设置了silence也会上报res—— 响应对象包含res.options—— 本次任务的选项含userParams等res.$—— Cheerio 实例当jQuery不为false时存在res.statusCode—— HTTP 状态码res.body—— 响应体Buffer或string取决于encodingres.headers—— 响应头done——必须调用表示任务完成、释放连接槽漏调会导致爬虫死锁见 src/crawler.ts 中 callback 以options.release作为第三个参数传入。事件EventsCrawler继承自EventEmitter通过事件驱动整个调度流程事件签名触发时机schedule(options)任务被加入调度器时limiterChange(options, rateLimiterId)限速器变更时如homogeneous重分配request(options)请求发送前drain()队列清空时各事件的使用场景schedule入队即触发是动态分配代理、限速器的最佳时机早于请求发生const proxies [http://p1:8080, http://p2:8080]; let idx 0; c.on(schedule, options { options.proxy proxies[idx]; idx (idx 1) % proxies.length; });request请求发出前最后修改机会常用于加时间戳参数options.searchParams { t: Date.now() }。源码中该事件在_execute内调用 got 之前触发见 src/crawler.ts受skipEventRequest控制。limiterChange当任务因homogeneous重分配被移入其他限速器时携带目标rateLimiterId触发见 src/crawler.ts。drain_limiters.empty即所有限速器的 running waiting 均为 0 时触发见 src/crawler.ts。判断爬虫是否结束必须监听drain而不是在add()返回后立即打印完成——add()只是入队异步请求仍在进行。类 APIClass APIcrawler.add(url | options)向队列添加任务接受 URL 字符串、选项对象、或二者的可嵌套数组。全局选项与任务级选项在此合并setDefaults并受skipDuplicates去重逻辑约束见 src/crawler.ts。queue()是add()的旧名别名已废弃。crawler.send(options)直接发请求绕过队列、限速器、preRequest与request事件同时支持 Promise 与回调两种形态见 src/crawler.ts// Promise 形式 const res await c.send(https://example.com); console.log(res.statusCode, res.body.length); // 回调形式两个参数无 done() c.send({ url: https://example.com, callback: (error, response) { /* ... */ } });源码细节send()默认把retries置为 0、skipEventRequest置为true并删除preRequest确证其一次性直连语义。适合单次请求或请求已由外部限速的场景官方还指出应避免对send()抱有多队列机制期待见 SKILL.md Gotchas。crawler.setLimiter(id, property, value)运行时修改某个限速器的属性当前仅支持rateLimit源码留有// todo other properties见 src/crawler.ts。修改后rateLimit 0同样会把该限速器的maxConnections钳制为 1见 src/rateLimiter/rateLimiter.ts。crawler.setLimiter(0, rateLimit, 1000); // 默认限速器 crawler.setLimiter(1, rateLimit, 500); // id1 的限速器需已有任务使用过crawler.queueSize类型number只读文档语义为当前队列中的任务数。实现注意事项当前仓库源码中该 getter 返回固定值0占位实现见 src/crawler.ts如需精确统计队列长度可参考Cluster暴露的waitingSize/unfinishedSize/status见 src/rateLimiter/cluster.ts。配置最佳实践与高频陷阱综合 SKILL.md 与 examples.md生产环境配置时请重点规避以下问题done()必须在每个分支调用包括if (error)分支否则连接槽不被释放爬虫死锁结束判定用drain事件add()返回不等于完成rateLimit 0时别指望并发maxConnections会被强制为 1如需并发又限速用多个rateLimiterId拆分每代理一个限速器见 examples.md 的 per-proxy 示例不要对send()期待队列机制它绕过preRequest、request与限速器POST 表单用formv2 不再接受body传表单二进制下载必须encoding: null否则 Buffer 被字符串化转码导致文件损坏代理轮换优先用schedule事件比proxies数组更可控可结合rateLimiterId做分池限速自定义数据走userParams直接挂字段会被alignOptions剥离crawlerOnlyOptionsdeprecatedOptions清单见 src/options.ts。参考资料options.md官方选项参考本文骨架examples.md全场景可运行示例队列、限速、Cheerio 抽取、二进制下载、直连、HTTP/2、代理轮换、preRequest、完整蜘蛛SKILL.md使用决策与常见坑位速查src/options.ts选项解析、废弃别名映射uri→url、qs→searchParams、strictSSL→rejectUnauthorized、incomingEncoding→encoding、gzip→decompress、jar→cookieJar、limiter→rateLimit等与 got 对齐逻辑src/crawler.ts调度、执行、回调与事件核心实现src/rateLimiterCluster 与 RateLimiter 的多级限速实现src/lib/multiPriorityQueue.ts 与 test/priority.js多级优先队列实现与优先级测试赞分享网页爬虫【免费下载链接】node-crawlerWeb Crawler/Spider for NodeJS server-side jQuery ;-)项目地址https://gitcode.com/gh_mirrors/no/node-crawler点击查看免费下载相关推荐Turborepo turbo.json 配置完全指南从全局选项到包级任务覆盖Turborepo turbo.json 配置完全指南从全局选项到包级任务覆盖 本文以 Turborepo 官方技能文档 skills/turborepo/r构建工具开发工具CLIelectron-vue 全局配置完全指南config.js、webpack 与构建选项深度解析electron vue 全局配置完全指南config.js、webpack 与构建选项深度解析 导读 electron vue 是一个基于 Electron前端桌面应用koanf源码解析核心架构与设计模式koanf源码解析核心架构与设计模式 koanf 是一个轻量级、可扩展的 Go 配置管理库支持 JSON、TOML、YAML 等多种格式以及环境变量、命令后端上一篇mcp-go极速上手3分钟搭建你的第一个LLM工具集成应用下一篇Vue Grid Layout 自定义拖拽手柄实现打造个性化用户交互体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考