Puppeteer 安装与配置 #

系统要求 #

基本要求 #

text

┌─────────────────────────────────────────────────────────────┐
│                    Puppeteer 系统要求                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Node.js:  >= 18.0.0 (推荐 20.x LTS)                        │
│   npm:      >= 8.0.0                                         │
│   操作系统:  Windows, macOS, Linux                           │
│   内存:     至少 512MB 可用内存                               │
│   磁盘:     约 300MB (包含 Chromium)                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

各系统依赖 #

Linux #

bash

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
  ca-certificates \
  fonts-liberation \
  libasound2 \
  libatk-bridge2.0-0 \
  libatk1.0-0 \
  libc6 \
  libcairo2 \
  libcups2 \
  libdbus-1-3 \
  libexpat1 \
  libfontconfig1 \
  libgbm1 \
  libgcc1 \
  libglib2.0-0 \
  libgtk-3-0 \
  libnspr4 \
  libnss3 \
  libpango-1.0-0 \
  libpangocairo-1.0-0 \
  libstdc++6 \
  libx11-6 \
  libx11-xcb1 \
  libxcb1 \
  libxcomposite1 \
  libxcursor1 \
  libxdamage1 \
  libxext6 \
  libxfixes3 \
  libxi6 \
  libxrandr2 \
  libxrender1 \
  libxss1 \
  libxtst6 \
  lsb-release \
  wget \
  xdg-utils

macOS #

macOS 通常无需额外依赖，确保 Xcode Command Line Tools 已安装：

bash

xcode-select --install

Windows #

Windows 通常无需额外依赖，但需要确保已安装 Visual C++ Redistributable。

安装方式 #

方式一：完整安装（推荐） #

安装 Puppeteer 并自动下载 Chromium：

bash

npm install puppeteer

安装完成后：

Puppeteer 库安装在 node_modules/puppeteer
Chromium 浏览器下载到 ~/.cache/puppeteer

方式二：核心库安装 #

只安装核心库，不下载 Chromium：

bash

npm install puppeteer-core

这种方式适合：

使用系统已安装的 Chrome/Chromium
使用远程浏览器
减小项目体积

方式三：使用 Yarn #

bash

yarn add puppeteer

方式四：使用 pnpm #

bash

pnpm add puppeteer

版本选择 #

版本对照表 #

Puppeteer 版本	Chromium 版本	Node.js 要求
22.x	Chrome 122+	Node.js 18+
21.x	Chrome 120+	Node.js 18+
20.x	Chrome 118+	Node.js 18+
19.x	Chrome 112+	Node.js 14+

安装特定版本 #

bash

# 安装最新版本
npm install puppeteer@latest

# 安装特定版本
npm install puppeteer@21.0.0

# 安装下一个版本（测试版）
npm install puppeteer@next

配置选项 #

环境变量配置 #

bash

# .env 文件
PUPPETEER_CACHE_DIR=/path/to/cache
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

npm 配置 #

bash

# 跳过 Chromium 下载
npm install puppeteer --save --puppeteer_skip_download=true

# 指定下载目录
npm install puppeteer --save --puppeteer_download_path=/custom/path

package.json 配置 #

json

{
  "name": "my-project",
  "dependencies": {
    "puppeteer": "^22.0.0"
  },
  "puppeteer": {
    "cacheDirectory": "./chrome-cache",
    "skipDownload": false
  }
}

基本使用 #

第一个脚本 #

创建 index.js 文件：

javascript

const puppeteer = require('puppeteer');

(async () => {
  // 启动浏览器
  const browser = await puppeteer.launch();
  
  // 创建新页面
  const page = await browser.newPage();
  
  // 访问网页
  await page.goto('https://example.com');
  
  // 截图
  await page.screenshot({ path: 'example.png' });
  
  // 关闭浏览器
  await browser.close();
})();

运行脚本：

bash

node index.js

TypeScript 支持 #

Puppeteer 内置 TypeScript 类型定义：

typescript

import puppeteer, { Browser, Page } from 'puppeteer';

async function main(): Promise<void> {
  const browser: Browser = await puppeteer.launch();
  const page: Page = await browser.newPage();
  
  await page.goto('https://example.com');
  
  const title: string = await page.title();
  console.log('Page title:', title);
  
  await browser.close();
}

main();

启动配置详解 #

puppeteer.launch() 选项 #

javascript

const browser = await puppeteer.launch({
  // 是否无头模式
  headless: true,  // 'new' | true | false
  
  // 可执行文件路径
  executablePath: '/path/to/chrome',
  
  // 是否忽略 HTTPS 错误
  ignoreHTTPSErrors: true,
  
  // 启动超时时间
  timeout: 30000,
  
  // 视口默认设置
  defaultViewport: {
    width: 1920,
    height: 1080,
    deviceScaleFactor: 1,
    isMobile: false,
    hasTouch: false,
    isLandscape: false
  },
  
  // 浏览器启动参数
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
    '--disable-gpu'
  ],
  
  // 用户数据目录
  userDataDir: './user-data',
  
  // 是否忽略默认参数
  ignoreDefaultArgs: false,
  
  // 慢动作模式（毫秒）
  slowMo: 100
});

常用启动参数 #

javascript

const browser = await puppeteer.launch({
  args: [
    // 安全相关
    '--no-sandbox',                    // 禁用沙箱（Docker 必需）
    '--disable-setuid-sandbox',        // 禁用 setuid 沙箱
    
    // 性能相关
    '--disable-gpu',                   // 禁用 GPU 加速
    '--disable-dev-shm-usage',         // 避免共享内存问题
    '--disable-software-rasterizer',   // 禁用软件光栅化
    
    // 窗口相关
    '--window-size=1920,1080',         // 设置窗口大小
    '--start-maximized',               // 最大化启动
    
    // 隐身模式
    '--incognito',                     // 隐身模式
    
    // 语言
    '--lang=zh-CN',                    // 设置语言
    
    // 禁用功能
    '--disable-extensions',            // 禁用扩展
    '--disable-plugins',               // 禁用插件
    '--disable-images',                // 禁用图片加载
    '--disable-javascript',            // 禁用 JavaScript
    
    // 自动化检测
    '--disable-blink-features=AutomationControlled'  // 隐藏自动化特征
  ]
});

有头模式调试 #

javascript

const browser = await puppeteer.launch({
  headless: false,  // 显示浏览器窗口
  slowMo: 100,      // 放慢操作速度
  devtools: true    // 自动打开开发者工具
});

使用系统 Chrome #

查找 Chrome 路径 #

javascript

const puppeteer = require('puppeteer-core');

// macOS
const browser = await puppeteer.launch({
  executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
});

// Windows
const browser = await puppeteer.launch({
  executablePath: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
});

// Linux
const browser = await puppeteer.launch({
  executablePath: '/usr/bin/google-chrome'
});

自动检测 Chrome 路径 #

javascript

const { execSync } = require('child_process');

function findChrome() {
  const platforms = {
    darwin: [
      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
      '/Applications/Chromium.app/Contents/MacOS/Chromium'
    ],
    linux: [
      '/usr/bin/google-chrome',
      '/usr/bin/chromium',
      '/usr/bin/chromium-browser'
    ],
    win32: [
      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'
    ]
  };
  
  const paths = platforms[process.platform] || [];
  
  for (const path of paths) {
    try {
      if (require('fs').existsSync(path)) {
        return path;
      }
    } catch (e) {}
  }
  
  return null;
}

const browser = await puppeteer.launch({
  executablePath: findChrome()
});

Docker 环境配置 #

Dockerfile 示例 #

dockerfile

FROM node:20-slim

# 安装 Chrome 依赖
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    ca-certificates \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libatspi2.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libwayland-client0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxkbcommon0 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 复制 package.json
COPY package*.json ./

# 安装依赖
RUN npm install

# 复制代码
COPY . .

# 运行脚本
CMD ["node", "index.js"]

Docker Compose 示例 #

yaml

version: '3.8'

services:
  puppeteer:
    build: .
    environment:
      - PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
    volumes:
      - ./:/app
    command: node index.js

Docker 中运行配置 #

javascript

const browser = await puppeteer.launch({
  headless: 'new',
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
    '--disable-gpu'
  ]
});

常见问题解决 #

问题 1：Chromium 下载失败 #

bash

# 使用国内镜像
export PUPPETEER_DOWNLOAD_HOST=https://registry.npmmirror.com/mirrors

# 或使用淘宝镜像
export PUPPETEER_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/chrome-for-testing

npm install puppeteer

问题 2：权限不足 #

bash

# Linux 权限问题
sudo chmod -R 755 node_modules/puppeteer/.local-chromium

问题 3：内存不足 #

javascript

// 限制内存使用
const browser = await puppeteer.launch({
  args: [
    '--max-old-space-size=4096',
    '--disable-dev-shm-usage'
  ]
});

// 及时关闭页面
const page = await browser.newPage();
// ... 操作
await page.close();

问题 4：超时问题 #

javascript

// 增加超时时间
const browser = await puppeteer.launch({
  timeout: 60000  // 60 秒
});

// 页面操作超时
await page.goto('https://example.com', {
  timeout: 60000,
  waitUntil: 'networkidle0'
});

问题 5：中文乱码 #

javascript

// 安装中文字体（Linux）
// sudo apt-get install fonts-wqy-zenhei fonts-wqy-microhei

// 或在启动时指定字体
const browser = await puppeteer.launch({
  args: ['--font-render-hinting=none']
});

配置最佳实践 #

开发环境配置 #

javascript

const browser = await puppeteer.launch({
  headless: false,
  devtools: true,
  slowMo: 50,
  defaultViewport: {
    width: 1920,
    height: 1080
  }
});

生产环境配置 #

javascript

const browser = await puppeteer.launch({
  headless: 'new',
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
    '--disable-gpu',
    '--disable-software-rasterizer',
    '--disable-extensions',
    '--disable-plugins'
  ]
});

爬虫配置 #

javascript

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

// 隐藏 webdriver 特征
await page.evaluateOnNewDocument(() => {
  Object.defineProperty(navigator, 'webdriver', {
    get: () => false
  });
  
  window.chrome = {
    runtime: {}
  };
  
  Object.defineProperty(navigator, 'plugins', {
    get: () => [1, 2, 3, 4, 5]
  });
});

验证安装 #

检查版本 #

javascript

const puppeteer = require('puppeteer');

console.log('Puppeteer version:', puppeteer.version());

(async () => {
  const browser = await puppeteer.launch();
  console.log('Chromium version:', await browser.version());
  await browser.close();
})();

完整测试脚本 #

javascript

const puppeteer = require('puppeteer');

async function test() {
  console.log('🚀 启动浏览器...');
  const browser = await puppeteer.launch();
  
  console.log('📄 创建页面...');
  const page = await browser.newPage();
  
  console.log('🌐 访问网页...');
  await page.goto('https://example.com');
  
  console.log('📸 截图...');
  await page.screenshot({ path: 'test-screenshot.png' });
  
  console.log('📝 获取标题...');
  const title = await page.title();
  console.log('标题:', title);
  
  console.log('✅ 测试完成！');
  await browser.close();
}

test().catch(console.error);

下一步 #

现在你已经完成了 Puppeteer 的安装和配置，接下来学习基础用法开始编写自动化脚本！