lighthouse
Lighthouse audit + improvement loop until targets met. Triggers "lighthouse", "page speed", "improve scores", "LCP", "CLS", "INP", "core web vitals". Repo-wide perf audits ("perf audit") go to /audit performance mode instead.
darkroomengineering · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add darkroomengineering/cc-settings --skill lighthouse技能说明
name: lighthouse description: Lighthouse audit + improvement loop until targets met. Triggers "lighthouse", "page speed", "improve scores", "LCP", "CLS", "INP", "core web vitals". Repo-wide perf audits ("perf audit") go to /audit performance mode instead. context: fork argument-hint: "[url]" allowed-tools:
- Bash
- Read
- Write
- Edit
- Grep
- Glob
- LS
- mcp__chrome-devtools__navigate_page
- mcp__chrome-devtools__take_screenshot
- mcp__chrome-devtools__take_snapshot
- mcp__chrome-devtools__lighthouse_audit requires:
- command: lighthouse install: "npm i -g lighthouse (CLI, used for batched 3x3 averaged audits)"
- mcp: chrome-devtools install: "chrome-devtools MCP — provides on-demand audits + visual regression screenshots"
Lighthouse Optimization Loop
Set a product-neutral scratch root once:
LIGHTHOUSE_DIR="${TMPDIR:-/tmp}/cc-settings-lighthouse"
mkdir -p "$LIGHTHOUSE_DIR"
Use the Chrome DevTools MCP only when the user configured it. Standalone Codex otherwise uses the Lighthouse CLI plus native/manual screenshots; if no visual capture path exists, stop before changing UI and report that visual regression verification is unavailable. This package does not auto-run unpinned registry MCP packages.
Method: 3 mobile + 3 desktop runs per audit, averaged for reliability. After each code change, re-audit and visually verify the page with the configured MCP or the stated manual fallback.
Setup
-
Parse URL from
$ARGUMENTS. If no URL, ask the user. Default:http://localhost:3000 -
Verify prerequisites:
lighthouse --version # CLI must be installed for the batched 3x3 protocolIf lighthouse is missing:
npm install -g lighthouseIf runs fail with a chrome-launcher error or every metric comes backNO_LCP/null, no system Chrome exists — find a real Chrome/Chromium binary (Chrome for Testing, Playwright'schromium-*— NOTchrome-headless-shell, which produces NO_LCP) and exportCHROME_PATH=<binary>before the loop. Record which binary was used; a before/after comparison is only clean when both sides ran the same binary. Check whether the user configured the chrome-devtools MCP. Do not install or auto-run an unpinned registry MCP on their behalf. -
Create results directory:
mkdir -p "$LIGHTHOUSE_DIR" -
Take baseline screenshots before any changes:
mcp__chrome-devtools__navigate_page(type: "url", url:<url>)mcp__chrome-devtools__take_screenshot
Describe the current layout, key elements, and visual state. This is your visual baseline — you will compare against it after every change to catch regressions.
-
Confirm with user: Show the URL, confirm the dev server is running, ask if there are specific pages or routes to audit beyond the main URL.
Audit Protocol
Each audit consists of 3 mobile + 3 desktop runs, averaged per category.
Run the audits
# Mobile runs (Lighthouse default is mobile)
for i in 1 2 3; do
lighthouse <url> \
--output=json \
--output-path="$LIGHTHOUSE_DIR/mobile-$i.json" \
--chrome-flags="--headless --no-sandbox" \
--only-categories=performance,accessibility,best-practices,seo \
--quiet \
2>/dev/null
done
# Desktop runs
for i in 1 2 3; do
lighthouse <url> \
--output=json \
--output-path="$LIGHTHOUSE_DIR/desktop-$i.json" \
--chrome-flags="--headless --no-sandbox" \
--preset=desktop \
--only-categories=performance,accessibility,best-practices,seo \
--quiet \
2>/dev/null
done
Extract scores
For each JSON result file:
cat "$LIGHTHOUSE_DIR/mobile-1.json" | \
jq '{
performance: (.categories.performance.score * 100),
accessibility: (.categories.accessibility.score * 100),
bestPractices: (.categories["best-practices"].score * 100),
seo: (.categories.seo.score * 100)
}'
Compute averages
Average the 3 runs per category for both mobile and desktop. Report as:
## Audit Results
| Category | Mobile (avg) | Desktop (avg) |
|----------|-------------|---------------|
| Performance | XX | XX |
| Accessibility | XX | XX |
| Best Practices | XX | XX |
| SEO | XX | XX |
Extract failing audits
From the JSON, find specific audits that failed or scored poorly:
cat "$LIGHTHOUSE_DIR/mobile-1.json" | \
jq '.audits | to_entries[] | select(.value.score != null and .value.score < 0.9) | {id: .key, score: .value.score, title: .value.title, description: .value.displayValue}'
Sort by impact (lowest scores first). These drive the improvement loop.
Diagnose From the JSON, Not From a Narrative
Before planning any fix, re-derive the bottleneck from the report you just ran. Prior session notes, state files, and issue write-ups go stale and get root causes wrong — treat them as hypotheses to check against the JSON, never as the diagnosis.
Classify the perf gap first:
- TBT high (hundreds of ms) → main-thread problem. Long tasks, hydration,
script execution.
mainthread-work-breakdownandlong-taskstell you where. - TBT low (~tens of ms) but LCP high under
throttlingMethod=simulate→ bytes-on-critical-path problem, NOT execution. Lantern replays observed traffic over simulated slow 4G, so eager bytes inflate LCP even when the page is actually fast. Fixes that defer execution will not move this; only removing or lazy-loading bytes will.
Do not read mainthread-work-breakdown's total as "blocking work before
paint" — it is the whole page load. TBT is the blocking measure.
For bytes-on-critical-path gaps, attribute before fixing:
jq '.audits["resource-summary"].details.items[] | {resourceType, requestCount, transferSize}' "$LIGHTHOUSE_DIR/mobile-1.json"
jq '.audits["bootup-time"].details.items[:5]' "$LIGHTHOUSE_DIR/mobile-1.json"
jq '.audits["network-requests"].details.items | sort_by(-.transferSize)
阅读完整来源 ↗