Skip to content

Commit 2a787f9

Browse files
committed
Docs: detail adjustment
1 parent 3636ae0 commit 2a787f9

File tree

6 files changed

+257
-276
lines changed

6 files changed

+257
-276
lines changed

README.md

Lines changed: 89 additions & 91 deletions
Large diffs are not rendered by default.

docs/cn.md

Lines changed: 47 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@ x-crawl 是一个灵活的 Node.js 多功能爬虫库。用于爬页面、爬接
88
99
## 特征
1010

11-
- **🔥 异步/同步** - 只需更改一下 mode 属性即可切换 异步/同步 爬取模式
12-
- **⚙️ 多种功能** - 可爬页面、爬接口、爬文件以及轮询爬并且支持爬取单个或多个。
13-
- **🖋️ 写法灵活** - 一种功能适配多种爬取配置、获取爬取结果的写法,写法非常灵活
14-
- **👀 设备指纹** - 零配置/自定义配置,即可避免通过指纹识别从不同位置识别并跟踪我们。
15-
- **⏱️ 间隔爬取** - 无间隔/固定间隔/随机间隔,可以有效 使用/避免 高并发爬取
16-
- **🔄 失败重试** - 可针对所有爬取的请求设置,针对单次爬取的请求设置,针对单个请求设置进行失败重试
17-
- **🚀 优先队列** - 根据单个请求的优先级使用优先爬取
18-
- **☁️ 爬取 SPA** - 批量爬取 SPA(单页应用程序)生成预渲染内容(即“SSR”(服务器端渲染))。
11+
- **🔥 异步/同步** - 只需更改一下 mode 属性值即可切换异步或同步爬取模式
12+
- **⚙️ 多种功能** - 可爬页面、爬接口、爬文件以及轮询爬并且支持爬取单个或多个。
13+
- **🖋️ 写法灵活** - 简单目标配置、详细目标配置、混合目标数组配置以及进阶配置,同种爬取 API 适配多种配置
14+
- **👀 设备指纹** - 零配置或自定义配置,即可避免通过指纹识别从不同位置识别并跟踪我们。
15+
- **⏱️ 间隔爬取** - 无间隔、固定间隔以及随机间隔,即可产生或避免高并发爬取
16+
- **🔄 失败重试** - 全局设置、局部设置以及单独设置。即可避免因一时问题而造成爬取失败
17+
- **🚀 优先队列** - 根据单个爬取目标的优先级可以优先于其他目标提前进行爬取
18+
- **☁️ 爬取 SPA** - 爬取 SPA(单页应用程序)生成预渲染内容(即“SSR”(服务器端渲染))。
1919
- **⚒️ 控制页面** - 无头浏览器可以表单提交、键盘输入、事件操作、生成页面的屏幕截图等。
20-
- **🧾 捕获记录** - 对爬取的结果进行捕获记录,并在控制台进行高亮的提醒。
20+
- **🧾 捕获记录** - 对爬取的结果等信息进行捕获记录,并在控制台进行高亮的提醒。
2121
- **🦾 TypeScript** - 拥有类型,通过泛型实现完整的类型。
2222

2323
## 跟 puppeteer 的关系
@@ -211,12 +211,14 @@ const myXCrawl = xCrawl({
211211

212212
mode 选项默认为 async 。
213213

214-
- async: 异步请求,在批量请求时,无需等当前请求完成,就进行下次请求
215-
- sync: 同步请求,在批量请求时,需要等这次请求完成,才会进行下次请求
214+
- async: 异步爬取目标,无需等当前爬取目标完成,就进行下次爬取目标
215+
- sync: 同步爬取目标,需要等这次爬取目标完成,才会进行下次爬取目标
216216

217-
若有设置间隔时间,则都需要等间隔时间结束才能发送请求
217+
若有设置间隔时间,则都需要等间隔时间结束才会爬取下次目标
218218

219-
#### 设备指纹
219+
**注意:** 爬取 API 的爬取过程都是单独进行的,该模式对批量爬取目标才有效。
220+
221+
#### 默认设备指纹
220222

221223
可以通过一个属性控制是否使用默认的随机指纹,您也可以通过后续的爬取配置自定义指纹。
222224

@@ -232,8 +234,8 @@ const myXCrawl = xCrawl({
232234

233235
enableRandomFingerprint 选项默认为 true。
234236

235-
- true: 启动随机设备指纹。可通过进阶版配置或详细目标版配置指定目标的指纹配置
236-
- false: 关闭随机设备指纹,不影响进阶版配置或详细版配置为目标指定的指纹配置
237+
- true: 启动随机设备指纹。可通过进阶配置或详细目标配置指定目标的指纹配置
238+
- false: 关闭随机设备指纹,不影响进阶配置或详细目标配置为目标指定的指纹配置
237239

238240
#### 多个爬虫应用实例
239241

@@ -268,15 +270,13 @@ myXCrawl.crawlPage('https://www.example.com').then((res) => {
268270

269271
#### browser 实例
270272

271-
它是 [Browser](https://pptr.dev/api/puppeteer.browser) 的实例对象,具体使用可以参考 [Browser](https://pptr.dev/api/puppeteer.browser)
272-
273-
browser 实例他是个无头浏览器,并无 UI 外壳,他做的是将浏览器渲染引擎提供的**所有现代网络平台功能**带到代码中。
273+
当你在同个爬虫实例调用 crawlPage API 进行爬取页面时,所用的 browser 实例都是同一个,因为 browser 实例在同个爬虫实例中的 crawlPage API 是共享的。他是个无头浏览器,并无 UI 外壳,他做的是将浏览器渲染引擎提供的**所有现代网络平台功能**带到代码中。具体使用可以参考 [Browser](https://pptr.dev/api/puppeteer.browser)
274274

275-
**注意:** browser 会一直保持着运行,造成文件不会终止,如果想停止可以执行 browser.close() 关闭。如果后面还需要用到 [crawlPage](#crawlPage) 或者 [page](#page) 请勿调用。因为当您修改 browser 实例的属性时,会对该爬虫实例 crawlPage API 内部的 browser 实例和返回结果的 page 实例以及 browser 实例造成影响,因为 browser 实例在同一个爬虫实例的 crawlPage API 内是共享的
275+
**注意:** browser 会一直保持着运行,造成文件不会终止,如果想停止可以执行 browser.close() 关闭。如果后面还需要用到 [crawlPage](#crawlPage) 或者 [page](#page) 请勿调用。因为 browser 实例在同个爬虫实例中的 crawlPage API 是共享的
276276

277277
#### page 实例
278278

279-
它是 [Page](https://pptr.dev/api/puppeteer.page) 的实例对象,实例还可以做事件之类的交互操作,具体使用可以参考 [page](https://pptr.dev/api/puppeteer.page)
279+
当你在同个爬虫实例调用 crawlPage API 进行爬取页面时,都会从 browser 实例中产生一个新的 page 实例。其可以做交互操作,具体使用可以参考 [Page](https://pptr.dev/api/puppeteer.page)
280280

281281
browser 实例内部会保留着对 page 实例的引用,如果后续不再使用需要自行关闭 page 实例,否则会造成内存泄露。
282282

@@ -301,13 +301,13 @@ myXCrawl.crawlPage('https://www.example.com').then(async (res) => {
301301

302302
#### 生命周期
303303

304-
crawlPageAPI 拥有的声明周期函数:
304+
crawlPage API 拥有的声明周期函数:
305305

306-
- onCrawlItemComplete: 当每个爬取目标结束并处理后执行
306+
- onCrawlItemComplete: 当每个爬取目标完成并进行了处理后会回调
307307

308308
##### onCrawlItemComplete
309309

310-
在 onCrawlItemComplete 函数中你可以拿到每个爬取目标的结果
310+
在 onCrawlItemComplete 函数中你可以提前拿到每次爬取目标的结果
311311

312312
**注意:** 如果你需要一次性爬取很多页面,就需要在每个页面爬下来后,用这个生命周期函数来处理每个目标的结果并关闭 page 实例,如果不进行关闭操作,则会因开启的 page 过多而造成程序崩溃。
313313

@@ -339,11 +339,11 @@ myXCrawl.crawlData({ targets }).then((res) => {
339339

340340
crawlData API 拥有的声明周期函数:
341341

342-
- onCrawlItemComplete: 当每个爬取目标结束并处理后执行
342+
- onCrawlItemComplete: 当每个爬取目标完成并进行了处理后会回调
343343

344344
##### onCrawlItemComplete
345345

346-
在 onCrawlItemComplete 函数中你可以拿到每个爬取目标的结果
346+
在 onCrawlItemComplete 函数中你可以提前拿到每次爬取目标的结果
347347

348348
### 爬取文件
349349

@@ -369,17 +369,17 @@ myXCrawl
369369

370370
crawlFile API 拥有的声明周期函数:
371371

372-
- onCrawlItemComplete: 当每个爬取目标结束并处理后执行
372+
- onCrawlItemComplete: 当每个爬取目标完成并进行了处理后会回调
373373

374-
- onBeforeSaveItemFile: 在保存文件前执行
374+
- onBeforeSaveItemFile: 会在保存文件前回调
375375

376376
##### onCrawlItemComplete
377377

378-
在 onCrawlItemComplete 函数中你可以拿到每个爬取目标的结果
378+
在 onCrawlItemComplete 函数中你可以提前拿到每次爬取目标的结果
379379

380380
##### onBeforeSaveItemFile
381381

382-
在 onBeforeSaveItemFile 函数中你可以拿到 Buffer 类型的文件,你可以对该 Buffer 进行处理,然后需要返回一个 Promise ,并且 resolve 是 Buffer 。
382+
在 onBeforeSaveItemFile 函数中你可以拿到 Buffer 类型的文件,你可以对该 Buffer 进行处理,然后需要返回一个 Promise ,并且 resolve 是 Buffer ,该 Buffer 会替换掉拿到的 Buffer 存储到文件中
383383

384384
**调整图片大小**
385385

@@ -427,7 +427,7 @@ myXCrawl.startPolling({ h: 2, m: 30 }, async (count, stopPolling) => {
427427
})
428428
```
429429
430-
**在轮询中使用 crawlPage 注意:** 调用 page.close() 是为了防止 browser 实例内部还保留着对 page 实例的引用,如果后续不再使用当前 page 需要自行关闭,否则会造成内存泄露。
430+
**在轮询中使用 crawlPage 注意:** browser 实例内部会保留着对 page 实例的引用,如果后续不再使用需要自行关闭 page 实例,否则会造成内存泄露。
431431
432432
回调函数参数:
433433
@@ -469,11 +469,11 @@ myXCrawl.crawlPage({
469469
})
470470
```
471471
472-
在上面的实例中,**应用实例配置**和**进阶配置**中都设置了间隔时间,那么将会以**进阶配置**的间隔时间为准。在**进阶配置**和**详细目标配置**中设置了视口,那么第二个目标是设置了视口,其将会以**详细目标配置**的视口为准。
472+
在上面的实例中,**应用实例配置**和**进阶配置**中都设置了间隔时间,那么将会以**进阶配置**的间隔时间为准。在**进阶配置**和**详细目标配置**中设置了视口,那么第二个目标会以其**详细目标配置**的视口为准。
473473
474-
### 设备指纹
474+
### 自定义设备指纹
475475
476-
自定义配置,即可避免通过指纹识别从不同位置识别并跟踪我们
476+
自定义配置设备指纹,可避免通过指纹识别从不同位置识别并跟踪我们
477477
478478
可以通过进阶用法在 fingerprint 传入多个信息,内部会帮助您随机分配给 targets 的每个目标。也可以直接用详细目标配置为目标设置特定的指纹。
479479
@@ -521,7 +521,7 @@ myXCrawl
521521
522522
间隔时间可以防止并发量太大,避免给服务器造成太大的压力。
523523
524-
爬取间隔时间是由实例方法内部控制的,并非由实例控制整个爬取间隔时间
524+
爬取间隔时间是由爬取 API 内部自己控制的,并非由爬虫实例控制爬取 API 的间隔时间
525525
526526
```js
527527
import xCrawl from 'x-crawl'
@@ -536,32 +536,32 @@ myXCrawl
536536
.then((res) => {})
537537
```
538538
539-
intervalTime 选项默认为 undefined 。若有设置值,则会在请求前等待一段时间,可以防止并发量太大,避免给服务器造成太大的压力。
539+
intervalTime 选项默认为 undefined 。若有设置值,则会在爬取目标前等待一段时间,可以防止并发量太大,避免给服务器造成太大的压力。
540540
541-
- number: 固定每次请求前必须等待的时间
542-
- Object: 在 max 和 min 中随机取一个值,更加拟人化
541+
- number: 固定每次爬取目标前必须等待的时间
542+
- IntervalTime: 在 max 和 min 中随机取一个值
543543
544-
**注意:** 第一次请求是不会触发间隔时间
544+
**注意:** 第一次爬取目标是不会触发间隔时间
545545
546546
### 失败重试
547547
548-
失败重试在超时之类的错误发生时,将会等待这一轮请求结束后重新请求
548+
可避免因一时问题而造成爬取失败,将会等待这一轮爬取目标结束后重新爬取目标
549549
550550
```js
551551
import xCrawl from 'x-crawl'
552552

553553
const myXCrawl = xCrawl()
554554

555555
myXCrawl
556-
.crawlData({ url: 'https://www.example.com/api', maxRetry: 1 })
556+
.crawlData({ url: 'https://www.example.com/api', maxRetry: 9 })
557557
.then((res) => {})
558558
```
559559
560560
maxRetry 属性决定要重试几次。
561561
562562
### 优先队列
563563
564-
优先队列可以让某个请求优先发送
564+
优先队列可以让某个爬取目标优先发送
565565
566566
```js
567567
import xCrawl from 'x-crawl'
@@ -581,9 +581,9 @@ priority 属性的值越大就在当前爬取队列中越优先。
581581
582582
### 关于结果
583583
584-
对于结果,每个请求的结果将统一使用对象包裹着,该对象提供了关于这次请求结果的信息,比如:id、结果、是否成功、最大重试、重试次数、收集到错误信息等。自动根据你选用的配置方式决定返回值是否包裹在一个数组中,并且在 TS 中类型完美适配。
584+
对于结果,每个爬取目标的结果将统一使用对象包裹着,该对象提供了关于这次爬取目标结果的信息,比如:id、结果、是否成功、最大重试、重试次数、收集到错误信息等。自动根据你选用的配置方式决定返回值是否包裹在一个数组中,并且在 TS 中类型完美适配。
585585
586-
每个对象的 id 是根据你配置里的请求顺序决定的,如果有使用优先级,则会根据优先级排序。
586+
每个对象的 id 是根据你配置里的爬取目标顺序决定的,如果有使用优先级,则会根据优先级排序。
587587
588588
相关的配置方式和结果详情查看:[crawlPage 配置](#配置)、[crawlData 配置](#配置-1)、[crawlFile 配置](#配置-2) 。
589589
@@ -597,7 +597,7 @@ x-crawl 本身就是用 TypeScript 编写的,并对 TypeScript 提供了支持
597597
598598
### xCrawl
599599
600-
通过调用 xCrawl 创建一个爬虫实例。请求是由实例方法内部自己维护,并非由实例自己维护。
600+
通过调用 xCrawl 创建一个爬虫实例。爬取目标是由实例方法内部自己维护,并非由实例自己维护。
601601
602602
#### 类型
603603
@@ -753,7 +753,7 @@ myXCrawl
753753
754754
##### 进阶配置 - CrawlPageAdvancedConfig
755755
756-
这是进阶配置,targets 是混合目标数组配置。如果你想爬取多个页面,并且请求配置(proxy、cookies、重试等等)不想重复写,还需要间隔时间、设备指纹以及生命周期等等,可以试试这种写法:
756+
这是进阶配置,targets 是混合目标数组配置。如果你想爬取多个页面,并且爬取目标配置(proxy、cookies、重试等等)不想重复写,还需要间隔时间、设备指纹以及生命周期等等,可以试试这种写法:
757757
758758
```js
759759
import xCrawl from 'x-crawl'
@@ -911,7 +911,7 @@ myXCrawl
911911
912912
##### 进阶配置 - CrawlDataAdvancedConfig
913913
914-
这是进阶配置,targets 是混合目标数组配置。如果你想爬取多个数据,并且请求配置(proxy、cookies、重试等等)不想重复写,还需要间隔时间、设备指纹以及生命周期等等,可以试试这种写法:
914+
这是进阶配置,targets 是混合目标数组配置。如果你想爬取多个数据,并且爬取目标配置(proxy、cookies、重试等等)不想重复写,还需要间隔时间、设备指纹以及生命周期等等,可以试试这种写法:
915915
916916
```js
917917
import xCrawl from 'x-crawl'
@@ -1052,7 +1052,7 @@ myXCrawl
10521052
10531053
##### 进阶配置 - CrawlFileAdvancedConfig
10541054
1055-
这是进阶配置,targets 是混合目标数组配置。如果你想爬取多个数据,并且请求配置(proxy、storeDir、重试等等)不想重复写,还需要间隔时间、设备指纹以及生命周期等等,可以试试这种写法:
1055+
这是进阶配置,targets 是混合目标数组配置。如果你想爬取多个数据,并且爬取目标配置(proxy、storeDir、重试等等)不想重复写,还需要间隔时间、设备指纹以及生命周期等等,可以试试这种写法:
10561056
10571057
```js
10581058
import xCrawl from 'x-crawl'

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
"dependencies": {
3333
"chalk": "4.1.2",
3434
"https-proxy-agent": "^5.0.1",
35-
"puppeteer": "19.9.0",
35+
"puppeteer": "19.9.1",
3636
"x-crawl": "link:"
3737
},
3838
"devDependencies": {

pnpm-lock.yaml

Lines changed: 8 additions & 22 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)