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 解析器。
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
容易踩的坑：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" } ] } - 若用 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 实时变化。
