Puppeteer中.$eval()与.$$eval()的高效使用指南

聖光之護

发布时间：2025-12-08 15:36:07

680人浏览过

来源于php中文网

原创

puppeteer中.$eval()与.$$eval()的高效使用指南

本文深入探讨了Puppeteer库中`.$eval()`和`.$$eval()`这两个核心DOM操作方法的正确使用方式。我们将通过实际代码示例，详细阐述它们在处理单个和多个DOM元素时的差异与最佳实践，并展示如何利用这些方法进行复杂的网页自动化，如模拟打字测试，涵盖请求拦截、元素交互及结果捕获等进阶技巧，旨在提升开发者在网页抓取和自动化任务中的效率与准确性。

在前端自动化和网页抓取领域，Puppeteer是一个功能强大的库，它提供了高级API来控制Chrome或Chromium。其中，page.$eval()、elementHandle.$eval()以及page.$$eval()、elementHandle.$$eval()是与页面DOM交互的核心方法。理解它们之间的区别和正确用法，对于高效地进行DOM查询和数据提取至关重要。

理解 .$eval()：针对单个元素的查询与操作

.$eval()方法用于在页面上下文中对匹配指定选择器的第一个元素执行一个函数。它的回调函数接收一个DOM元素作为参数，允许你直接操作或提取该元素的属性。

基本用法示例：

假设我们想从ID为#words的容器中获取第一个div元素的HTML内容：

const puppeteer = require('puppeteer');

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

    // 等待 #words 元素出现
    const wordsSelector = await page.waitForSelector('#words');
    // 使用 .$eval 获取第一个 div 的 innerHTML
    const innerHtml = await wordsSelector.$eval('div', element => element.innerHTML);
    console.log(innerHtml); // 预期输出：in...

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

在这个例子中，wordsSelector.$eval('div', ...)会在#words元素内部查找第一个div，并将其作为element参数传递给回调函数。回调函数返回该元素的innerHTML。

掌握 .$$eval()：处理多个元素集合

.$$eval()方法则用于在页面上下文中对匹配指定选择器的所有元素执行一个函数。与.$eval()不同，它的回调函数接收一个DOM元素数组作为参数。这是初学者常犯错误的地方，误以为回调函数接收的是单个元素。

常见错误示例：

尝试像.$eval()那样直接访问words.innerHTML会导致错误，因为words此时是一个数组：

ECTouch移动商城系统

ECTouch是上海商创网络科技有限公司推出的一套基于 PHP 和 MySQL 数据库构建的开源且易于使用的移动商城网店系统！应用于各种服务器平台的高效、快速和易于管理的网店解决方案，采用稳定的MVC框架开发，完美对接ecshop系统与模板堂众多模板，为中小企业提供最佳的移动电商解决方案。ECTouch程序源代码完全无加密。安装时只需将已集成的文件夹放进指定位置，通过浏览器访问一键安装，无需对已有

下载

// 错误示例：
// const wordsSelector = await page.waitForSelector('#words');
// console.log(await wordsSelector.$$eval('div', words => words.innerHTML)); 
// 这里的 'words' 是一个数组，没有 innerHTML 属性

正确用法示例：

要正确使用.$$eval()，你需要遍历这个元素数组，并对每个元素执行操作。通常，我们会使用Array.prototype.map()方法来提取每个元素的所需属性。

const puppeteer = require('puppeteer');

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

    // 假设页面有隐私政策弹窗，需要点击拒绝
    const rejectAllButton = await page.waitForSelector(".rejectAll");
    if (rejectAllButton) {
        await rejectAllButton.click();
    }

    // 等待激活的单词元素出现
    await page.waitForSelector("#words .word.active");

    const wordsEl = await page.$("#words");
    // 使用 $$eval 获取所有 .word 元素的 innerHTML
    const wordsInnerHtmlArray = await wordsEl.$$eval(".word", els =>
        els.map(el => el.innerHTML) // 遍历数组，提取每个元素的 innerHTML
    );
    console.log(wordsInnerHtmlArray); // 预期输出：['w...', 'o...']

    // 最佳实践：如果只需要纯文本，推荐使用 .textContent
    const wordsTextContentArray = await wordsEl.$$eval(".word", els =>
        els.map(el => el.textContent.trim()) // 提取纯文本并去除空白
    );
    console.log(wordsTextContentArray); // 预期输出：['word1', 'word2', ...]

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

在这个修正后的例子中，els是一个DOM元素数组。我们通过els.map(el => el.innerHTML)遍历这个数组，为每个元素提取innerHTML，最终得到一个包含所有innerHTML字符串的数组。

提示：innerHTML vs textContent

当你的目标是获取元素的纯文本内容时，强烈建议使用element.textContent而不是element.innerHTML。textContent只返回元素及其后代节点的文本内容，不包含任何HTML标签，这通常更符合数据抓取的需求，并且可以避免不必要的解析和潜在的安全问题。

实战应用：自动化网页交互示例 (以打字测试为例)

为了更全面地展示.$eval()和.$$eval()的实际应用，我们来看一个模拟打字测试的复杂场景。这个例子不仅会使用到上述方法，还会涉及请求拦截、元素交互和结果捕获。

const puppeteer = require("puppeteer");

let browser;
(async () => {
  browser = await puppeteer.launch({ headless: true }); // 设置 headless: false 可观察浏览器操作
  const [page] = await browser.pages();
  const url = "https://monkeytype.com/";

  // 1. 设置请求拦截以优化性能和稳定性
  await page.setRequestInterception(true);
  const allowedDomains = [
    "https://monkeytype.com",
    "https://www.monkeytype.com",
    "https://api.monkeytype.com",
    "https://fonts.google", // 允许加载字体文件
  ];
  page.on("request", request => {
    if (allowedDomains.some(domain => request.url().startsWith(domain))) {
      request.continue();
    } else {
      request.abort(); // 阻止加载其他不必要的资源，如广告、分析脚本等
    }
  });

  // 2. 导航到目标页面并等待DOM加载完成
  await page.goto(url, { waitUntil: "domcontentloaded" });

  // 3. 处理隐私政策弹窗（如果存在）
  const rejectAllButton = await page.waitForSelector(".rejectAll");
  if (rejectAllButton) {
      await rejectAllButton.click();
  }

  // 4. 等待打字测试区域加载完成，确保单词可见
  await page.waitForSelector("#words .word.active");
  const wordsContainer = await page.$("#words"); // 获取单词容器的 ElementHandle

  // 5. 模拟打字过程
  try {
    for (;;) { // 无限循环，直到没有活动的单词或出现错误
      // 使用 .$eval 获取当前活动单词的纯文本
      const activeWord = await wordsContainer.$eval(".word.active", el =>
        el.textContent.trim()
      );
      console.log(`正在输入: ${activeWord}`);
      // 使用 ElementHandle.type() 模拟键盘输入
      await wordsContainer.type(activeWord + " "); // 输入单词并加上空格
    }
  } catch (err) {
    // 当没有 .word.active 元素时，.$eval 会抛出错误，表示打字测试可能已完成
    console.log("打字测试可能已完成或遇到其他错误:", err.message);
  }

  // 6. 捕获测试结果
  const results = await page.waitForSelector("#result");
  // 将结果区域滚动到视图中，以便截图
  await results.evaluate(el => el.scrollIntoView());
  // 截图保存结果
  await results.screenshot({ path: "typing-results.png" });
  console.log("打字测试结果已保存到 typing-results.png");

})()
  .catch(err => console.error("发生错误:", err))
  .finally(() => browser?.close()); // 无论成功失败，确保关闭浏览器实例

代码解析：

请求拦截: page.setRequestInterception(true) 结合 page.on('request', ...) 允许我们控制哪些网络请求被允许或阻止。这对于提高页面加载速度、减少不必要的资源消耗以及避免干扰（如广告）非常有用。
元素定位与交互: page.waitForSelector() 确保元素在操作前已经加载。page.$() 返回一个 ElementHandle，我们可以直接在其上调用 .$eval() 或 type() 方法。
模拟打字: 通过一个无限循环，不断获取当前活动的单词，并使用 elementHandle.type() 方法模拟用户输入。当所有单词都输入完毕，wordsContainer.$eval(".word.active", ...) 将找不到匹配的元素，从而抛出错误，被 try...catch 捕获，结束循环。
结果捕获: 最后，等待结果元素出现，通过 elementHandle.evaluate() 在浏览器上下文中执行 scrollIntoView() 将其滚动到可视区域，然后使用 elementHandle.screenshot() 截取结果图。
错误处理与资源清理: try...catch 块用于优雅地处理可能发生的错误，而 finally 块确保浏览器实例在任何情况下都会被关闭，防止资源泄露。

注意事项与最佳实践

选择器精准性: 使用尽可能具体和稳定的CSS选择器。避免过度依赖可能频繁变化的类名或动态生成的ID。
错误处理: 在自动化脚本中加入健壮的错误处理机制，例如使用 try...catch 捕获元素未找到等异常。
等待机制: 充分利用 page.waitForSelector(), page.waitForNavigation(), page.waitForTimeout() 等等待函数，确保在操作元素之前它们已经加载并可见。
innerHTML vs textContent: 根据需求选择合适的方法提取内容。通常 textContent 更安全、更简洁。
性能优化:
- 无头模式 (Headless Mode): 在生产环境或自动化测试中，通常使用 headless: true 来运行浏览器，不显示UI，提高执行效率。
- 请求拦截: 如示例所示，拦截并阻止不必要的资源加载可以显著提升页面加载速度和脚本执行效率。
- 资源清理: 务必在脚本结束时关闭浏览器实例 (browser.close())，以释放系统资源。

总结

.$eval() 和 .$$eval() 是 Puppeteer 中用于在浏览器上下文中执行JavaScript并与DOM交互的强大工具。.$eval() 适用于单个元素的查询和操作，而 .$$eval() 则处理元素集合，通常需要结合 map 方法来提取每个元素的数据。通过掌握这些方法，并结合请求拦截、等待机制和错误处理等最佳实践，开发者可以构建出高效、稳定且功能强大的网页自动化和数据抓取解决方案。

CSS Line Clamp 与首字母大写的兼容性解决方案

如何同时实现首字母大写与多行文本截断（Line Clamp）

CSS 实现首字母大写与多行截断的兼容性解决方案

如何让悬停显示的内容在鼠标移入时保持可见（防止意外消失）

如何通过 CSS 动画延迟 Turbo Frame 的加载时机