如何使用 Puppeteer 和 NodeJS 进行网络抓取 2026 指南

当您调用 puppeteer.launch()时，该库会启动一个 Chromium（或 Chrome）进程，并通过 Chrome DevTools 协议（CDP）与其建立连接。CDP 是一个基于 WebSocket 的接口，它暴露了几乎所有的浏览器功能：DOM 检查、网络监控、输入模拟等。您的 Node.js 脚本通过此套接字发送命令，Chromium 则返回结果。

这种架构意味着 Puppeteer 并非简化的浏览器模拟器。它运行的是真正的 V8 JavaScript 引擎、真正的渲染引擎以及真正的网络堆栈。依赖于 fetch、Web Workers 或 Shadow DOM 的网页，其行为表现与在用户浏览器中完全一致。正因如此，当您需要在动态渲染内容的网站上使用 Puppeteer 和 Node.js 进行网页抓取时，它便成为极具可靠性的选择。

Puppeteer 同时支持无头模式（无可见窗口，速度更快，适合服务器端）和有头模式（可见的浏览器窗口，便于调试）。默认情况下，Puppeteer 最新版本已内置 Chromium 二进制文件，因此无需单独安装浏览器。若想更深入地了解无头浏览器，有许多优秀的资源可详细解释其架构和常见用例。

在编写任何爬取代码之前，请确认您已安装 Node.js 18 或更高版本。在撰写本文时，Puppeteer v24 要求至少使用 Node.js 18.0。

node --version   # should print v18.x or higher
mkdir puppeteer-scraper && cd puppeteer-scraper
npm init -y
npm install puppeteer

运行 npm install puppeteer 会下载该库以及一个兼容的 Chromium 二进制文件（约 170 MB）。如果您已自行管理 Chrome 安装，或希望安装更精简的版本，可以使用 puppeteer-core ，该命令将跳过捆绑浏览器的下载。这种做法在 Docker 和 CI 环境中很常见，因为您通常通过系统包管理器安装 Chromium。

此时您的项目文件夹中应包含一个 node_modules 目录以及一个 package.json 文件，其中列出了 Puppeteer 作为依赖项。创建一个名为 scraper.js （或 scraper.mjs ，如果你更喜欢 ES 模块），至此你已准备好构建你的第一个基于 Node.js 的 Puppeteer 网络爬虫项目。

一个小提示：Puppeteer 团队会在每次发布时更新捆绑的 Chromium，因此锁定特定版本（例如 npm install puppeteer@24.26.1) 有助于确保你的 CI 构建在不同环境中具有可重现性。

Puppeteer 网络爬虫的经典入门目标是 Quotes to Scrape，这是一个专门用于练习提取技术的沙盒网站。

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://quotes.toscrape.com', {
    waitUntil: 'domcontentloaded',
  });

  const html = await page.content();
  console.log(html.substring(0, 500));

  await browser.close();
})();

以下是具体步骤：

1. puppeteer.launch() 启动一个无头 Chromium 进程。
2. browser.newPage() 打开一个空白标签页。
3. page.goto() 导航至目标 URL。 waitUntil 该选项用于告知 Puppeteer 何时视为导航完成。使用 domcontentloaded 比 networkidle0 ，但可能会遗漏延迟加载的内容。
4. page.content() 返回页面完全渲染后的 HTML。
5. browser.close() 关闭浏览器进程并释放资源。

这个框架是您将构建的每个 Puppeteer 爬虫的基础。其模式始终如一：启动、导航、提取、关闭。变化的是中间的提取逻辑，我们将在后续章节中详细展开。

使用 node scraper.js ，终端应会输出原始 HTML。若在 Linux 系统上遇到共享库缺失的错误，请跳至部署章节查看解决方法。

若需浏览和页面方法的完整参考，官方 Puppeteer API 文档是最可靠的来源。

静态页面是简单的情况。动态网站会在初始 HTML 响应后加载内容，有时通过 XHR 请求，有时通过客户端渲染框架。当您使用 Puppeteer 和 NodeJS 抓取现代单页应用程序时，Puppeteer 提供了多种等待策略来处理这种情况。

最可靠的方法是 page.waitForSelector()，该方法会暂停执行，直到特定的 CSS 选择器出现在 DOM 中：

await page.goto('https://quotes.toscrape.com');
await page.waitForSelector('.quote');

一旦元素出现，使用 page.evaluate() 在浏览器上下文中运行 JavaScript，并将数据提取回 Node.js：

const quotes = await page.evaluate(() => {
  const items = document.querySelectorAll('.quote');
  return Array.from(items).map(item => ({
    text: item.querySelector('.text').innerText,
    author: item.querySelector('.author').innerText,
    tags: Array.from(item.querySelectorAll('.tag')).map(t => t.innerText),
  }));
});

console.log(quotes);

关于 page.evaluate():

• 回调函数在浏览器中运行，而非在 Node.js 中。您无法在其内部引用 Node.js 变量或模块。
• 返回值必须是可序列化的（普通对象、数组、字符串、数字）。不能直接返回 DOM 元素。
• 如果选择器未匹配到任何元素， querySelector 将返回 null，当您尝试读取 .innerText时会抛出异常。将访问操作封装在可选链中（?.）或空值检查中，可防止生产环境中的无声崩溃。

对于那些通过定时器而非 DOM 事件加载内容的页面， page.waitForTimeout() 可作为备用方案，但建议尽可能优先使用基于选择器的等待机制，因为它们速度更快且更具确定性。若您正在全功能浏览器自动化库与轻量级解析器之间抉择，Cheerio 与 Puppeteer 的对比指南可助您选定最适合的工具。

大多数实际抓取目标不会在单次页面加载中提供全部数据。你会遇到分页、无限滚动、登录墙及其他交互模式。以下是使用 Puppeteer 和 NodeJS 对生产环境网站进行网页抓取时，需要处理的三种最常见模式。

分页是您最常遇到的模式。处理策略很简单：从当前页面提取数据，找到“下一页”链接，跳转至该页面，并重复此过程直至没有更多页面。

let currentPage = 1;
const allQuotes = [];

while (true) {
  await page.waitForSelector('.quote');
  const pageQuotes = await page.evaluate(() =>
    Array.from(document.querySelectorAll('.quote')).map(q => ({
      text: q.querySelector('.text').innerText,
      author: q.querySelector('.author').innerText,
    }))
  );
  allQuotes.push(...pageQuotes);

  const nextButton = await page.$('li.next > a');
  if (!nextButton) break;

  await Promise.all([
    page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
    nextButton.click(),
  ]);
  currentPage++;
}

console.log(`Scraped ${allQuotes.length} quotes across ${currentPage} pages.`);

关键细节在于将 click() 和 waitForNavigation() Promise.all标签中。若先点击再等待，Puppeteer 可能会错过导航事件，因为该事件可能已被触发。这一用于防范竞态条件的保护措施，对实现可靠的多页爬取至关重要。

添加重试逻辑可使该模式适用于生产环境。将导航操作封装在 try/catch中，为 waitForNavigation，并在记录失败并继续之前最多重试三次。正是这种错误处理机制，将博客文章中的 Puppeteer 抓取示例与那些可整夜无人值守运行的抓取工具区分开来。

无限滚动用“加载更多”触发器取代了分页，该触发器在滚动到页面底部时触发。社交媒体信息流和产品列表页面通常采用这种模式。要使用 Puppeteer 抓取动态网站，需通过编程方式滚动并等待新内容出现。

async function autoScroll(page, maxScrolls = 10) {
  let previousHeight = 0;
  let scrollCount = 0;

  while (scrollCount < maxScrolls) {
    previousHeight = await page.evaluate(() => document.body.scrollHeight);
    await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
    await new Promise(r => setTimeout(r, 1500));

    const newHeight = await page.evaluate(() => document.body.scrollHeight);
    if (newHeight === previousHeight) break;
    scrollCount++;
  }
}

该函数会比较 scrollHeight 每次滚动前后的高度。当高度停止变化时，要么表示所有内容已加载完毕，要么需要点击“显示更多”按钮。添加一个 maxScrolls 上限，以避免在真正无尽的动态信息流页面上陷入无限循环。您还可以通过 querySelectorAll）作为次要终止信号，以处理新内容加载但未改变页面总高度的情况。

突破登录墙进行抓取需要表单交互。Puppeteer的 page.type() 可模拟逐键输入，而 page.click() 并触发真实的鼠标事件，这一点至关重要，因为某些网站会监听输入事件，而不仅仅是检查字段值。

await page.goto('https://quotes.toscrape.com/login');
await page.type('#username', 'testuser');
await page.type('#password', 'testpass');
await Promise.all([
  page.waitForNavigation(),
  page.click('input[type="submit"]'),
]);

登录后，浏览器会话会自动保留 Cookie 以供后续导航。在此会话期间，您可以继续访问已认证的页面，而无需重新输入凭据。如果网站首先显示 Cookie 同意横幅，请在与登录表单交互之前点击“接受”按钮。

对于更复杂的表单操作流程（多步骤向导、文件上传、下拉菜单选择），Puppeteer 提供了诸如 page.select() 用于 <select> 元素和 elementHandle.uploadFile() 用于文件输入。您可以在专门介绍这些高级交互操作的指南中，探索如何使用 Puppeteer 提交表单。

这里介绍一种大多数 Puppeteer 网络爬虫教程完全忽略的技术：与其解析 DOM，不如拦截页面发出的网络请求，并直接从网站自身的 API 调用中获取结构化的 JSON 有效载荷。

许多现代网站通过 XHR 或 Fetch 请求获取数据，并在客户端进行渲染。若能捕获这些有效载荷，便可完全跳过依赖 CSS 选择器的繁琐操作。

await page.setRequestInterception(true);

page.on('response', async (response) => {
  const url = response.url();
  if (url.includes('/api/products') && response.status() === 200) {
    try {
      const data = await response.json();
      console.log('Captured API response:', data);
    } catch (e) {
      // Not a JSON response, skip
    }
  }
});

page.on('request', (request) => {
  const blocked = ['image', 'font', 'stylesheet'];
  if (blocked.includes(request.resourceType())) {
    request.abort();
  } else {
    request.continue();
  }
});

await page.goto('https://example-spa.com');

这种方法之所以强大，有两个原因。首先，响应本身已经是结构化的 JSON，因此你完全不需要编写选择器。其次，它随时间推移往往更稳定，因为 API 接口的变更频率远低于 UI 标记。

要发现页面调用了哪些接口，请在目标网站上打开浏览器的开发者工具“网络”标签页，按“Fetch/XHR”过滤，并查找包含所需数据的响应。 随后在拦截处理程序中过滤这些 URL 模式。这种隐藏 API 采集技术是您为 Puppeteer Node.js 爬取工具包增添的最具竞争力的差异化功能之一。它让您能够更高效地使用 Puppeteer 和 Node.js 进行网页爬取，因为对于基于 API 的页面，完全无需进行 DOM 解析。

单个 Puppeteer 进程会按顺序处理请求。当您需要抓取数千个 URL 时，这种串行处理方式就会成为瓶颈。以下是两项对扩展 Node.js 网页抓取器 Puppeteer 工作流影响最大的优化措施。

屏蔽非必要资源。 图片、字体、样式表和媒体文件不仅消耗带宽、拖慢页面加载速度，却无法提供任何可抓取的数据。禁用图片和视频加载是加速 Puppeteer 爬虫的最有效方法之一，且不会导致数据丢失，因为这些资源在 DOM 标记中仍然可访问。请使用请求拦截来中止这些资源类型的加载（如上一节所示）。仅此一项改动，就能将媒体资源密集型网站的页面加载时间缩短一半。

并行处理多个页面。Puppeteer 本身具有异步特性，而 Node.js 通过 Promise.all。与其逐个处理 URL，不如同时打开多个页面并行抓取：

const urls = ['https://example.com/1', 'https://example.com/2', 'https://example.com/3'];
const browser = await puppeteer.launch({ headless: true });

const scrape = async (url) => {
  const page = await browser.newPage();
  try {
    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
    const title = await page.evaluate(() => document.title);
    return { url, title };
  } catch (err) {
    return { url, error: err.message };
  } finally {
    await page.close();
  }
};

const results = await Promise.all(urls.map(scrape));
console.log(results);

请注意 try/catch/finally 块。在生产环境中，单个页面偶尔会超时或失败。将每个任务封装起来可确保单个无效 URL 不会导致整个批处理崩溃。 finally 块可确保即使发生错误也能关闭页面，从而防止内存泄漏。

一个实用的并发限制是每个浏览器实例处理 5 到 10 个页面，具体取决于您的机器内存。超过这个数量时，请考虑启动多个浏览器实例，或将 URL 批量划分为顺序处理的块。每个 Chromium 页面大约消耗 30 到 80 MB 内存，当您运行数十个并发标签页时，内存消耗会迅速累积。对于真正的大规模任务，您可能需要转向托管浏览器云服务，而不是在本地托管 Chrome。

尽管 Puppeteer 运行的是真实浏览器，网站仍可通过 JavaScript 指纹识别、头部信息分析和行为启发式分析来检测自动化流量。如果您曾遇到过抓取工具在处理 20 次请求后突然开始返回 CAPTCHA 验证码的情况，那便是机器人检测所致。

隐身插件是第一道防线。puppeteer-extra-plugin-stealth 包修复了多个已知的检测途径： navigator.webdriver flag、Chrome 插件数组、WebGL 渲染器字符串等。在撰写本文时，请务必确认您安装的隐身插件版本与您的 Puppeteer 版本兼容，因为两个库在重大版本发布后可能会出现不兼容的情况。

const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
puppeteer.use(StealthPlugin());

const browser = await puppeteer.launch({ headless: true });

代理轮换是第二道防线。在不同请求中轮换外发 IP 地址，能大幅增加网站关联并封锁您流量的难度。您可以在 Puppeteer 隐身爬取配置中，于启动时传入代理：

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://proxy-address:port'],
});

需注意的一点限制：Puppeteer的原生API不支持按请求切换代理。代理是在浏览器层级设置的，因此更改代理需要重启浏览器实例。对于高流量的Puppeteer代理轮换，若没有外部代理管理层或专用的住宅代理池，这将变得不切实际。

除了技术措施外，您还应在请求之间添加合理的延迟，并遵守 robots.txt 指令。遵守网络礼仪可降低被封IP的风险，并延长爬虫的运行时间。如需全面的实用策略，可查阅《避免网页爬取被封的技巧》。

将结果输出到控制台虽可用于调试，但生产环境中的爬虫需要结构化的文件输出。Node.js 通过内置的 fs 模块，使这一过程变得十分简单。

JSON 导出：

const fs = require('fs');
const data = [{ text: 'Example quote', author: 'Author' }];
fs.writeFileSync('quotes.json', JSON.stringify(data, null, 2), 'utf-8');

CSV 导出：

const header = 'text,author\n';
const rows = data.map(d => `"${d.text}","${d.author}"`).join('\n');
fs.writeFileSync('quotes.csv', header + rows, 'utf-8');

若需生成更完善的 CSV 文件（处理值内的逗号、特殊字符及大型数据集），建议使用 csv-stringify 或 fast-csv。这些库能处理嵌入式引号和多行字段等特殊情况，而简单的模板字面量方法往往会忽略这些情况。

当下游消费者是其他程序或 API 时，请选择 JSON。当数据将用于电子表格、支持 CSV 导入的数据库，或希望在 Excel 中打开文件的非技术相关方时，请选择 CSV。无论选择哪种格式，在使用 Puppeteer 和 NodeJS 进行网络爬取时，将数据增量写入磁盘（而非将所有数据积存于内存中），对于可能中途崩溃的长期运行任务而言至关重要。

在 macOS 上运行完美的 Puppeteer 爬虫，一旦部署到 Linux 服务器上往往就会出错。无头 Chrome 浏览器依赖于操作系统包，而 Linux 服务器通常缺少 Chromium 所需的与 GUI 相关的共享库。

对于 Debian 或 Ubuntu 服务器，请安装缺失的依赖项：

apt-get update && apt-get install -y \
  ca-certificates fonts-liberation libasound2 libatk1.0-0 \
  libcups2 libdbus-1-3 libgdk-pixbuf2.0-0 libnspr4 libnss3 \
  libx11-xcb1 libxcomposite1 libxrandr2 xdg-utils

对于 Docker 部署，一个简化的 Dockerfile 如下所示：

FROM node:18-slim
RUN apt-get update && apt-get install -y chromium
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "scraper.js"]

容器化环境中的两个关键启动参数：

puppeteer.launch({
  headless: true,
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
});

若不使用 --no-sandbox，Chromium 将在大多数 Docker 容器中拒绝启动。在您能控制输入 URL 的容器化爬虫中使用这些参数是安全的，但在处理不可信内容的环境中应避免使用。 一旦容器能够正确构建并运行，将 Docker 部署的爬虫加入 CI 管道（GitHub Actions、GitLab CI）便十分简单。许多开发者在这一部署步骤上遇到障碍，因此若您确定需要服务器部署，请从一开始就计划在容器化环境中使用 Puppeteer 和 NodeJS 进行网页抓取。

如果您正在评估无头浏览器抓取工具，想必也听说过 Playwright。这两个库有着共同的基因（Playwright 由前 Puppeteer 维护者创建），但它们针对不同的需求。

如果您的抓取目标仅需 Chromium 支持，且团队已使用 JavaScript 编写代码，那么 Puppeteer 是更简单、更成熟的选择，且拥有更庞大的插件生态系统。当您需要多浏览器支持，或使用 JavaScript 以外的语言进行开发时，Playwright 则更具优势。如需更全面的选项评估，您可以参考其他 Puppeteer 替代方案，以找到最符合项目需求的工具。

无论您选择哪种库，本指南涵盖的核心概念（等待策略、请求拦截、隐身措施、错误处理）均可直接应用于 Playwright，仅存在细微的 API 差异。

• Puppeteer 通过 DevTools 协议驱动真实的 Chromium 浏览器，因此非常适合抓取普通 HTTP 客户端无法处理的 JavaScript 渲染页面。
• 始终使用 waitForSelector ，而非固定超时，将导航点击包裹在 Promise.all，并在页面操作周围添加 try/catch 块包裹页面操作，以构建高容错的爬虫。
• 拦截网络请求以直接捕获隐藏的 API JSON 有效载荷，完全绕过脆弱的 DOM 选择器。
• 分层部署隐身插件和代理轮换以降低机器人被检测的风险，并将其与速率限制和遵守 robots.txt 等礼貌抓取做法相结合。
• 将结构化数据导出为 JSON 或 CSV，在 Docker 中使用正确的沙箱标志进行部署，并批量处理并发页面，以实现超越单 URL 脚本的扩展能力。

Linux 服务器通常缺少 Chromium 所依赖的与 GUI 相关的共享库，例如 libx11-xcb, libnss3以及字体包。请使用 apt-get ，或使用包含这些组件的 Docker 基础镜像。此外，若不使用 --no-sandbox 参数运行会导致 Chrome 在大多数 Linux 主机上崩溃，因为内核沙箱机制需要提升权限，而容器通常会限制这些权限。

使用 page.cookies() 将当前会话的 Cookie 导出为 JSON 数组，然后使用 fs.writeFileSync。在后续运行中，加载该文件并调用 page.setCookie(...cookies) ，再导航至目标网站。这样可以保留登录会话、偏好设置和 CSRF 令牌，而无需在每次执行时重新认证。

合法性因司法管辖区和目标网站的服务条款而异。一般而言，在许多地区抓取公开数据是被允许的，但违反网站的服务条款可能带来法律风险。请务必检查目标网站的 robots.txt 文件（通常位于 https://domain.com/robots.txt）并遵守其中的 Disallow 指令。请在请求之间添加延迟，避免因密集流量导致服务器过载。

验证码（CAPTCHA）专为阻止自动化操作而设计。隐身插件可通过掩盖浏览器指纹来延迟验证码的出现，但一旦验证码被触发，仅靠 Puppeteer 无法解决。您可以集成第三方验证码破解服务（通过其 API），或重构爬虫程序以减少被检测的信号（降低请求频率、使用家庭 IP 地址、随机化视口尺寸），从而减少验证码的触发频率。

Puppeteer 仍是 Node.js 环境中抓取动态、大量使用 JavaScript 的网站最强大的工具之一。在本指南中，您已学会如何设置项目、使用选择器提取内容 page.evaluate()处理分页和无限滚动、拦截隐藏的 API 响应、应用隐身措施、导出结构化数据，以及在 Docker 中部署爬虫。

最重要的收获是：要将可运行的原型转化为生产环境中的爬虫，不仅需要掌握 DOM 遍历，还需关注错误处理、并发控制和反检测机制。将页面封装在 try/catch包裹页面、批量并发请求以及轮换代理，这些模式决定了脚本是会在 50 次请求后崩溃，还是能在大规模运行中保持稳定。

如果您发现自己花在应对封锁、验证码和代理基础设施上的时间，比编写数据提取逻辑的时间还要多，这通常意味着您需要将请求层进行外包处理。WebScrapingAPI 的 Scraper API 通过单一接口即可处理代理轮换、浏览器指纹管理和验证码破解，让您无需重构爬虫的其他部分，只需保留 Puppeteer 解析代码，并替换网络层即可。