Puppeteer logo Puppeteer
登录
15. 项目实战与最佳实践

15.项目实战与最佳实践

经过前面十四章的系统学习，我们已经掌握了 Puppeteer 的核心 API、调试技巧、性能优化以及云端部署等知识。本章将通过一个完整的爬虫项目，把这些零散的知识点串联起来，形成一套可维护、可扩展的生产级实践方案。这个实战项目不会追求复杂的业务逻辑，而是聚焦于如何把 Puppeteer 用得稳健、用得优雅。

完整爬虫项目实战

项目需求与设计思路

假设我们需要定期监控某个电商平台的商品价格变化。这个任务听起来简单，实际落地时会遇到各种细节问题：如何应对页面结构变动？如何防止爬虫被识别？如何保证数据不丢失？如何监控抓取性能？

我们先定义项目的核心需求：

  • 支持多商品并发抓取
  • 自动处理登录状态
  • 遇到网络错误自动重试
  • 抓取结果持久化存储
  • 记录详细的运行日志
  • 可配置化，支持不同环境

基于这些需求，项目会拆分成五个核心模块：配置管理、浏览器实例管理、页面解析逻辑、数据存储层，以及错误处理与重试机制。这种分层设计让代码职责清晰，也方便后续扩展。

配置管理模块

配置管理是项目的基石。把硬编码的参数抽离到配置文件中，可以让我们在修改抓取目标、调整并发数时不用重新部署代码。

// config.ts
interface CrawlerConfig {
  // 目标网站配置
  target: {
    baseUrl: string;
    loginUrl: string;
    productUrlPattern: RegExp;
  };
  // Puppeteer 启动参数
  browser: {
    headless: boolean;
    slowMo: number;
    args: string[];
  };
  // 抓取策略
  crawler: {
    concurrency: number;
    timeout: number;
    retryAttempts: number;
    retryDelay: number;
  };
  // 日志级别
  logging: {
    level: 'debug' | 'info' | 'warn' | 'error';
    outputDir: string;
  };
}

export const config: CrawlerConfig = {
  target: {
    baseUrl: 'https://example-ecommerce.com',
    loginUrl: 'https://example-ecommerce.com/login',
    productUrlPattern: /^https:\/\/example-ecommerce\.com\/product\/\d+$/,
  },
  browser: {
    headless: true,
    slowMo: 50,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
      '--disable-accelerated-2d-canvas',
      '--disable-gpu',
    ],
  },
  crawler: {
    concurrency: 3,
    timeout: 30000,
    retryAttempts: 3,
    retryDelay: 2000,
  },
  logging: {
    level: 'info',
    outputDir: './logs',
  },
};

这段配置把不同维度的参数分门别类。target 定义了抓取目标，browser 控制 Puppeteer 的启动行为，crawler 设置抓取策略，logging 管理日志输出。通过调整 concurrency 可以控制并发数，避免对目标网站造成过大压力；retryAttempts 和 retryDelay 为后续的重试机制提供参数支持。

浏览器管理模块

浏览器实例管理要解决两个核心问题：一是如何复用浏览器实例减少启动开销，二是如何隔离不同页面的 Cookie 和缓存避免状态污染。

// browser-manager.ts
import puppeteer, { Browser, BrowserContext } from 'puppeteer';
import { config } from './config';
import { logger } from './logger';

export class BrowserManager {
  private browser: Browser | null = null;
  private context: BrowserContext | null = null;

  async init(): Promise<void> {
    logger.info('正在启动浏览器实例...');
    
    this.browser = await puppeteer.launch({
      headless: config.browser.headless,
      slowMo: config.browser.slowMo,
      args: config.browser.args,
    });

    // 创建独立的浏览器上下文，实现会话隔离
    this.context = await this.browser.createBrowserContext();
    
    logger.info('浏览器启动完成');
  }

  async createPage() {
    if (!this.context) {
      throw new Error('浏览器上下文未初始化');
    }

    const page = await this.context.newPage();
    
    // 设置统一的页面超时
    page.setDefaultTimeout(config.crawler.timeout);
    
    // 拦截图片加载提升性能
    await page.setRequestInterception(true);
    page.on('request', (req) => {
      if (req.resourceType() === 'image') {
        req.abort();
      } else {
        req.continue();
      }
    });

    // 记录页面错误
    page.on('pageerror', (error) => {
      logger.error('页面错误:', error);
    });

    return page;
  }

  async close(): Promise<void> {
    if (this.context) {
      await this.context.close();
      this.context = null;
    }
    
    if (this.browser) {
      await this.browser.close();
      this.browser = null;
    }
    
    logger.info('浏览器已关闭');
  }

  get isInitialized(): boolean {
    return this.browser !== null && this.context !== null;
  }
}

这个管理器封装了浏览器的生命周期。createBrowserContext 的调用是关键，它为每次抓取任务创建独立的上下文，避免 Cookie 和本地存储相互干扰。请求拦截器屏蔽了图片资源，这在爬虫场景中能显著降低带宽消耗和提升加载速度。页面错误监听帮助我们捕获 JavaScript 运行时异常，这些信息对排查抓取失败原因很有价值。

页面解析模块

页面解析是业务逻辑的核心。我们需要把 Puppeteer 的操作封装成可复用的函数，每个函数只负责一个原子操作。

// page-parser.ts
import { Page } from 'puppeteer';
import { config } from './config';
import { logger } from './logger';

export interface ProductInfo {
  url: string;
  title: string;
  price: number;
  stock: number;
  timestamp: Date;
}

export class PageParser {
  async login(page: Page, username: string, password: string): Promise<boolean> {
    logger.info(`正在登录: ${username}`);
    
    await page.goto(config.target.loginUrl);
    
    // 使用 Locator API 填充表单
    await page.locator('input[name="username"]').fill(username);
    await page.locator('input[name="password"]').fill(password);
    
    // 点击登录按钮并等待导航
    await Promise.all([
      page.waitForNavigation({ waitUntil: 'networkidle2' }),
      page.locator('button[type="submit"]').click(),
    ]);

    const isLoggedIn = await page.locator('.user-profile').waitHandle().then(() => true).catch(() => false);
    
    logger.info(isLoggedIn ? '登录成功' : '登录失败');
    return isLoggedIn;
  }

  async extractProductInfo(page: Page, productUrl: string): Promise<ProductInfo | null> {
    logger.info(`正在抓取商品: ${productUrl}`);
    
    await page.goto(productUrl);
    
    try {
      // 等待关键元素加载
      await page.locator('.product-detail').wait();
      
      // 在页面上下文中执行数据提取
      const data = await page.evaluate(() => {
        const title = document.querySelector('h1.product-title')?.textContent?.trim() || '';
        const priceText = document.querySelector('.price-current')?.textContent || '0';
        const stockText = document.querySelector('.stock-status')?.textContent || '0';
        
        return {
          title,
          price: parseFloat(priceText.replace(/[^\d.]/g, '')),
          stock: parseInt(stockText.replace(/[^\d]/g, ''), 10),
        };
      });

      return {
        url: productUrl,
        title: data.title,
        price: data.price,
        stock: data.stock,
        timestamp: new Date(),
      };
    } catch (error) {
      logger.error(`商品信息提取失败: ${productUrl}`, error);
      return null;
    }
  }
}

这里使用了 Locator API，这是 Puppeteer 推荐的现代定位方式，比传统的 page.$ 和 page.$$ 更稳定。login 方法演示了如何等待导航完成，extractProductInfo 展示了在 page.evaluate 中执行浏览器端代码提取数据。注意我们在 evaluate 中只返回可序列化的简单对象，这是 Puppeteer 的限制，也是最佳实践。

数据存储模块

抓取的数据需要持久化。这里实现一个简单的文件存储，实际生产环境可以替换为数据库。

// storage.ts
import { promises as fs } from 'fs';
import { join } from 'path';
import { ProductInfo } from './page-parser';
import { logger } from './logger';

export class Storage {
  private dataDir: string;

  constructor(dataDir: string = './data') {
    this.dataDir = dataDir;
  }

  async save(products: ProductInfo[]): Promise<void> {
    const timestamp = new Date().toISOString().slice(0, 10);
    const filename = join(this.dataDir, `products-${timestamp}.json`);
    
    try {
      await fs.mkdir(this.dataDir, { recursive: true });
      
      const existingData: ProductInfo[] = [];
      try {
        const rawData = await fs.readFile(filename, 'utf-8');
        existingData.push(...JSON.parse(rawData));
      } catch {
        // 文件不存在时忽略
      }

      existingData.push(...products);
      
      await fs.writeFile(filename, JSON.stringify(existingData, null, 2));
      logger.info(`已保存 ${products.length} 条商品数据到 ${filename}`);
    } catch (error) {
      logger.error('数据保存失败', error);
      throw error;
    }
  }
}

存储模块负责把抓取结果写入磁盘。按日期分文件存储，方便后续分析价格趋势。fs.mkdir 的 recursive: true 参数确保目录存在，避免手动创建。读取现有数据再追加的方式，实现了简单的增量更新。

错误处理与重试机制

错误分类与捕获策略

爬虫运行中会遇到各种错误：网络超时、页面结构变化、JavaScript 异常。不加处理的错误会导致整个任务失败，因此需要分类处理。

// errors.ts
export enum ErrorType {
  NETWORK_ERROR = 'NETWORK_ERROR',
  PARSE_ERROR = 'PARSE_ERROR',
  LOGIN_ERROR = 'LOGIN_ERROR',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
}

export class CrawlerError extends Error {
  constructor(
    message: string,
    public type: ErrorType,
    public originalError?: Error
  ) {
    super(message);
    this.name = 'CrawlerError';
  }
}

export function classifyError(error: Error): ErrorType {
  if (error.message.includes('net::ERR')) {
    return ErrorType.NETWORK_ERROR;
  }
  if (error.message.includes('Timeout')) {
    return ErrorType.NETWORK_ERROR;
  }
  if (error.message.includes('selector')) {
    return ErrorType.PARSE_ERROR;
  }
  return ErrorType.UNKNOWN_ERROR;
}

错误分类让我们能针对不同类型的错误采取不同的恢复策略。网络错误通常可以通过重试解决，而解析错误可能意味着页面结构变化，需要人工介入。

智能重试实现

重试机制需要避免无脑重试，应该加入指数退避策略，防止对故障服务造成更大压力。

// retry-handler.ts
import { config } from './config';
import { logger } from './logger';
import { CrawlerError, ErrorType, classifyError } from './errors';

export async function withRetry<T>(
  operation: () => Promise<T>,
  context: string
): Promise<T> {
  let lastError: Error | null = null;

  for (let attempt = 1; attempt <= config.crawler.retryAttempts; attempt++) {
    try {
      logger.debug(`[${context}] 第 ${attempt} 次尝试`);
      return await operation();
    } catch (error) {
      lastError = error as Error;
      const errorType = classifyError(lastError);
      
      logger.warn(`[${context}] 操作失败: ${errorType}`, lastError);

      // 解析错误不重试
      if (errorType === ErrorType.PARSE_ERROR) {
        throw new CrawlerError(
          `解析失败，可能需要更新选择器: ${context}`,
          ErrorType.PARSE_ERROR,
          lastError
        );
      }

      // 最后一次尝试后不再重试
      if (attempt === config.crawler.retryAttempts) {
        break;
      }

      // 指数退避延迟
      const delay = config.crawler.retryDelay * Math.pow(2, attempt - 1);
      logger.info(`[${context}] ${delay}ms 后重试...`);
      await sleep(delay);
    }
  }

  throw new CrawlerError(
    `[${context}] 达到最大重试次数`,
    classifyError(lastError!),
    lastError!
  );
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

withRetry 是一个高阶函数，接收异步操作和上下文信息。它根据错误类型决定是否重试，对解析错误直接抛出，避免无意义重试。指数退避策略通过 Math.pow(2, attempt - 1) 实现，第一次延迟 2 秒，第二次 4 秒，第三次 8 秒，给服务恢复留出时间。

代码模块化组织

模块划分原则

前面的代码已经展示了模块化雏形。这里再补充一个主协调器，把所有模块串联起来。

// crawler.ts
import { BrowserManager } from './browser-manager';
import { PageParser } from './page-parser';
import { Storage } from './storage';
import { withRetry } from './retry-handler';
import { logger } from './logger';
import { config } from './config';

export class Crawler {
  private browserManager: BrowserManager;
  private parser: PageParser;
  private storage: Storage;

  constructor() {
    this.browserManager = new BrowserManager();
    this.parser = new PageParser();
    this.storage = new Storage();
  }

  async run(productUrls: string[]): Promise<void> {
    logger.info(`开始抓取任务，共 ${productUrls.length} 个商品`);
    
    try {
      await this.browserManager.init();
      
      // 并发控制
      const concurrency = config.crawler.concurrency;
      const results: any[] = [];

      for (let i = 0; i < productUrls.length; i += concurrency) {
        const batch = productUrls.slice(i, i + concurrency);
        const batchResults = await Promise.allSettled(
          batch.map(url => this.processProduct(url))
        );
        
        results.push(...batchResults);
      }

      // 统计结果
      const successCount = results.filter(r => r.status === 'fulfilled').length;
      const failureCount = results.length - successCount;
      
      logger.info(`任务完成: 成功 ${successCount}, 失败 ${failureCount}`);
    } finally {
      await this.browserManager.close();
    }
  }

  private async processProduct(url: string) {
    const page = await this.browserManager.createPage();
    
    try {
      // 使用重试包装抓取逻辑
      const productInfo = await withRetry(
        () => this.parser.extractProductInfo(page, url),
        `抓取商品: ${url}`
      );

      if (productInfo) {
        await this.storage.save([productInfo]);
      }
    } finally {
      await page.close();
    }
  }
}

协调器 Crawler 类负责整体流程控制。run 方法实现了分批并发，避免一次性打开过多页面。Promise.allSettled 让我们能收集所有结果，包括失败的。finally 块确保页面一定会关闭，防止资源泄漏。

依赖注入与解耦

上面的代码中，模块之间还是存在硬依赖。我们可以通过依赖注入进一步提升可测试性。

// crawler-di.ts
import { BrowserManager } from './browser-manager';
import { PageParser } from './page-parser';
import { Storage } from './storage';
import { withRetry } from './retry-handler';
import { logger } from './logger';
import { config } from './config';

export class CrawlerDI {
  constructor(
    private browserManager: BrowserManager,
    private parser: PageParser,
    private storage: Storage
  ) {}

  async run(productUrls: string[]): Promise<void> {
    // 与上面相同的实现逻辑
    // 但依赖由外部注入，方便单元测试时 mock
  }
}

// 使用示例
const crawler = new CrawlerDI(
  new BrowserManager(),
  new PageParser(),
  new Storage()
);

依赖注入让 CrawlerDI 不再负责创建依赖，而是由调用方传入。测试时可以传入 mock 对象，验证各个模块的交互是否符合预期。

性能监控与日志

关键指标采集

性能监控帮助我们了解爬虫的运行效率，及时发现瓶颈。

// metrics.ts
import { logger } from './logger';

export class Metrics {
  private startTime: number = 0;
  private operationCount: number = 0;
  private errorCount: number = 0;

  start(): void {
    this.startTime = Date.now();
    this.operationCount = 0;
    this.errorCount = 0;
  }

  recordOperation(): void {
    this.operationCount++;
  }

  recordError(): void {
    this.errorCount++;
  }

  stop(): void {
    const duration = Date.now() - this.startTime;
    const opsPerSecond = (this.operationCount / duration * 1000).toFixed(2);
    
    logger.info('性能统计:', {
      运行时长: `${duration}ms`,
      操作次数: this.operationCount,
      错误次数: this.errorCount,
      每秒操作数: opsPerSecond,
    });
  }
}

Metrics 类记录运行时长、操作次数和错误次数。opsPerSecond 指标能直观反映爬虫效率。把这些数据输出到日志，方便后续分析。

日志分级与输出

日志是排查问题的生命线。我们需要分级管理，避免调试信息淹没重要错误。

// logger.ts
import { createLogger, format, transports } from 'winston';
import { config } from './config';

const logLevel = config.logging.level;

export const logger = createLogger({
  level: logLevel,
  format: format.combine(
    format.timestamp(),
    format.errors({ stack: true }),
    format.json()
  ),
  transports: [
    new transports.Console({
      format: format.combine(
        format.colorize(),
        format.simple()
      ),
    }),
    new transports.File({
      filename: `${config.logging.outputDir}/error.log`,
      level: 'error',
    }),
    new transports.File({
      filename: `${config.logging.outputDir}/combined.log`,
    }),
  ],
});

这里使用 winston 库实现专业日志管理。控制台输出使用彩色格式，方便开发时查看；错误日志单独写入文件，便于监控告警；所有日志以 JSON 格式存储，方便后续用工具分析。日志级别通过配置文件控制，生产环境可以设为 warn，减少日志量。

总结

写到这里，我们已经完成了一个具备生产级质量的 Puppeteer 爬虫项目。回顾全书内容，从第一章的环境搭建，到最后一章的项目实战，我们走过了一条从入门到精通的道路。

最初我们学习了如何启动浏览器、打开页面，这是自动化的起点。接着深入元素定位与交互，理解了显式等待的重要性，避免了 flaky test 的陷阱。JavaScript 执行与数据提取章节让我们掌握了在浏览器上下文中运行代码的技巧，这是 Puppeteer 最强大的能力之一。

网络请求拦截与 Mock 为我们打开了控制网络层的大门，让测试不再依赖外部服务。调试技巧与日志分析教会我们在无头浏览器这个黑盒中定位问题。Cookie、存储与状态管理让我们能够模拟真实用户会话。截图、PDF 与媒体处理扩展了自动化的输出能力。

无头模式与性能优化让我们把脚本部署到服务器，而高级页面交互技巧则应对了现代 Web 应用的复杂性。Chrome 扩展与浏览器集成展示了 Puppeteer 的生态系统。Docker 容器化部署和云端环境配置让自动化脚本真正跑在生产环境。跨浏览器自动化与 WebDriver BiDi 则为未来多浏览器支持铺平了道路。

最后一章的项目实战，把这些知识点编织成网。配置管理让脚本灵活，浏览器管理让资源可控，页面解析让逻辑清晰，数据存储让结果持久，错误处理让系统稳健，性能监控让运行透明。每个模块都不复杂，但组合在一起就构成了可靠的系统。

Puppeteer 的学习曲线并不陡峭，但要用好它，需要理解浏览器的工作原理、网络协议的细节、异步编程的模式，以及软件工程的最佳实践。希望这本书不仅教会了 API 的使用，更传递了一种思路：自动化不是简单的脚本堆砌，而是需要设计、需要架构、需要用心维护的软件项目。

自动化测试、网页抓取、性能监控，这些场景背后都是同一个核心诉求——让机器代替重复劳动。Puppeteer 给了我们这个能力，但如何用得优雅、用得稳健，取决于我们怎么组织代码、怎么处理异常、怎么监控运行。这些工程实践，比 API 本身更重要。

技术总在演进，Puppeteer 也会继续发展。但掌握了这些核心思想和实践模式，无论工具如何变化，我们都能快速适应。毕竟，好的自动化方案，从来都不是依赖某个特定 API，而是建立在清晰的架构和稳健的工程实践之上。

上一章

跨浏览器自动化与WebDriver BiDi