解决 lightweight-charts 项目中 Puppeteer 安装与测试问题

在 lightweight-charts 项目开发过程中，开发者可能会遇到 Puppeteer 相关的安装和测试问题。本文将深入分析这些问题的根源，并提供多种解决方案。

问题现象

当开发者尝试运行 npm run build 或执行端到端测试时，可能会遇到以下错误：

1. Chrome 浏览器下载失败，提示 Failed to set up chrome-headless-shell
2. 文件路径不存在错误 ENOENT: no such file or directory
3. 无法找到指定版本的 Chrome 浏览器

这些问题通常发生在 macOS ARM 架构设备上，特别是在 M1/M2 芯片的 Mac 电脑上。

问题根源分析

这些问题的根本原因在于：

1. Puppeteer 默认会尝试下载特定版本的 Chrome 浏览器用于测试
2. 项目配置中指定了缓存目录 .cache/puppeteer，但权限或路径可能存在问题
3. ARM 架构设备的兼容性问题
4. 缓存机制在不同环境下的行为不一致

解决方案

方案一：跳过 Puppeteer 下载（仅开发）

如果不需要运行端到端测试，可以在安装依赖时跳过 Puppeteer 的浏览器下载：

PUPPETEER_SKIP_DOWNLOAD=true npm install

这种方法适合只需要构建项目而不需要运行测试的场景。

方案二：完整解决测试环境问题

如果需要完整的测试功能，可以按照以下步骤操作：

1. 清理现有环境

rm -rf node_modules
npm cache clean --force

2. 重新安装依赖

npm install

3. 如果仍然遇到问题，可以尝试修改 .puppeteerrc.cjs 配置文件，移除或调整 cacheDirectory 设置

方案三：手动安装浏览器

对于更复杂的情况，可以手动安装浏览器：

1. 首先跳过自动下载

PUPPETEER_SKIP_DOWNLOAD=true npm install

2. 手动安装浏览器

npx puppeteer browsers install

3. 在 .puppeteerrc.js 中明确指定浏览器路径

executablePath: 'node_modules/.cache/puppeteer/chrome/mac_arm-132.0.6834.83/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing'

生产环境构建建议

对于生产环境构建，建议使用：

npm run build:prod

或

npm run build:release

这些命令会跳过开发依赖和测试相关的步骤，专注于生成生产可用的代码。

最佳实践

1. 对于 CI/CD 环境，确保缓存目录可写
2. 在 ARM 架构设备上，确认下载的浏览器版本兼容
3. 定期清理 npm 缓存以避免冲突
4. 考虑在团队中统一开发环境配置

通过以上方法，开发者可以有效地解决 lightweight-charts 项目中与 Puppeteer 相关的安装和测试问题，确保开发流程顺利进行。