Puppeteer-core 在 M2 芯片 Mac 上环境变量失效问题解析

问题背景

在使用 Puppeteer 项目时，开发者经常需要指定 Chromium 可执行文件的路径。根据官方文档说明，可以通过设置 PUPPETEER_EXECUTABLE_PATH 环境变量来实现这一目的。然而，当开发者在搭载 M2 芯片的 Mac 电脑上使用 puppeteer-core 包时，发现该环境变量并未生效，导致程序抛出错误提示需要显式指定 executablePath。

核心问题分析

经过深入调查，我们发现这个问题实际上与 M2 芯片无关，而是源于 puppeteer-core 和 puppeteer 两个包在设计理念上的根本区别：

1. puppeteer 是一个完整的产品级包，内置了 Chromium 下载和管理功能，支持通过环境变量进行配置
2. puppeteer-core 是一个轻量级库包，专门为需要精细控制浏览器环境的场景设计，它不包含任何默认配置逻辑

技术原理详解

puppeteer-core 的设计哲学是提供纯粹的 API 接口，而不做任何隐式假设。这种设计带来了几个关键特性：

• 不自动下载或管理浏览器二进制文件
• 不读取任何环境变量配置
• 需要开发者显式指定所有必要参数
• 保持极小的包体积和清晰的职责边界

这种设计虽然增加了些许使用复杂度，但为高级用户提供了完全的掌控权，特别是在以下场景中特别有价值：

• 需要精确控制浏览器版本
• 在受限环境中使用自定义构建的 Chromium
• 集成到已有浏览器管理系统中
• 构建轻量级应用时避免不必要的依赖

解决方案

对于遇到此问题的开发者，有以下几种解决方案：

1. 显式指定 executablePath（推荐）： 在调用 launch 方法时直接传入可执行文件路径：

   const browser = await puppeteer.launch({
     executablePath: '/path/to/chrome'
   });
   

2. 改用完整版 puppeteer： 如果不需要精细控制，可以使用完整版 puppeteer 包，它会自动处理浏览器下载和环境变量。

3. 实现自定义配置层： 可以自行封装一个配置模块，统一管理浏览器路径，然后在各处调用时使用。

最佳实践建议

基于 Puppeteer 生态的使用经验，我们建议：

1. 明确项目需求，选择适合的包：

   • 快速原型开发 → 使用 puppeteer
   • 生产环境精细控制 → 使用 puppeteer-core

2. 建立项目级的浏览器管理策略：

   • 统一存放浏览器二进制文件
   • 使用配置文件而非环境变量
   • 考虑版本锁定机制

3. 文档化浏览器依赖： 在项目文档中明确记录所需的浏览器版本和获取方式，便于团队协作和后续维护。

总结

理解 puppeteer-core 的设计理念对于正确使用它至关重要。这个包不是 puppeteer 的简单替代品，而是为特定场景设计的工具。通过显式配置而非隐式约定，它为高级用户提供了更强的灵活性和控制力。希望本文能帮助开发者更好地理解这一区别，并在实际项目中做出合适的技术选型。