跳至内容
免费开始
返回博客

使用 JavaScript 和 Node.js 进行网页抓取:实用指南

Robert Sfichi最后更新于 6 min read
使用 JavaScript 和 Node.js 进行网页抓取:实用指南
简而言之:使用 JavaScript 和 Node.js 进行网页抓取,需要 Node.js 22.12 或更高版本、用于发送请求的内置 fetch,以及用于解析 HTML 的 Cheerio。当数据就在请求返回的 HTML 中时使用 Cheerio;当页面由 JavaScript 构建,或需要点击和等待时使用 Playwright。本指南从分页、隐藏 JSON 到离线测试和抓取 API 备用方案,完整构建一个爬虫。

使用 JavaScript 进行网页抓取通常从一个简单任务开始:数据位于网页上,你编写 JavaScript 代码,并希望将这些数据转换为干净的 JSON 格式,避免遇到块或空数组等问题。如果你对这个概念还比较陌生,请先阅读“什么是网页抓取”的相关内容。

本指南将以 books.toscrape.com(一个专为爬虫开发者打造的练习书店)作为示例。你将使用原生 fetch 和 Cheerio 提取并解析网页,礼貌地爬取分页目录,检查页面是否由 JavaScript 生成,使用 Playwright 渲染页面并点击跳转,离线测试解析器,并将受限页面转移到爬虫 API 上,而无需修改解析器。

快速入门

  • 请使用 Node.js 22.12 或更高版本(推荐 24 或 26 LTS)
  • npm install cheerio 适用于数据位于 HTML 中的页面
  • npm install playwright 适用于数据位于 HTML 中的页面适用于需要真实浏览器的页面
  • 在爬取前请检查 robots.txt 文件和网站的使用条款

使用 JavaScript 进行网页抓取需要什么?

你需要 Node.js 22.12 或更高版本、一个代码编辑器,以及两个包:用于解析 HTML 的 Cheerio 和用于渲染需要浏览器处理的页面的 Playwright。Node 内置的 fetch 方法可处理请求,因此无需使用 Axios。 同时也要熟悉浏览器的开发者工具,因为找到正确的选择器和页面数据源,就完成了工作的一半。

Node.js 非常适合用于网页抓取。它与页面自身的脚本使用相同的语言,因此阅读网站的 JavaScript 代码会让人感到很熟悉。其异步 I/O 模型无需线程即可处理大量网络请求。而且,领先的浏览器自动化工具 Playwright 和 Puppeteer 都是以 JavaScript 为核心的。

下表列出了本指南中使用的工具。如需更全面的汇总,请参阅《六款 Node.js 爬虫库对比》。

工具

用途

适用场景

npm 最新版本(2026年10月)

Node floor

fetch(内置)

HTTP 请求

始终可用;无需安装

属于 Node 的一部分

自 Node 21 起稳定

Cheerio

使用 CSS 选择器解析 HTML

数据位于 HTML 中

1.2.0

20.18.1

jsdom

Node.js 中的类浏览器 DOM

您需要的是 DOM API,而不仅仅是选择器

30.1.3

22.22.2、24.15 或 26

Playwright

驱动 Chromium、Firefox、WebKit

页面需要点击、等待或渲染操作

1.64.1

20

Puppeteer

驱动 Chrome 或 Firefox

现有的 Puppeteer 代码、Chrome 开发工具

25.16.0

22.12.0

p-limit

限制并发 Promise 数量

允许并行请求的网站上的多个 URL

7.3.3

20

Axios / Got

带附加功能的HTTP客户端

您已经在使用它们

1.21.0 / 16.1.0

— / 22

jsdom 构建的 DOM 比 Cheerio 更完整,但速度较慢,且仅在启用其文档中称为“不安全”的选项时才会运行页面脚本,因此 Cheerio 是更好的默认选择。如果您的项目已经使用 Axios,那么它也是可以的。 Node 版本说明解释了版本建议的原因:Puppeteer 需要 22.12 版本,而根据 Node.js 发布计划,Node 20 已超过生命周期。

如何搭建一个 Node.js 爬虫项目?

创建一个文件夹,将项目切换为 ES 模块,以便 import 使顶级 await 能正常工作,并安装两个主要包。Playwright只需额外执行一条命令即可下载其自带的 Chromium 构建版本。

mkdir node-scraper && cd node-scraper
npm init -y
npm pkg set type=module
npm install cheerio playwright
npx playwright install chromium
mkdir fixtures out
# Optional, for the Puppeteer example:
npm install puppeteer

该 fixtures/ 文件夹用于存储离线测试所需的已保存页面,而 out/ 用于存储测试结果。Puppeteer 会在安装过程中下载 Chrome,npm 11 可能会因此显示一条关于安装脚本的警告。你可以通过 npm install-scripts ls。如果您使用 TypeScript 编写代码,相同的代码可在 .ts 文件中运行,通过 Node 的内置类型剥离功能或诸如 tsx.

能否在浏览器中使用 JavaScript 抓取网站?

仅限于同一网站的页面。除非服务器通过 CORS 头部允许,否则浏览器会阻止一个网站的 JavaScript 读取另一个网站的响应,而大多数服务器并不允许。这就是为什么爬虫在 Node.js 中运行——Node.js 没有此类限制。请将浏览器 JavaScript 用于在开发者工具控制台中测试选择器,而非用于收集数据。

其背后的规则是同源策略。从一个源加载的脚本可以向另一个源发送请求,但除非另一个服务器通过 Access-Control-Allow-Origin 标头明确允许。MDN 的 CORS 指南对此有详细说明。

Node.js 并非浏览器,因此它会读取收到的任何响应。这使其成为构建爬虫的理想环境,同时还能避免将 API 密钥等凭据存储在访问者的设备上。浏览器扩展和书签小工具是唯一的例外:它们可以读取你当前正在浏览的页面,这适合一次性复制,但不适用于定时数据采集。

如何使用 Node.js 的 fetch 和 Cheerio 抓取网页?

使用 `fetch()` 获取页面的 HTML,检查响应是否正常,然后通过 `cheerio.load()` 将文本加载到 Cheerio 中。使用 CSS 选择器选中每个重复出现的卡片或行,从中读取文本或属性,并随读随转为数字。 返回普通对象,并使用 new URL(href, pageUrl) 解析相对链接。

books.toscrape.com 列出了 1,000 本图书,分布在 50 个目录页面中,每页 20 本,包含价格、星级评分和库存状态。网站上的横幅提示这是用于抓取练习的演示站点,且价格和评分均为随机生成,因此是一个安全的学习环境。

首先创建一个可重复使用的请求助手。它会发送一个描述性用户代理,并在 15 秒后停止请求,同时使用 AbortSignal.timeout(),并检查 res.ok,并针对速率限制和服务器错误进行重试。当服务器发送 Retry-After 标头时,它会等待该时间长度;否则,它将采用指数退避策略。

// fetch-html.js: one polite GET with a timeout, a status check, and retries
const HEADERS = {
  'User-Agent': 'node-scraper-tutorial/1.0 (+https://example.com/contact)',
  'Accept': 'text/html,application/xhtml+xml',
  'Accept-Language': 'en-US,en;q=0.9',
};
const RETRY = new Set([429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function fetchHtml(url, { retries = 3, timeoutMs = 15_000 } = {}) {
  for (let attempt = 0; ; attempt++) {
    let res;
    try {
      res = await fetch(url, { headers: HEADERS, signal: AbortSignal.timeout(timeoutMs) });
    } catch (err) {                                   // DNS, reset, or timeout
      if (attempt >= retries) throw err;
      await sleep(1000 * 2 ** attempt);
      continue;
    }
    if (res.ok) return res.text();
    if (!RETRY.has(res.status) || attempt >= retries) {
      throw new Error(`GET ${url} failed: HTTP ${res.status}`);
    }
    const retryAfter = Number(res.headers.get('retry-after'));  // seconds, if the server says so
    await sleep(retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** attempt);
  }
}

请将联系 URL 替换为你的地址,这样网站所有者就能联系到你,而不是直接封禁你。 fetch Node 内置了 `fetch` 功能,且 Fetch API 的工作原理与浏览器中完全一致。如果你正在考虑选用某个库,可以参考对原生 fetch、Axios、Got 和 Ky 的对比分析。

该解析器接受 HTML 和页面 URL,并返回类型化的记录。将其与网络代码分离,既便于测试,也便于在更改请求方式时复用。

// parse-books.js: turn one books.toscrape.com listing page into typed records
import * as cheerio from 'cheerio';

const RATINGS = { One: 1, Two: 2, Three: 3, Four: 4, Five: 5 };

export function parseBooks(html, pageUrl) {
  const $ = cheerio.load(html);

  const books = $('article.product_pod').map((_, card) => {
    const $card = $(card);
    const link = $card.find('h3 a');
    const priceText = $card.find('.price_color').text();          // "£51.77"
    const ratingWord = ($card.find('.star-rating').attr('class') ?? '')
      .replace('star-rating', '').trim();                          // "Three"

    return {
      title: link.attr('title'),                    // full title; the link text is cut off
      price: priceText ? Number(priceText.replace(/[^0-9.]/g, '')) : null,
      currency: priceText.includes('£') ? 'GBP' : null,
      rating: RATINGS[ratingWord] ?? null,
      inStock: $card.find('.instock.availability').length > 0,
      url: new URL(link.attr('href'), pageUrl).href, // hrefs are relative, and differ by page
    };
  }).get();

  const nextHref = $('li.next a').attr('href');
  const nextUrl = nextHref ? new URL(nextHref, pageUrl).href : null;
  return { books, nextUrl };
}

输出结果无需二次清理。价格将转换为数字,而非字符串 "£51.77"。星级评分包含在类名中(star-rating Three),因此通过一个小型映射即可将其转换为 1 到 5 的数值,任何意外情况都会被处理为 null ,而非错误的猜测。而且每个链接都会经过 new URL(),因为该网站的 href 属性是相对路径。

保存第一页目录页面的副本,并在不连接网络的情况下对其运行解析器:

curl -o fixtures/books-page-1.html "https://books.toscrape.com/catalogue/page-1.html"
// static-fixture.js: parse a saved page, no network
import { readFile } from 'node:fs/promises';
import { parseBooks } from './parse-books.js';

const html = await readFile('fixtures/books-page-1.html', 'utf8');
const { books, nextUrl } = parseBooks(html, 'https://books.toscrape.com/catalogue/page-1.html');
console.log(books.length, 'books');
console.log(books[0]);
console.log('next:', nextUrl);

输出:

20 books
{
  title: 'A Light in the Attic',
  price: 51.77,
  currency: 'GBP',
  rating: 3,
  inStock: true,
  url: 'https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html'
}
next: https://books.toscrape.com/catalogue/page-2.html

以同样的方式保存你计划抓取的每种页面类型,每 curl -o ,每次操作间隔一秒。这些文件日后将成为你的测试数据集。Cheerio 还提供了更多功能,包括 extract() 从script标签中读取JSON。这两项内容均在我们的完整Cheerio指南中有所涵盖,Cheerio的文档中也列出了完整的API。

如何找到正确的 CSS 选择器?

在浏览器中打开页面,右键点击目标数据,选择“检查”。 找到每个记录中重复出现一次的元素(例如带有类名的商品卡片),并在开发者工具控制台中使用 `document.querySelectorAll()` 测试你的选择器。建议优先使用简短的基于类的选择器,而非从开发者工具复制的冗长路径——后者在布局发生变化时会失效。

在 books.toscrape.com 上,右键单击任意书名并选择“检查”。每本书都位于一个 <article class="product_pod">中,因此这就是重复出现的元素。在“控制台”选项卡中进行测试:

document.querySelectorAll('article.product_pod').length   // 20
document.querySelector('article.product_pod h3 a').textContent   // "A Light in the ..."
document.querySelector('article.product_pod h3 a').title         // "A Light in the Attic"

第二行展示了一个容易被忽略的陷阱。长书名在可见的链接文本中会被截短,但完整的书名位于链接的 title 属性中。提取数据时,请务必将其与页面实际含义进行比对,而不仅仅是表面显示的内容。评分机制也是如此:卡片中任何地方都没有“3”这个数字,只有类名 star-rating Three.

还要区分“查看源代码”和“检查”的区别。“查看源代码”显示的是服务器发送的 HTML,这正是 fetch 接收的内容。而“检查”功能则显示脚本执行后的实时 DOM。当某个选择器在“检查”中有效,但在 Node.js 中却返回空结果时,说明该内容是由 JavaScript 生成的,下文将说明如何处理。

将选择器锚定在类和属性上,而非位置(li.next a,而非 ul > li:nth-child(2) > a)。此外,CSS ID 不能以数字开头(除非进行转义),因此一个 ID 为 id="2015" 需要 [id="2015"] 而非 #2015。对于其他所有情况,请随时查阅完整的选择器参考文档。

如何“礼貌地”抓取多个页面?

首先检查 robots.txt,然后跟随每个页面的“下一页”链接,而不是猜测 URL 模式。维护一份已访问 URL 列表,以防止坏链接导致循环;通过稳定键去除重复记录,并在请求之间留出间隔时间。遵守网站自身的速率限制规则和 Retry-After 标头,并在开发过程中限制总页面数。

从 robots.txt 开始。这个简易读取器会收集 Disallow 规则,用于 User-agent: * 规则。它支持简单的前缀规则,而 robots.txt 标准(RFC 9309)则定义了通配符和 Allow 优先级,因此对于依赖这些功能的网站,请使用完整的解析器。根据该标准,4xx响应表示无规则适用,而5xx响应则表示应将整个网站视为禁止访问区域。

// robots.js: a minimal robots.txt check for the "User-agent: *" group.
// Good enough for simple prefix rules; use a full RFC 9309 parser for wildcards or Allow precedence.
export async function disallowedPaths(origin) {
  const res = await fetch(new URL('/robots.txt', origin), { signal: AbortSignal.timeout(10_000) });
  if (res.status >= 500) throw new Error(`robots.txt HTTP ${res.status}: treat the site as off-limits`);
  if (!res.ok) return [];                       // 4xx: no robots.txt, so nothing is disallowed
  let inStar = false;
  const rules = [];
  for (const raw of (await res.text()).split('\n')) {
    const line = raw.split('#')[0].trim();
    const [key, ...rest] = line.split(':');
    const value = rest.join(':').trim();
    if (/^user-agent$/i.test(key)) inStar = value === '*';
    else if (inStar && /^disallow$/i.test(key) && value) rules.push(value);
  }
  return rules;
}

export const isAllowed = (url, rules) => !rules.some((p) => new URL(url).pathname.startsWith(p));

爬虫从第一个目录页面开始,沿着下一个链接爬行直到没有链接为止,每次请求之间等待一秒,并将结果保存为 JSON 和 CSV 格式。

// crawl-books.js: follow "next" links politely and save JSON + CSV
import { writeFile } from 'node:fs/promises';
import { fetchHtml } from './fetch-html.js';
import { parseBooks } from './parse-books.js';
import { disallowedPaths, isAllowed } from './robots.js';

const START = 'https://books.toscrape.com/catalogue/page-1.html';
const MAX_PAGES = Number(process.env.MAX_PAGES ?? 5);
const DELAY_MS = 1000;                           // no published limit, so stay at one request per second

const rules = await disallowedPaths(START);
const seen = new Set();                          // stops loops if a "next" link points backward
const byUrl = new Map();                         // dedupe records, not just pages

for (let url = START, page = 1; url && page <= MAX_PAGES && !seen.has(url); page++) {
  if (!isAllowed(url, rules)) { console.log('robots.txt disallows', url); break; }
  seen.add(url);
  const { books, nextUrl } = parseBooks(await fetchHtml(url), url);
  for (const b of books) byUrl.set(b.url, b);
  console.log(`page ${page}: ${books.length} books (${url})`);
  url = nextUrl;
  if (url) await new Promise((r) => setTimeout(r, DELAY_MS));
}

const books = [...byUrl.values()];
await writeFile('out/books.json', JSON.stringify(books, null, 2));
const cols = Object.keys(books[0]);
const cell = (v) => `"${String(v ?? '').replaceAll('"', '""')}"`;
await writeFile('out/books.csv',
  [cols.join(','), ...books.map((b) => cols.map((c) => cell(b[c])).join(','))].join('\n') + '\n');
console.log(`saved ${books.length} unique books; robots.txt disallows: ${rules.join(', ') || 'nothing'}`);

以下是采用默认五页上限时的输出结果:

page 1: 20 books (https://books.toscrape.com/catalogue/page-1.html)
page 2: 20 books (https://books.toscrape.com/catalogue/page-2.html)
page 3: 20 books (https://books.toscrape.com/catalogue/page-3.html)
page 4: 20 books (https://books.toscrape.com/catalogue/page-4.html)
page 5: 20 books (https://books.toscrape.com/catalogue/page-5.html)
saved 100 unique books; robots.txt disallows: nothing

运行时使用 MAX_PAGES=100 node crawl-books.js 运行时,它会在第50页后自动停止,因为最后一页没有“下一页”链接:

page 49: 20 books (https://books.toscrape.com/catalogue/page-49.html)
page 50: 20 books (https://books.toscrape.com/catalogue/page-50.html)
saved 1000 unique books; robots.txt disallows: nothing

该网站展示了每项安全措施存在的理由。主页上的下一个链接是 catalogue/page-2.html,但在第2页上它只是 page-3.html。将该链接附加到网站根目录后,结果为 https://books.toscrape.com/page-3.html,这会返回 404 错误。 new URL(href, pageUrl) 会根据链接来源页面解析每个链接,因此结果总是正确的。

主页和 catalogue/page-1.html 也分别通过两个 URL 提供相同的 20 本书,且两者的下一个链接都指向第 2 页。如果爬虫从这两个 URL 开始抓取,或者通过“上一页”链接回溯到第 1 页,那么针对这 20 本书,就能节省 40 行数据。 已访问集合可防止重复页面,而按书籍 URL 作为键存储记录则可避免重复行。如需了解此类更多技巧,请阅读我们关于项目生命周期中数据抓取最佳实践的指南。

一次可以运行多少个请求?

并发处理需根据具体网站情况决定。当网站公布了速率限制时,请严格遵守,即使这意味着每次只能发送一个请求。若未公布限制,请为每个主机设置较低的并行请求上限,保持间隔,并在遇到 429 状态码时自动降频。如果因速度过快导致被封,加快速度通常无济于事。

books.toscrape.com 未公布限制,因此该脚本使用 p-limit(npm install p-limit),以获取每本书的 UPC 码和精确库存数量:

// details.js: enrich books from their detail pages, at most 2 requests at a time
import { readFile, writeFile } from 'node:fs/promises';
import * as cheerio from 'cheerio';
import pLimit from 'p-limit';
import { fetchHtml } from './fetch-html.js';

const books = JSON.parse(await readFile('out/books.json', 'utf8')).slice(0, 10);
const limit = pLimit(2);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const results = await Promise.allSettled(books.map((book) => limit(async () => {
  const $ = cheerio.load(await fetchHtml(book.url));
  await sleep(500);                               // keep a pause even with two workers
  return {
    ...book,
    upc: $('th:contains("UPC")').next('td').text(),
    stockCount: Number($('p.instock.availability').text().match(/\d+/)?.[0] ?? 0),
  };
})));

const ok = results.filter((r) => r.status === 'fulfilled').map((r) => r.value);
console.log(`${ok.length} enriched, ${results.length - ok.length} failed`);
console.log(ok[0]);
await writeFile('out/books-details.jsonl', ok.map((b) => JSON.stringify(b)).join('\n') + '\n');

输出:

10 enriched, 0 failed
{
  title: 'A Light in the Attic',
  price: 51.77,
  currency: 'GBP',
  rating: 3,
  inStock: true,
  url: 'https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html',
  upc: 'a897fe39b1053632',
  stockCount: 22
}

Promise.allSettled() 确保单个页面失败不会导致其余九个结果被丢弃。

如何将抓取的数据保存为 JSON 和 CSV 格式?

JSON 会保留数据类型:数字保持为数字,而 null 保持 null。CSV是电子表格所需的格式,但需要加引号,因此爬虫会将每个单元格用引号包裹,并把值内的任何引号加倍。空值会变成空单元格。

title,price,currency,rating,inStock,url
"A Light in the Attic","51.77","GBP","3","true","https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
"Tipping the Velvet","53.74","GBP","1","true","https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html"

对于大型任务,请采用每行一个 JSON 对象的格式(JSON Lines),正如 details.js ,这样即使中途发生崩溃,也不会导致整个文件丢失。如果您的数据源是表格而非卡片,请参阅我们的指南,了解如何将 HTML 表格导出为干净的 CSV 文件。

如何判断页面是否需要 JavaScript 渲染?

使用普通的 fetch() 加载页面并运行你的选择器。如果选择器未找到任何内容,但浏览器显示了数据,说明 JavaScript 在加载完成后生成了该内容。然后打开开发者工具,选择“网络”选项卡,按 Fetch/XHR 过滤,并重新加载或点击页面:返回数据的请求通常比浏览器更易于使用。

您可以将此检查自动化。此脚本会统计原始 HTML 和渲染后的页面中选择器的匹配项,并列出页面加载过程中发出的每个 fetch 或 XHR 请求:

// check-js.js: does the selector match in the raw HTML and in the rendered page?
import * as cheerio from 'cheerio';
import { chromium } from 'playwright';
import { fetchHtml } from './fetch-html.js';

const url = process.argv[2] ?? 'https://books.toscrape.com/catalogue/page-1.html';
const selector = process.argv[3] ?? 'article.product_pod';

const $ = cheerio.load(await fetchHtml(url));
const inHtml = $(selector).length;

const browser = await chromium.launch();
try {
  const page = await browser.newPage();
  const dataRequests = [];
  page.on('request', (req) => {
    if (['xhr', 'fetch'].includes(req.resourceType())) dataRequests.push(req.url());
  });
  await page.goto(url, { waitUntil: 'networkidle' });
  const rendered = await page.locator(selector).count();

  console.log(`raw HTML: ${inHtml} | rendered: ${rendered} | fetch/XHR requests: ${dataRequests.length}`);
  dataRequests.forEach((u) => console.log('  ', u));
  console.log(inHtml > 0 ? 'The data is in the HTML: use fetch + Cheerio.'
    : dataRequests.length ? 'JavaScript loads the data: try calling the request above.'
    : 'JavaScript builds the data: render the page or look for JSON in a <script>.');
} finally {
  await browser.close();
}

书籍目录的输出结果:

raw HTML: 20 | rendered: 20 | fetch/XHR requests: 0
The data is in the HTML: use fetch + Cheerio.

这就是你期望的答案:服务器将每本书的信息都发送到了 HTML 中,因此使用浏览器只会徒增时间。在为新网站编写爬虫之前,请先使用另一个 URL 和选择器(node check-js.js <url> "<selector>"),再为新网站编写爬虫程序。

当原始计数为 0 时,数据隐藏在以下两个位置之一:可能是 <script> 标签内的 JSON,Cheerio 可以读取并 JSON.parse() 解码。或者,JavaScript 在页面加载后会请求该数据,该请求会出现在脚本列表和“网络”选项卡中。无论哪种情况,你通常都可以跳过浏览器。关于渲染型浏览器的运作原理,请参阅无头浏览器的工作原理。

如何在不使用浏览器的情况下抓取 JavaScript 数据?

在开发者工具的“网络”选项卡中找到页面用于获取数据的请求,复制其 URL 和参数,然后使用 fetch() 自行调用该请求。这样,您就能获得 JSON 数据,无需解析 HTML,也无需运行浏览器。请保持相同的速率限制和用户代理,并且仅调用页面本身用于获取公开数据的端点。

在任何网站上,操作步骤都是一样的:

  1. 打开开发者工具,选择“网络”标签页,并按“Fetch/XHR”进行筛选。
  2. 刷新页面,或点击会加载数据的按钮、标签页或“加载更多”链接。
  3. 点击每个请求并检查其“响应”选项卡,直到找到包含您所需记录的那个。
  4. 记下 URL 以及发生变化的查询参数(通常是 page, offset,或 cursor),以及任何指示何时停止的字段,例如 has_next 或一个空数组。
  5. 在 Node.js 中使用 URLSearchParams ,并在循环中调用它。

分页的 JSON 端点通常最终会呈现如下形式。将你找到的端点和字段代入其中:

// fetch-json-pages.js: call a paged JSON endpoint you found in the Network tab
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function fetchAllPages(endpoint, { maxPages = 50, delayMs = 1000 } = {}) {
  const items = [];
  for (let page = 1; page <= maxPages; page++) {
    const url = `${endpoint}?${new URLSearchParams({ page })}`;
    const res = await fetch(url, {
      headers: { 'User-Agent': 'node-scraper-tutorial/1.0 (+https://example.com/contact)' },
      signal: AbortSignal.timeout(15_000),
    });
    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
    const data = await res.json();
    items.push(...data.items);           // the array that holds the records
    if (!data.has_next) break;           // or: if (data.items.length === 0) break;
    await sleep(delayMs);
  }
  return items;
}

如果存在,这是最快且最稳定的方法:当网站重新设计 HTML 时,JSON 字段很少会发生变化。在处理过程中进行规范化,就像 Cheerio 解析器那样:修剪字符串、转换数字,并将缺失的键转换为 null 或 false 。

也要知道何时该停手。需要登录、会话令牌或签名参数的接口不属于公开数据,而绕过这些验证就不再是爬虫行为。将其视为“停车标志”,而非“谜题”。

如何使用 Playwright 抓取由 JavaScript 渲染的页面?

使用 Playwright 启动 Chromium,打开页面,并执行用户会执行的操作,例如点击链接。 等待数据而非进入休眠状态:waitForURL() 会捕获点击触发的导航操作,而定位器的 waitFor() 会等待直到数据行出现。然后使用 evaluateAll() 读取页面中的数据行,并在 finally 代码块中关闭浏览器。

当数据仅在点击、滚动、输入或其他脚本驱动的操作后才会出现时,请使用浏览器。此脚本像读者一样浏览 books.toscrape.com:它打开首页,点击“悬疑”分类,阅读每张卡片,并点击“下一页”直到该分类内容全部浏览完毕。

// playwright-books.js: open a category like a user, read every page of results
import { chromium } from 'playwright';

const browser = await chromium.launch();               // headless by default
try {
  const page = await browser.newPage({ userAgent: 'node-scraper-tutorial/1.0 (+https://example.com/contact)' });
  await page.route('**/*.{jpg,jpeg,png}', (route) => route.abort());   // skip images you won't use
  await page.goto('https://books.toscrape.com/');

  await page.getByRole('link', { name: 'Mystery', exact: true }).click();
  await page.waitForURL('**/category/books/mystery_3/**');

  const books = [];
  for (;;) {
    const cards = page.locator('article.product_pod');
    await cards.first().waitFor();                     // wait for the data, not a fixed sleep
    books.push(...await cards.evaluateAll((els) => els.map((el) => ({
      title: el.querySelector('h3 a').getAttribute('title'),
      price: Number(el.querySelector('.price_color').textContent.replace(/[^0-9.]/g, '')),
      url: el.querySelector('h3 a').href,               // the browser resolves it for you
    }))));

    const next = page.locator('li.next a');
    if (await next.count() === 0) break;
    const current = page.url();
    await next.click();
    await page.waitForURL((u) => u.href !== current);  // the click navigates to the next page
    await page.waitForTimeout(1000);                   // politeness delay between pages
  }
  console.log(books.length, 'mystery books; last page:', page.url());
  console.log(books[0]);
} finally {
  await browser.close();
}

输出:

32 mystery books; last page: https://books.toscrape.com/catalogue/category/books/mystery_3/page-2.html
{
  title: 'Sharp Objects',
  price: 47.82,
  url: 'https://books.toscrape.com/catalogue/sharp-objects_997/index.html'
}

在任何网站上,这里有几个关键选择。 getByRole('link', { name: 'Mystery', exact: true }) 以用户所见的方式查找链接,因此即使类名发生变化也能正常工作。 waitForURL() 每次点击后都会确保读取新页面,而非旧页面。 cards.first().waitFor() 该脚本会等待直到数据出现,这比固定延迟更优——固定延迟在网站运行缓慢时可能过短,而在运行快速时则会浪费时间。Playwright的自动等待功能还会在点击前检查元素是否可见且状态稳定。

在 evaluateAll()中,代码在页面内运行,因此 a.href 位置已经是绝对的。使用 page.route() 可为您和网站节省带宽。唯一剩下的固定等待时间是出于礼貌而设计的延迟,而非对加载时间的猜测。

当点击触发数据请求而非导航时,请将点击事件包裹起来并 page.waitForResponse() 封装在 Promise.all() ,以确保在开始监听之前响应不会到达。关于代理、无限滚动和请求拦截,请参阅我们的 Playwright 深度指南。

在 Puppeteer 中,相同的抓取代码是什么样子的?

Puppeteer 通过略有不同的调用实现了相同的流程: page.click() 配合 page.waitForNavigation(),然后 page.waitForSelector() 并 page.$$eval() 来读取卡片。Puppeteer 25 需要 Node.js 22.12 或更高版本。

// puppeteer-books.js: the same category in Puppeteer
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.setUserAgent('node-scraper-tutorial/1.0 (+https://example.com/contact)');
  await page.goto('https://books.toscrape.com/');

  await Promise.all([
    page.waitForNavigation(),
    page.click('a[href*="category/books/mystery_3"]'),
  ]);
  await page.waitForSelector('article.product_pod');

  const books = await page.$$eval('article.product_pod h3 a', (links) => links.map((a) => ({
    title: a.getAttribute('title'),
    url: a.href,
  })));
  console.log(books.length, 'books on page 1;', 'first:', books[0].title);
} finally {
  await browser.close();
}

输出:

20 books on page 1; first: Sharp Objects

请注意 Promise.all() 点击操作:请在点击前先等待导航完成,否则加载速度较快的页面可能会在 Puppeteer 开始监听之前就加载完毕。有关截图、PDF 以及更多 Puppeteer 用法示例,请参阅我们的《Puppeteer 和 Node.js 指南》。

进行网页抓取时,应该使用 Playwright 还是 Puppeteer?

新建抓取程序时建议使用 Playwright:它能自动等待元素加载,通过单一 API 驱动 Chromium、Firefox 和 WebKit,并且能很好地处理多个隔离会话。 如果您的团队已有 Puppeteer 代码,或者需要 Chrome 专用的工具,请使用 Puppeteer。在数据抓取方面,两者渲染的页面效果相同,因此应根据对 API 的熟悉程度来选择,而非仅凭速度宣传。


Playwright

Puppeteer

浏览器

Chromium、Firefox、WebKit

Chrome、Firefox

等待

定位器会自动等待元素就绪

显式 waitForSelector() 及类似

隔离会话

浏览器上下文,内置

内置浏览器上下文

捕获数据请求

page.waitForResponse()

page.waitForResponse()

编程语言

JavaScript/TypeScript、Python、Java、.NET

JavaScript/TypeScript

npm 最新版本(2026年10月)

1.64.1

25.16.0

何时选用

新项目、跨浏览器检测

现有 Puppeteer 代码、Chrome DevTools 协议相关工作

这两个项目都是开源且积极维护的,并且都会为你下载相应的浏览器。实际的区别体现在日常编码中:Playwright 的定位器会自动等待并重试,因此脚本需要更少的显式等待。如果你已经在生产环境中运行 Puppeteer,那么从爬取的角度来看,没有必要重写它。

如何使用爬虫 API 从 Node.js 爬取被屏蔽的页面?

保留你的解析器,只需修改请求部分。将目标 URL 连同从环境变量中获取的密钥一起发送至 WebScrapingAPI 的 Scraper API;当页面需要 JavaScript 时,添加 `render_js=1`;若需获取特定地区的内容,则添加 `country` 参数。 你将获取到的页面 HTML 传递给之前编写的同一 Cheerio 函数。

对于练习站点,你不需要这样做。 当真实目标站点开始返回 403 错误或出现重试也无法解决的验证页面时,当内容因国家/地区而异时,或者当你不想运行大量浏览器来批量渲染页面时,才需要使用此方法。如果只是偶尔遇到错误,请先尝试其他方法来减少被封锁的情况。

Scraper API 接受一个 URL 并返回页面,而 WebScrapingAPI 则负责处理代理、重试以及可选的 JavaScript 渲染。 wsaFetch() 是 fetchHtml():

// wsa-fetch.js: same job as fetchHtml(), but WebScrapingAPI's Scraper API does the fetching
const ENDPOINT = 'https://api.webscrapingapi.com/v2';
const RETRY = new Set([429, 500, 503]);          // documented as "retry later"
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export function buildWsaUrl(url, { renderJs = false, country } = {}) {
  const apiKey = process.env.WSA_API_KEY;
  if (!apiKey) throw new Error('Set WSA_API_KEY in your environment first.');
  const params = new URLSearchParams({ api_key: apiKey, url });   // encodes the target URL
  if (renderJs) params.set('render_js', '1');
  if (country) params.set('country', country);                     // two-letter code, e.g. "us"
  return `${ENDPOINT}?${params}`;
}

export async function wsaFetch(url, { renderJs = false, country, retries = 2 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(buildWsaUrl(url, { renderJs, country }), {
      signal: AbortSignal.timeout(130_000),   // the API's own timeout tops out at 120 s
    });
    if (res.ok) return res.text();
    if (res.status === 422 && !renderJs) {    // scrape not completed: try once with rendering
      renderJs = true;
      continue;
    }
    if (!RETRY.has(res.status) || attempt >= retries) {
      throw new Error(`WebScrapingAPI HTTP ${res.status}: ${await res.text()}`);
    }
    await sleep(2000 * 2 ** attempt);
  }
}

该密钥来自 process.env.WSA_API_KEY ,且绝不会出现在代码中。 URLSearchParams 会对目标 URL 进行编码,这一点很重要:如果目标 URL 本身包含查询字符串,未编码的 ? 或 & 会被解读为API参数。客户端超时时间略高于API规定的120秒上限,且仅对API文档中明确标注为临时状态的响应进行重试。JavaScript渲染和地理定位不会消耗额外积分,但渲染速度较慢,因此仅当HTML中缺少您的数据时才应启用该功能。

替换 fetch 层并保持 parseBooks() 完全保持原样:

// crawl-books-wsa.js: swap the fetch layer, keep parseBooks() unchanged
import { wsaFetch, buildWsaUrl } from './wsa-fetch.js';
import { parseBooks } from './parse-books.js';

const url = 'https://books.toscrape.com/catalogue/page-1.html';
const opts = { country: 'us' };                    // add renderJs: true only if the HTML lacks the data

if (process.argv.includes('--dry-run')) {
  const redact = (u) => u.replace(/api_key=[^&]+/, 'api_key=REDACTED');
  console.log(redact(buildWsaUrl(url, opts)));
  console.log(redact(buildWsaUrl(url, { ...opts, renderJs: true })));
} else {
  const { books, nextUrl } = parseBooks(await wsaFetch(url, opts), url);
  console.log(books.length, 'books; first:', books[0]?.title, '; next:', nextUrl);
}

将该键放入一个 .env 包含 WSA_API_KEY=your_key_here,并添加 .env 到 .gitignore,并使用 Node 的内置 --env-file 参数加载该文件,这样就无需使用 dotenv 包:

node --env-file=.env crawl-books-wsa.js --dry-run
node --env-file=.env crawl-books-wsa.js

干跑会打印请求 URL 并屏蔽密钥,以便您查看编码:

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fbooks.toscrape.com%2Fcatalogue%2Fpage-1.html&country=us
https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fbooks.toscrape.com%2Fcatalogue%2Fpage-1.html&render_js=1&country=us

实际运行时会将返回的 HTML 传递给同一个解析器:

20 books; first: A Light in the Attic ; next: https://books.toscrape.com/catalogue/page-2.html

错误信息会明确显示。如果没有环境变量,脚本会在 Error: Set WSA_API_KEY in your environment first. ,且返回错误的键值时会返回 WebScrapingAPI HTTP 401: {"error":"Invalid API key"} ,而非返回空结果。有关每个参数和错误代码的详细信息,请参阅我们的完整 Scraper API 指南。需要点击或输入操作的页面,使用托管浏览器比 fetch 更合适,下一节将对此进行介绍。

您应该使用哪种 JavaScript 抓取方法?

当数据位于 HTML 中时,请使用 fetch 和 Cheerio。当 JavaScript 从 JSON 端点加载数据时,请调用该端点。当必须在页面上点击、滚动或等待时,请使用 Playwright。当代码块、位置或大规模渲染导致本地 fetch 不可靠时,请使用爬虫 API。大多数项目会结合使用其中两种方法。

使用场景

使用

原因

数据位于“查看源代码”中

fetch + Cheerio

速度最快,组件最少

大量页面

fetch + Cheerio 支持 robots.txt、延迟、重试和去重

礼貌且可重启

JavaScript 通过 XHR 加载数据,您可以调用

fetch 加载数据

无需解析,无需浏览器

数据以 JSON 格式封装在 <script>

Cheerio + JSON.parse

无需浏览器

点击、滚动或页面等待

Playwright(或 Puppeteer)

真实浏览器,真实事件

403错误、验证页面、特定国家/地区的内容或大规模渲染

来自 fetch

托管代理、重试和渲染;解析器保持不变

带操作的托管浏览器会话

浏览器 API

无需自行运行Chrome的会话

对于每个新网站,请按顺序执行以下检查:

  1. “查看源代码”中是否显示数据?请使用 fetch 和 Cheerio。
  2. 数据是否通过 Fetch/XHR 请求获取?请调用该请求。
  3. 是否需要点击、滚动或等待操作?请使用 Playwright。
  4. 是否被屏蔽,或者内容具有地域限制?请通过 Scraper API 进行抓取。
  5. 是否需要能够点击和输入的托管浏览器会话?请使用 Browser API。

如何测试 Node.js 爬虫,以防止其无声崩溃?

将每种页面类型保存为 HTML 文件,并使用 Node 内置的测试运行器对其解析器进行测试。验证行数、关键字段的类型以及下一页链接。当网站更改布局时,测试会明确报错,而不是让爬虫默默地保存空数据或错误数据。

当网站发生变化时,爬虫很少会直接崩溃。它们会继续运行,并保存空字符串、零值,甚至什么都不保存。 fixture 测试能在错误数据进入数据库之前就将其拦截。将最后一个商品目录页面和一个分类页面保存到你之前保存的首页旁边:

curl -o fixtures/books-page-50.html "https://books.toscrape.com/catalogue/page-50.html"
sleep 1
curl -o fixtures/mystery-page-1.html "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html"

然后使用以下代码编写测试: node:test 和 node:assert/strict。无需额外包:

// parse-books.test.js: run with `node --test`; uses saved pages, no network
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';
import { parseBooks } from './parse-books.js';

const BASE = 'https://books.toscrape.com/catalogue/';
const load = (name) => readFile(`fixtures/${name}`, 'utf8');

test('parses 20 typed records and the next link', async () => {
  const { books, nextUrl } = parseBooks(await load('books-page-1.html'), `${BASE}page-1.html`);
  assert.equal(books.length, 20);
  for (const b of books) {
    assert.ok(b.title.length > 0);
    assert.ok(Number.isFinite(b.price) && b.price > 0, b.title);
    assert.ok(b.rating >= 1 && b.rating <= 5, b.title);
  }
  assert.equal(nextUrl, `${BASE}page-2.html`);
});

test('resolves ../../../ links on category pages', async () => {
  const url = `${BASE}category/books/mystery_3/index.html`;
  const { books } = parseBooks(await load('mystery-page-1.html'), url);
  assert.equal(books[0].url, `${BASE}sharp-objects_997/index.html`);
});

test('the last page has no next link', async () => {
  const { books, nextUrl } = parseBooks(await load('books-page-50.html'), `${BASE}page-50.html`);
  assert.equal(books.length, 20);
  assert.equal(nextUrl, null);
});

运行 node --test:

✔ parses 20 typed records and the next link
✔ resolves ../../../ links on category pages
✔ the last page has no next link
ℹ tests 3
ℹ pass 3
ℹ fail 0

第二个测试用于防范相对链接的陷阱:分类页面通过 ../../../sharp-objects_997/index.html,而处理不当的解析器仍会返回 20 条记录,只是 URL 会失效。请按计划重新保存测试数据,并对比解析后的输出结果,这样你就能在用户发现之前察觉到布局变化。Node 的内置测试运行器还支持监视模式、代码覆盖率和快照功能。

JavaScript 和 Python 哪个更适合网络爬虫?

两者都表现良好。 如果你的团队已经使用 JavaScript 开发,或者需要自动化浏览器操作,或者爬虫运行在 Node.js 服务中,请选择 JavaScript。如果数据需要 feeding 到 pandas、Notebook 或机器学习中,或者你想使用 Scrapy 的爬取框架,请选择 Python。网站采取的防御措施远比你选择的语言重要得多。

这些构建模块几乎是一一对应的。原生 fetch 对应 Python 的 HTTP 客户端,Cheerio 扮演快速 HTML 解析器的角色,而 Playwright 在两种语言中均存在且 API 几乎相同。JavaScript 的优势在于浏览器自动化,以及从页面脚本到后端全程使用单一语言。Python 的优势则在于下游的分析栈,以及适用于超大规模任务的成熟爬取框架。 如果你的团队习惯使用 Python,请阅读我们关于使用 Python 进行网页抓取的指南。本指南中的决策原则同样适用。

如何使用 JavaScript 负责任地进行数据抓取?

在爬取前请阅读网站的使用条款和 robots.txt 文件,保持较低的请求频率,使用真实的用户代理标识您的爬虫,并仅收集您所需的字段。除非有合法依据,否则请避免收集个人数据;切勿在未经许可的情况下爬取登录后的内容;如果网站提供官方 API,请务必使用该 API。

上述大部分要求在您的代码中已有所体现。 robots.js 在抓取第一页之前会先检查规则。一秒的延迟和两个工作线程的上限能确保你的请求负载保持在较低水平。 User-Agent 请求头标明了您的爬虫身份,并为网站提供了联系您的途径。而解析器仅保留您所需的字段,且经过类型转换和清理,而非存储整页内容。

其余部分则取决于你的判断。公共页面并非任人随意抓取:服务条款、版权法和隐私法仍然适用,特别是涉及个人数据时。请阅读我们的《负责任的网络数据原则》以及关于“网络抓取是否合法”的概述,并在为商业项目进行抓取前寻求法律建议。

常见问题

Node.js 适合用于网页抓取吗?

是的。Node.js 无需线程即可同时处理大量网络请求,内置 fetch 模块,并支持运行领先的浏览器自动化工具 Playwright 和 Puppeteer。Cheerio 能够使用熟悉的 CSS 选择器快速解析 HTML。如果您的团队已经使用 JavaScript 编程,或者爬虫在 Node.js 服务中运行,那么 Node.js 是一个绝佳的选择。

为什么 Cheerio 会返回一个空数组?

通常是因为数据不在请求收到的 HTML 中。JavaScript 会在页面加载后在浏览器中添加这些数据,因此 Cheerio 无法获取到它们。请在浏览器中查看源代码:如果那里缺少数据,请在“网络”选项卡中查找 JSON 请求,或者使用 Playwright 渲染该页面。

Cheerio 和 Playwright 有什么区别?

Cheerio 解析你已经获取的 HTML。它速度快且轻量,但无法运行 JavaScript 或执行任何点击操作。Playwright 驱动真实的浏览器,因此它能看到脚本运行后的页面,并能进行点击、滚动和等待操作。默认情况下使用 Cheerio,仅当页面需要浏览器时才使用 Playwright。

JavaScript 能抓取动态网站吗?

可以。对于通过 JavaScript 加载数据的页面,首先查找页面发出的 JSON 请求,并使用 `fetch()` 调用它,这样速度更快且更稳定。当需要在页面上进行点击、滚动或等待操作时,请使用 Playwright 或 Puppeteer 在无头浏览器中加载页面,并读取渲染后的元素。

如何在使用 Node.js 进行抓取时避免被封禁?

放慢请求速度,发送真实的用户代理,在 Retry-After 延迟结束后重试 429 和 503 响应,并缓存页面以避免重复抓取。 如果网站仍然返回 403 错误或验证页面,请将请求路由到一个管理代理和渲染的爬虫 API,并保持您的 Cheerio 解析器不变。

进行网页抓取时,我还需要 Axios 或 node-fetch 吗?

不需要。Node.js 18 及更高版本已内置 fetch 功能,且在所有受支持的版本中均稳定运行,因此新建的爬虫无需额外的 HTTP 库。Axios 和 Got 依然可用,并提供了拦截器和内置重试等便利功能。 如果您的项目已经使用了它们,请继续保留。否则,原生 `fetch` 配合一个小型重试辅助工具就足够了。

在 Node.js 爬虫中应如何存储 API 密钥?

将密钥保存在 WSA_API_KEY 等环境变量中,并通过 process.env 读取。在本地开发时,将其写入 .env 文件,运行 node --env-file=.env,并将 .env 添加到 .gitignore 中。 切勿将密钥直接写入代码、共享的 URL 或前端 JavaScript 中,以免被任何访问者读取。

我可以使用 TypeScript 抓取网站吗?

可以。本指南中的所有示例均可在 TypeScript 中运行,因为 Cheerio、Playwright 和 Puppeteer 都自带了相应的类型定义。最新版本的 Node.js 可以通过去除类型信息直接运行 .ts 文件,或者你可以使用 tsx 等运行器。为记录结构添加类型定义还能在保存错误数据之前捕获解析错误。

如何抓取带有无限滚动的页面?

打开开发者工具,滚动页面,并在“网络”标签页中观察加载每批新数据的请求。该请求通常会带有一个页码或光标位置,因此你可以通过 fetch() 循环调用该请求,直到报告无更多结果为止。如果没有可用的请求,则使用 Playwright 进行滚动并读取行数据。

使用 JavaScript 进行网页抓取是否合法?

编程语言本身不会改变法律状况。抓取公开数据通常是合法的,但这取决于网站的条款、数据类型以及当地法律,特别是涉及个人数据和受版权保护的内容时。请遵守 robots.txt 规则,避免在没有合法依据的情况下获取个人数据,并为商业项目寻求法律建议。

保留您的 Node.js 解析器,将棘手的页面交由他人处理

当网站开始屏蔽您或需要 JavaScript 时,您的 Cheerio 解析器无需更改。将您的 fetch 请求指向 WebScrapingAPI 的 Scraper API,并在 Node.js 中继续解析。JavaScript 渲染和地理定位不会消耗额外积分,且失败的请求不会计费。 比较 Scraper API 套餐,可从 5,000 次请求的免费试用开始。

关于作者

Robert Sfichi, 全栈开发工程师 @ WebScrapingAPI

Robert Sfichi

全栈开发工程师

罗伯特·斯菲奇是 WebScrapingAPI 的团队成员,致力于产品开发,并协助构建可靠的解决方案,以支持该平台及其用户。

开始构建

准备好扩展您的数据收集规模了吗?

加入2,000多家企业,使用WebScrapingAPI在无需任何基础设施开销的情况下,以企业级规模提取网络数据。