Lighthouse

O que Lighthouse faz?

Execute o Google Lighthouse para medir a qualidade web e verificar se as correções realmente alteraram os números. O Lighthouse audita uma URL em Desempenho, Acessibilidade, SEO e Boas Práticas, retornando uma pontuação de 0–100 por categoria, além de uma lista de auditorias com falhas e orientações específicas.

Quando usar esta habilidade

Esta habilidade mede. Habilidades de qualidade complementares corrigem. O fluxo de trabalho é um ciclo:

medir (esta habilidade)  →  corrigir (desempenho / acessibilidade / seo / boas-práticas)  →  medir novamente

Recorra a esta habilidade para: obter uma pontuação base, encontrar as auditorias específicas com falha, definir um orçamento de desempenho, controlar uma compilação no CI ou comprovar que uma mudança melhorou (ou regrediu) uma métrica. Não adivinhe melhorias — meça, altere uma coisa, meça novamente.

Como funciona

1. Escolha uma URL alvo — uma URL implantada ou um servidor local de desenvolvimento/preview (http://localhost:3000).
2. Execute o Lighthouse — prefira scripts/run-lighthouse.sh <url>; ele executa várias vezes, pega a mediana e emite um JSON compacto (relatórios completos são enormes e desperdiçam contexto).
3. Leia as pontuações das categorias e as auditorias com falha a partir do JSON.
4. Mapeie cada auditoria com falha para uma correção usando a habilidade de qualidade relevante.
5. Execute novamente e reporte a diferença antes/depois.

Instalação e execução (CLI)

O README do Lighthouse o instala globalmente (requer Node 22 LTS+), e ele utiliza um Chrome/Chromium local que você deve ter instalado:

npm install -g lighthouse
# ou: yarn global add lighthouse

lighthouse https://example.com --view    # execução básica; --view abre o relatório HTML

O Lighthouse detecta automaticamente um Chrome instalado; aponte para um binário específico com a variável de ambiente CHROME_PATH.

Para uma execução rápida e única sem instalação global, npx lighthouse <url> também funciona — o binário CLI publicado suporta isso, embora a documentação oficial cubra apenas a instalação global.

Execução legível por máquina para um agente (JSON para arquivo, silencioso, headless):

npx lighthouse https://example.com \
  --quiet \
  --chrome-flags="--headless=new" \
  --only-categories=performance,accessibility,seo,best-practices \
  --output=json --output-path=./lh.json

O script wrapper (recomendado)

scripts/run-lighthouse.sh encapsula o CLI, executa N vezes, pega a execução mediana (orientação do próprio Lighthouse para reduzir variabilidade) e imprime JSON compacto na saída padrão — apenas as pontuações das categorias e as auditorias com falha. Logs para humanos vão para a saída de erro.

# Uso: run-lighthouse.sh <url> [execuções] [categorias]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility

Exemplo de saída:

{
  "success": true,
  "url": "https://example.com",
  "runs": 3,
  "lighthouseVersion": "13.x",
  "scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96 },
  "failingAudits": [
    { "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
    { "id": "unused-javascript", "score": 0.3, "displayValue": "Economia potencial de 180 KiB" }
  ]
}

Principais flags

Flag	Propósito
--output=json|html|csv	Formato do relatório (repita para múltiplos)
--output-path=<caminho>	Onde escrever o relatório
--only-categories=…	Limitar a performance,accessibility,seo,best-practices
--preset=desktop	Configuração de desktop (o padrão é mobile: telefone de médio porte emulado + 4G lento)
--chrome-flags="--headless=new"	Executar headless (CI/servidores)
--budget-path=budget.json	Aplicar um orçamento de desempenho (LightWallet)
--throttling-method=simulate|devtools|provided	Como limitar a rede/CPU (simulate é o padrão de laboratório)
--quiet	Suprimir logs de progresso
--view	Abrir o relatório HTML ao finalizar

Lendo o JSON

As pontuações são floats de 0–1 em categories; os detalhes das auditorias estão em audits.

# Pontuações das categorias (0–1) → multiplique por 100 para a pontuação familiar
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json

# Valores de laboratório dos Core Web Vitals
jq '.audits | {
  LCP: .["largest-contentful-paint"].displayValue,
  CLS: .["cumulative-layout-shift"].displayValue,
  TBT: .["total-blocking-time"].displayValue
}' lh.json

# Auditorias com falha/oportunidades que merecem ação
jq '[.audits[] | select(.score != null and .score < 0.9)
     | {id, score, displayValue}]' lh.json

Orçamentos de desempenho (LightWallet)

Falhe a execução quando ativos ou tempos excederem um limite. Um arquivo examples/budget.json pronto para editar acompanha esta habilidade; o formato é:

[
  {
    "path": "/*",
    "timings": [
      { "metric": "largest-contentful-paint", "budget": 2500 },
      { "metric": "interactive", "budget": 3800 }
    ],
    "resourceSizes": [
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "stylesheet", "budget": 100 },
      { "resourceType": "image", "budget": 500 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 }
    ]
  }
]

lighthouse https://example.com --budget-path=budget.json --output=json --output-path=./lh.json

Tamanhos estão em KB, tempos em ms. Os resultados do orçamento aparecem nas auditorias performance-budget e timing-budget no JSON.

Laboratório vs. campo — leia isto antes de confiar em um número

O Lighthouse é uma ferramenta de laboratório: uma carga sintética, em hardware emulado, com limitação simulada. É reproduzível e ótimo para detectar regressões, mas não representa o que os usuários reais experimentam.

• A variabilidade é real. Uma única execução pode variar ±5–10 pontos. Execute pelo menos 3 vezes e pegue a mediana (o script wrapper faz isso).
• Para dados de usuários reais, use fontes de campo: CrUX, PageSpeed Insights (que mostra ambos laboratório e campo), o relatório de Core Web Vitals do Search Console ou a biblioteca web-vitals reportando para sua análise.
• O INP não pode ser medido em uma única carga do Lighthouse — ele precisa de interações reais. O Lighthouse relata o Tempo de Bloqueio Total (TBT) como seu proxy de laboratório; trate o INP de campo como a fonte da verdade.

Nota sobre o Lighthouse v13 (Insight Audits)

Desde o v13 (Outubro de 2025+), o Lighthouse migrou o Desempenho para Insight Audits. Vários IDs de auditoria de oportunidade legados foram mesclados ou removidos (por exemplo, auditorias relacionadas a CLS → cls-culprits-insight, auditorias de imagem → image-delivery-insight). O conselho permanece o mesmo; apenas os IDs das auditorias e o agrupamento do relatório mudaram. Ao analisar relatórios mais antigos, trate-os como um superconjunto, não uma contradição. Fixe uma versão do Lighthouse no CI para que os IDs de auditoria nos quais você confia permaneçam estáveis.

Como a pontuação de Desempenho é construída

A pontuação de Desempenho é uma combinação ponderada de métricas de laboratório (os pesos mudam entre versões). Nas versões recentes, os principais pesos são aproximadamente:

Métrica	Peso aproximado
Tempo de Bloqueio Total (TBT)	~30%
Maior Pintura com Conteúdo (LCP)	~25%
Mudança Cumulativa de Layout (CLS)	~25%
Primeira Pintura com Conteúdo (FCP)	~10%
Índice de Velocidade	~10%

Como TBT/LCP/CLS dominam, corrigí-los move mais a pontuação. Use a Calculadora de Pontuação do Lighthouse para ver exatamente como uma mudança de métrica se traduz em pontos.

CI e a API programática

Mantidos em referências para manter o foco:

• Integração contínua — @lhci/cli, asserções lighthouserc.js e um fluxo de trabalho do GitHub Actions: references/CI.md
• API programática (Node) — dirigir o Lighthouse com chrome-launcher para fluxos personalizados, fluxos de usuário e execuções em lote: references/PROGRAMMATIC-API.md

Mapeando auditorias para correções

Categoria do Lighthouse	Corrigir com
Desempenho / Core Web Vitals	uma habilidade de desempenho ou Core Web Vitals
Acessibilidade	uma habilidade de acessibilidade / WCAG
SEO	uma habilidade de SEO
Boas Práticas	uma habilidade de segurança / boas práticas

Combine esta habilidade com addyosmani/web-quality-skills para o lado da correção do ciclo.

Referências

• Repositório do Lighthouse
• Opções do CLI do Lighthouse
• Orçamentos de desempenho / LightWallet
• Lighthouse CI
• Pontuação
• Configuração de CI · API programática