lighthouse ci是基于node.js的cli工具，非html功能，需在ci中启动本地服务后通过lhci collect访问并用lhci assert校验阈值，依赖chrome实例执行审计，无法在静态html中直接调用。
Lighthouse CI 不是 HTML 的功能，它是一个独立的 Node.js CLI 工具，用于在 CI 环境中运行 lighthouse 审计。你无法“用 HTML 调用 Lighthouse CI”，但可以在构建流程中让它自动访问你的本地服务并检测已部署或预览的页面。
为什么不能直接在 HTML 里集成 Lighthouse CI
Lighthouse CI 运行在 Node.js 环境，依赖 Chrome 实例执行真实浏览器审计；HTML 是静态文档，没有执行能力，也无法启动浏览器进程或读取本地服务器状态。常见误解是把 lighthouse 浏览器插件、DevTools 面板和 CI 工具混为一谈。
真正要做的，是在 CI 流程（如 GitHub Actions、GitLab CI）中：
- 先启动一个本地 HTTP 服务（例如
npx serve -s build或python3 -m http.server 3000） - 再让
lhci collect去访问http://localhost:3000 - 最后用
lhci assert检查得分是否达标
GitHub Actions 中跑 Lighthouse CI 的最小可行配置
关键不是写多复杂的 YAML，而是确保 Chrome 可用、服务能响应、URL 可达。以下片段可直接放入 .github/workflows/lighthouse.yml：
name: Lighthouse CI
on: [pull_request]
jobs:
lhci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install & Build
run: |
npm ci
npm run build
- name: Serve & Test
uses: bahmutov/npm-install@v1
with:
command: 'serve -s dist -p 3000'
# 注意：serve 必须后台运行，否则阻塞后续步骤
- name: Wait for server
run: sleep 3
- name: Run LHCI
run: |
npm install -g @lhci/cli
lhci collect --url=http://localhost:3000 --numberOfRuns=1 --collect.settings.chromeFlags='--no-sandbox'
lhci assert --preset=lighthouse:recommended
⚠️ 容易踩的坑：
-
serve默认前台阻塞，必须用nohup serve ... &或换用支持后台的命令（如npx http-server -p 3000 -c-1 dist） - Ubuntu runner 默认没装 Chrome，但
@lhci/cli会自动下载 Chromium，前提是加--no-sandbox -
--numberOfRuns=1在 CI 中更稳定；多次运行可能因资源波动导致分数抖动
可访问性断言怎么写才不误报
categories:accessibility 是最常被滥用的断言项。Lighthouse 的可访问性审计覆盖约 50+ 条规则，但很多依赖人工判断（如 ARIA 标签语义是否恰当），自动化仅能捕获结构缺失。
推荐做法是分层断言：
- 硬性拦截：比如
"axe-core:color-contrast"（颜色对比度）必须 > 0.95，这个有明确数值标准 - 警告不中断：把
"best-practices:aria-allowed-attr"设为["warn"]，只报错不失败 - 跳过不可控项：如
"accessibility:link-in-text-block"在 CMS 渲染内容时无法干预，直接 exclude
示例断言配置（lighthouserc.json）：
"assert": {
"assertions": {
"categories:accessibility": ["off"],
"axe-core:color-contrast": ["error", {"minScore": 0.95}],
"best-practices:aria-allowed-attr": ["warn"],
"accessibility:link-in-text-block": ["off"]
}
}
本地开发时如何快速验证 CI 配置是否有效
别等 push 到 PR 才发现失败。在本机模拟 CI 环境最可靠的方式是：
- 用
docker run --rm -it -v $(pwd):/app -w /app node:20 bash进入干净容器 - 手动执行 CI 脚本里的每条命令（
npm ci→npm run build→ 启服务 →lhci collect） - 重点观察
lhci collect是否返回✅ Done collecting!，而不是卡住或报net::ERR_CONNECTION_REFUSED
如果本地能过但 CI 失败，90% 是因为服务没真正监听 0.0.0.0:3000（默认只 listen localhost），需加参数如 serve -s dist -p 3000 -a 0.0.0.0。
CI 环境里没有图形界面、没有用户交互、Chrome 启动方式受限——这些限制决定了它只能做“结构级”检查，别指望它代替人工可访问性测试。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
