最可靠方式是用 puppeteer 启动 chrome 实例再调用 lighthouse node api 或 cli，需显式指定 chrome 路径、启用远程调试端口、匹配版本、独占进程、预创建报告目录，并注意缓存、设备类型与权限问题。
用 Puppeteer 启动 Chrome 并运行 Lighthouse 审计
Lighthouse 本身没有内置的“自动触发”能力，必须通过外部控制浏览器来启动审计。最可靠的方式是用 Puppeteer 启动一个干净、可编程的 Chrome 实例，再调用 lighthouse CLI 或其 Node API。别用无头 Chrome 自己拼接 flag——Lighthouse 对启动参数敏感，比如必须启用 --remote-debugging-port，且不能和 Puppeteer 冲突。
实操建议：
- 用
Puppeteer.launch({ headless: 'new', args: ['--no-sandbox', '--disable-setuid-sandbox'] })启动，headless: 'new'是现代推荐模式，避免旧版 headless 的兼容问题 - 确保 Chrome 版本与
lighthousenpm 包版本匹配（例如 v11+ Lighthouse 要求 Chrome 117+），不匹配会报ERR_CONNECTION_REFUSED或卡在“Connecting to browser...” - 不要复用已存在的 Chrome 进程；Puppeteer 必须独占控制权，否则
lighthouse无法接管调试协议
调用 lighthouse CLI 时传参的关键陷阱
直接执行 lighthouse https://example.com --output html --output json --report-folder ./report --chrome-flags="--headless=new" 看似简单，但实际容易失败。根本原因是：CLI 默认尝试自动查找 Chrome，而 Docker、CI 环境或非标准安装路径下它常找不到，或找到错误版本。
实操建议：
- 显式指定 Chrome 路径：
--chrome-flags="--headless=new --remote-debugging-port=9222"+--chrome-path="/usr/bin/chromium"（Linux）或--chrome-path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"（macOS） - 加
--preset=desktop显式声明设备类型，否则默认用 mobile，可能误判响应式布局得分 - 禁用缓存影响结果：
--extra-headers='{"Cache-Control": "no-cache"}'，否则本地开发服务器反复审计时可能命中内存缓存，性能分虚高
在 Node.js 中用 lighthouse API 替代 CLI 更可控
CLI 适合一次性跑，但要做定时审计、集成进 CI 或动态改 URL/配置时，Node API 是更稳的选择。注意它不是简单封装 CLI，而是直连 CDP，对异常处理要求更高。
实操建议：
- 用
lighthouse(url, { port: 9222, output: ['html', 'json'], onlyCategories: ['performance', 'accessibility'], disableStorageReset: false })，其中disableStorageReset: false是关键——设为true会导致 Service Worker 缓存残留，审计结果不准 - 必须等 Puppeteer 页面完全加载后再调
lighthouse()，推荐监听page.waitForNetworkIdle({ timeout: 10000 })，而非page.goto().then(...)，否则 JS 懒加载资源可能被漏掉 - 返回的
lhr对象里，lhr.categories.performance.score是 0–1 数值，不是百分比；要转成百分制得乘 100，别直接当整数用
CI 环境中生成报告的权限与路径问题
Docker 或 GitHub Actions 下跑 Lighthouse 常见报错：ENOTDIR: not a directory, mkdir './report' 或 HTML 报告打开空白。根源不是代码，而是工作目录不可写、--report-folder 路径未提前创建、或生成的 report.html 引用了相对路径的 JS/CSS 资源却没一并输出。
实操建议：
- CI 中务必先
mkdir -p ./report，再执行 lighthouse 命令；Node API 则用fs.mkdirSync('./report', { recursive: true }) - 用
--output html --output json --view时，--view在无 GUI 环境会失败，删掉它；想预览就 scp 出来或用serve临时起服务 - HTML 报告依赖内联 JS，但某些安全策略（如 CSP）会拦截，若页面本身有严格
script-src 'self'，审计报告打开后白屏，此时应改用--output json提取数据，自行渲染
真正卡住人的往往不是怎么调 API，而是 Chrome 启动参数和文件系统权限这两个点反复出错。跑通一次后，把 Puppeteer 启动、Lighthouse 配置、目录准备这三步封装成函数，比每次查文档快得多。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
