claude-seo 的 Unlighthouse 扩展：零配额多页面 Lighthouse 审计的安装、路由与源码解析

Unlighthouse 是一个 MIT 许可的多页面 Lighthouse 运行器，能够对整站所有 URL 逐一执行 Lighthouse 审计并汇总为单一聚合报告，不需要 API 配额、不需要任何凭据，除了爬取目标站点外也没有额外网络外发。本文基于 claude-seo 仓库中 extensions/unlighthouse/docs/UNLIGHTHOUSE-SETUP.md 展开，完整讲解该扩展的安装、验证、卸载流程，/seo unlighthouse命令的路由规则与全部参数，并深入 scripts/unlighthouse_run.py 的源码实现，说明其 SSRF 安全前检、Node 环境检查、超时管理与结果解析机制。读完本文，你将掌握如何在本地、离线或 CI 环境中对整站进行免费的全量 Core Web Vitals（CWV）实验室测量，并能在 Unlighthouse 与 PageSpeed Insights 之间做出正确选型。

为什么需要 Unlighthouse：单 URL 审计之外的整站方案

PageSpeed Insights（PSI）免费配额（约 25,000 QPD）对于大型站点往往不够用，而逐 URL 调用 PSI API 的聚合工作流在没有付费 Google Cloud 账单的情况下几乎不可行。Unlighthouse 恰好填补了这一空白：它在本机运行 Lighthouse 实验室测试，通过爬取站点收集全部（或设定上限的）路由，输出一份聚合报告。

从 scripts/unlighthouse_run.py 的模块文档可以确认其定位：它是"对站点每个 URL 运行 PageSpeed 并聚合结果"这一工作流的最接近的免费等价物。同时，Unlighthouse 是本地运行的，因此在离线或受限环境（如无法访问外部 API 的 CI 网络）中依然可用。

该扩展属于 claude-seo 的 extension 体系：安装脚本将seo-unlighthouse技能复制进~/.claude/skills/，使 Claude Code 可以通过/seo unlighthouse命令直接调度，底层由统一的 scripts/unlighthouse_run.py 封装器驱动。

安装：两条命令、三个步骤、零凭据

安装命令

在仓库根目录执行以下任一脚本即可（bash 与 PowerShell 二选一）：

./extensions/unlighthouse/install.sh

.\extensions\unlighthouse\install.ps1

安装器做了什么

对照 install.sh 与 install.ps1 的源码，安装流程共三步：

1. 校验环境：检查 Python 3 与 Node 18+（npx）是否在$PATH上；同时确认~/.claude/skills/seo已存在——也就是说，必须先安装 claude-seo 基础技能，Unlighthouse 扩展才能安装成功。两个安装器对任一前置条件缺失都会立即报错退出。
2. 预热 Unlighthouse：通过npx --yes --package=unlighthouse@0.13.5 unlighthouse-ci --help把固定版本的unlighthouse@0.13.5下载到 npx 缓存，之后的每次运行都直接命中缓存，不再重复下载。
3. 复制技能文件：将extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md复制为~/.claude/skills/seo-unlighthouse/SKILL.md，让 Claude Code 能够发现并路由/seo unlighthouse命令。

整个安装过程不需要任何 API Key，也不会修改 settings.json。卸载时运行 uninstall.sh，它只删除技能目录，并特别注明"没有任何需要从 settings.json 移除的内容——Unlighthouse 没有密钥"。

版本固定值得注意：封装器与安装器都将 Unlighthouse 钉死在unlighthouse@0.13.5（见 scripts/unlighthouse_run.py），保证 CI 或本机多次运行的行为可复现。

验证安装与命令路由

安装完成后，用一条最小命令验证：

/seo unlighthouse https://example.com --max-routes 5

技能的路由规则定义在 extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md 中，汇总如下：

所有旗标（flag）都会转发给scripts/unlighthouse_run.py，由它统一处理 url_safety 安全前检与子进程超时管理（见下一节）。--max-routes通过--scanner参数以 JSON 形式传入{"maxRoutes": N}，即控制 Unlighthouse 爬虫最多审计的路由数量，避免对超大站点产生不可控的审计时长。

封装器源码解析：安全前检、Node 检查、超时与结果

调用入口与命令行参数

unlighthouse_run.py是一个薄封装，CLI 参数如下（scripts/unlighthouse_run.py）：

直接命令行调用示例：

python scripts/unlighthouse_run.py https://example.com python scripts/unlighthouse_run.py https://example.com --json python scripts/unlighthouse_run.py https://example.com --device desktop --max-routes 50

SSRF 安全前检

在启动任何子进程之前，封装器会调用validate_url_strict(target)（scripts/unlighthouse_run.py）。这一步来自仓库的统一安全模块 scripts/url_safety.py：validate_url_strict会执行 DNS 解析，检查每一个返回的 A 记录是否都是公网地址，任何私有、回环、保留、链路本地或多播地址都会抛出URLSafetyError，从而同时阻断 SSRF 与 DNS rebinding 攻击。测试 tests/test_technical_depth.py 用http://192.168.1.1/验证了这一行为：私有 IP 目标会被直接拒绝并返回{"ok": False, "error": "url_safety: ..."}。

Node 环境检查

安全校验通过后，封装器通过shutil.which("npx")检查 Node 是否可用（scripts/unlighthouse_run.py）；找不到npx时返回错误并提示安装 Node.js 18+。对应的测试 tests/test_technical_depth.py 通过 monkeypatch 模拟npx缺失，确认返回错误路径而非抛出异常。

实际命令构造与超时管理

无--output-dir时使用tempfile.mkdtemp(prefix="claude-seo-unlighthouse-")创建临时输出目录。随后构造子进程命令（scripts/unlighthouse_run.py）：

npx --yes --package unlighthouse@0.13.5 unlighthouse-ci \ --site <target> \ --device mobile|desktop \ --output-path <out_dir> \ --build-static-files \ [--scanner '{"maxRoutes": N}']

子进程以 600 秒（可调）超时运行，超时返回{"ok": False, "error": "...timed out after 600s", "output_dir": ...}——注意输出目录会被保留，便于排查半成品结果；FileNotFoundError也被单独捕获并返回可读错误。

结果解析与输出

封装器从输出目录读取 Unlighthouse 写入的ci-result.json（scripts/unlighthouse_run.py），解析后返回结构化结果。返回对象包含：

• ok/exit_code：子进程是否成功；
• target：规范化后的目标 URL；
• output_dir：报告目录绝对路径；
• summary：ci-result.json的完整内容；
• stdout_tail/stderr_tail：子进程输出的末尾 2000 字符，便于排查失败原因。

技能文档（extensions/unlighthouse/skills/seo-unlighthouse/SKILL.md）明确说明了聚合字段的语义：score.performance为所有审计路由的中位数，另有score.accessibility、score.bestPractices、score.seo；逐路由明细可查<output_dir>/ci-result.json。非--json模式下，CLI 会把scores或score字段逐个打印成键 值形式，便于人读。

Unlighthouse 与 PageSpeed Insights：如何选型

原文档给出的选型对照表是理解二者定位的核心，完整保留如下：

一个必须牢记的差异：PSI 在可用时使用 CrUX 字段数据（真实用户）；Unlighthouse 在本地运行 Lighthouse 实验室测试。因此，若要衡量生产流量的可信 Core Web Vitals，应优先选择 PSI / CrUX。Unlighthouse 的价值在于覆盖面与成本：当你的目标是"整站几百个页面全部测一遍"且不想消耗 API 配额时，本地聚合是更合适的手段。

卸载

./extensions/unlighthouse/uninstall.sh

卸载器只删除~/.claude/skills/seo-unlighthouse目录，不触碰 settings.json。由于 Unlighthouse 全程无密钥，卸载是干净彻底的。

与仓库其他技能的配合

技能文档给出了两条跨技能协作路径，方便在实战中组合使用：

• 需要单 URL 的字段数据（CrUX）：改用seo-google psi/seo-google crux，它们走 Google 官方 API 获取真实用户数据；
• 慢页面 LCP 子部分拆解：使用scripts/lcp_subparts.py工作流（Phase C），对 Unlighthouse 发现的性能瓶颈页面做更细粒度的 LCP 归因分析。

此外，CLAUDE.md 的脚本索引（CLAUDE.md）将该脚本标注为"Unlighthouse CLI wrapper (site-wide Lighthouse)"，并归入技术 SEO 脚本组。整体上，Unlighthouse 扩展在 claude-seo 中扮演"整站性能基线"角色：跑一遍得到全站聚合分数与逐路由明细，再对有问题的页面下钻到 PSI/CrUX 字段数据或 LCP 子部分分析，形成从实验室基线到字段验证的完整 CWV 工作闭环。