puppeteer安装与配置需先确保node.js和npm全局可用，再通过npm install puppeteer-core初始化项目，配合手动指定chrome路径、合理设置启动参数及vscode调试配置实现稳定运行。

确认本地已安装 Node.js 且 node 和 npm 可全局调用

VSCode 本身不自带 Node 运行时，它只是编辑器。如果你运行 node --version 或 npm --version 报错“command not found”，说明系统 PATH 没识别到 Node 安装路径——Puppeteer 根本跑不起来，别急着装插件或改 VSCode 设置。

常见错误现象：ReferenceError: require is not defined（在 JS 文件里直接写 require('puppeteer') 却报错），往往是因为你误把文件当浏览器环境执行了，而不是用 node 命令运行。

• macOS / Linux：检查 which node 是否有输出；若无，重装 Node（推荐用 brew install node 或从官网下载 pkg）
• Windows：打开 CMD 执行 where node，确认返回路径包含 Program Files odejs；若无，安装时勾选 “Add to PATH”
• VSCode 终端需重启才能读取新 PATH —— 关掉所有终端窗口再新开一个

初始化项目并安装 Puppeteer 的正确方式

puppeteer 默认会自动下载 Chromium，但国内网络常卡在下载阶段，导致 npm install puppeteer 长时间无响应甚至失败。这不是你代码的问题，是网络策略导致的。

使用场景：你只需要爬取 HTML、截图、提取数据，不需要调试浏览器界面，所以用 puppeteer-core + 手动指定已安装 Chrome 更稳定。

• 先执行 npm init -y 初始化项目
• 安装精简版：npm install puppeteer-core
• 确保本机已安装 Chrome（版本 ≥90），然后通过 executablePath 指向它：

  const browser = await puppeteer.launch({
    executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', // macOS
    // executablePath: 'C:\Program Files\Google\Chrome\Application\chrome.exe', // Windows
    headless: true,
  });

• 避免全局安装 puppeteer —— 它会反复下载二进制，且不同项目版本冲突风险高

VSCode 中调试 Puppeteer 脚本的关键配置

直接按 F5 运行 JS 文件大概率失败，因为 VSCode 默认调试器不加载 package.json 的 type: "module" 或 CommonJS 规则，也不自动设 node 解析器。

Zenlink - Node SDK for ZenHeart

ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。

下载

容易踩的坑：Cannot use import statement outside a module 错误，不是语法错，是运行时没启用 ES Module 支持。

• 在项目根目录加 .vscode/launch.json，内容为：

  {
    "version": "0.2.0",
    "configurations": [
      {
        "type": "node",
        "request": "launch",
        "name": "Launch Puppeteer",
        "skipFiles": ["<node_internals>/**"],
        "program": "${file}",
        "console": "integratedTerminal",
        "internalConsoleOptions": "neverOpen"
      }
    ]
  }</node_internals>

• 若用 ES Module（即写 import puppeteer from 'puppeteer-core'），必须在 package.json 加 "type": "module"，且确保 Node 版本 ≥14.18
• 若用 CommonJS（const puppeteer = require('puppeteer-core')），就别加 "type": "module"，否则报错

处理常见反爬拦截：启动参数和等待策略不能省

Puppeteer 默认 User-Agent 和行为特征太明显，很多网站（如知乎、微博、电商详情页）会直接返回 403 或空白页。光靠 headless: true 不够，得模拟真实浏览器上下文。

性能影响：加太多启动参数会略微拖慢启动速度，但能显著提升成功率；不加的话，可能爬 10 次失败 7 次。

• 必加基础参数：

  await puppeteer.launch({
    headless: true,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-blink-features=AutomationControlled',
      '--disable-web-security',
    ],
  });

• 启动后立即覆盖 navigator.webdriver：

  await page.evaluateOnNewDocument(() => {
    Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
  });

• 别用 page.waitForTimeout(2000) 硬等，优先用 page.waitForSelector('main') 或 page.waitForNetworkIdle()，更可靠

网页结构动态渲染、懒加载、登录态校验这些逻辑，得靠具体页面分析，没有通用解法。Puppeteer 只负责打开、执行、取数，怎么应对目标站点，得你自己看 Network 面板和 Elements 实时变化。