seo-images

图片 SEO 审计

对目标上的每个 <img> 和 <picture> 进行聚焦的页面级（或域名抽样）审计。发现替代文本问题、格式缺失（WebP/AVIF 覆盖情况）、响应式图片缺失（srcset / sizes）、LCP 和 CLS 风险，以及缺少 ImageObject 标记的问题。输出按优先级排列的修复清单，以及可直接粘贴的 <picture> 和 JSON-LD 代码片段。

改编自 AgriciDaniel/claude-seo 的 seo-images 技能（MIT）。评估标准、延迟加载器分类和严重程度等级均沿用上游实现；数据源接入了此目录的 SE Ranking / Firecrawl / Google API 技术栈。

先决条件

• 清点所需： mcp__firecrawl-mcp__firecrawl_scrape（原始 HTML 访问权限）。WebFetch 仅返回 Markdown——技能看到内容之前，所有 <img> 属性（srcset、sizes、loading、fetchpriority、width、height、data-src* 延迟加载变体）都会被剥除。没有 Firecrawl 就无法运行审计。通过 bash extensions/firecrawl/install.sh 安装。
• 可选（PSI 字节节省估算）： 已配置 google-api.json（Tier 0——仅需 API 密钥）。配置后会执行步骤 9，并将每张图片实际的 Lighthouse wastedBytes 添加到修复清单中。
• 可选（SE Ranking 审计交叉引用）： 已连接 SE Ranking MCP 服务，且该域名有近期审计。满足条件时，步骤 10 会将图片相关的审计问题提升到同一修复清单中。
• 用户提供：目标 URL（单页审计）或域名（抽样审计）。对于域名，技能会先确认抽样页数，再消耗 Firecrawl 点数。

流程

1. 验证目标并进行预检。 规范化 URL（移除尾部斜杠，解码 IDN）。确定模式：

   • URL 模式（看起来是单个页面的输入默认采用）：目标为一个 URL。费用：1 个 Firecrawl 点数 + 可选 PSI 调用。
   • 域名模式（输入为裸域名，或用户明确要求对整个域名进行审计）：先映射，再抓取样本。
   • 预检（适用时参照 skills/seo-firecrawl/references/preflight.md）：
     • 确认 Firecrawl 已连接。若未连接，则提供安装命令并终止。
     • 如果已接入 Google API（存在 ~/.config/seo-skills/google-api.json），记录检测到的层级；步骤 9 将使用该配置。否则，将步骤 9 标记为已跳过。
     • 如果 SE Ranking MCP 已连接，且该域名存在近期审计，则记录审计 ID；步骤 10 将使用该 ID。否则，将步骤 10 标记为已跳过。

2. 收集图片清单 mcp__firecrawl-mcp__firecrawl_scrape（URL 模式）或 firecrawl_map + firecrawl_scrape（域名模式）

   • **URL 模式：**抓取目标页面，设置 formats: ["html", "markdown"] 和 onlyMainContent: false（导航栏和页脚中的图片也很重要，审核时都要纳入考量，包括主视觉 Logo、页脚信任徽章和装饰图片）。对于 SPA，传入 waitFor: 2000，以便在渲染后的 DOM 中显示延迟注入的图片。解析返回的 html 中每个 <img> 和 <picture>。为每张图片记录：
     • src、srcset、sizes、alt、loading、fetchpriority、decoding、width、height、role、aria-hidden
     • 延迟加载器属性：data-src、data-srcset、data-lazy-src、data-original、data-perfmatters-src、data-perfmatters-srcset、data-ewww-src、data-eio
     • 类名信号：lazyload、lazyloaded、lazy、perfmatters-lazy、lazyload-eio
     • 父级 <picture> 中 <source> 条目的：type、srcset、media
     • 解析后的绝对 URL（用于检测跨域 / CDN）
   • **域名模式：**运行 firecrawl_map（默认 limit: 500，硬性上限；费用：每个发现的 URL 约 0.5 个额度——运行前说明预估费用）。从 URL 列表中选取最多 10 个页面作为样本：主页，以及流量最高的着陆页（如果已连接 SE Ranking，则根据 DATA_getDomainKeywords 的页面汇总选择；否则选择网站地图中嵌套层级最深的 URL——通常是内容页，而非分类索引页）。抓取前确认样本列表和额度费用。然后抓取每个页面（每页 1 个额度）。清单包含所有样本页面上图片的并集。
   • **CSS 背景图片：**标记为已知盲区。我们不会审核样式表中的 background-image: url(...)——Google 不会将其作为内容图片进行抓取，也不会让它们出现在图片搜索中。在综合结果中说明“检测到 {n} 个可能的背景图片（来自计算样式引用）——不在本次审核范围内；如果主视觉 / 功能图片使用 CSS 实现，请另行检查”。

3. 替代文本审核

   • 加载 references/image-checks.md § 替代文本。针对每张图片：
     • **是否存在：**缺少 alt（不是 alt=""——空字符串形式可用于纯装饰性图片）。严重程度：高。
     • **装饰图片但未标记：**只有在图片确实属于装饰性图片时，alt="" 才合适。如果 alt="" 的图片同时具有非装饰性的 src（例如产品照片路径、主视觉图片路径），则标记为“确认是否确为装饰用途”（中）。
     • 通用文本：alt 值符合通用模式——单独的文件名（image.jpg、IMG_1234.png）、单个通用名词（photo、picture、image、banner）、CTA 文案（click here、read more、learn more）。严重程度：高。
     • 长度：alt 不在 10–125 个字符范围内。少于 10 个字符 → 中（描述性可能不足）。超过 125 个字符 → 低（可能过于冗长；屏幕阅读器通常会在此处截断）。
     • **关键词堆砌：**同一关键词在 alt 中出现 3 次或以上，或关键词占 alt 字符数的 50% 以上。严重程度：中。
     • **页面上多张图片使用相同的 alt：**标记为模板错误（中）——产品详情页（PDP）上的每张产品照片不应共用相同的 alt。

4. 格式覆盖率（WebP / AVIF）

   • 对每张图片，根据 src 扩展名（.webp、.avif、.jpg/.jpeg、.png、.gif、.svg）和 <picture> <source> 的 type 属性（image/avif、image/webp）判断其提供的格式。
   • 计算页面（或域名样本）的三项覆盖率指标：
     • 直接以 WebP 或 AVIF 格式提供的图片占比（通过选中的 <img src> 或选中的 <picture> <source>）。
     • 使用 <picture> 包裹且至少包含一个现代格式 <source> 的图片占比（渐进增强——回退链）。
     • 仅使用旧格式的图片占比（JPEG / PNG / GIF），且没有现代格式替代项。
   • 单张图片标记：
     • 使用旧格式且没有 <picture> 现代格式替代项 → image_legacy_format（中）。
     • 大于 500 KB 的动画 GIF → 建议改用视频（<video autoplay muted loop playsinline>）（中——影响性能和 LCP）。来源：Google PSI efficient-animated-content 审计。
     • 将 SVG 用于照片内容 → image_svg_misuse（低——文件会非常大；SVG 适用于图标和插图）。
   • JPEG XL 说明。 Chromium 于 2025 年 11 月宣布恢复基于 Rust 的 JPEG XL 解码，但该功能尚未在 Chrome 稳定版中推出。作为提示说明：目前无需采取行动，持续关注 2026 年的进展。

5. 响应式覆盖率（srcset / sizes）

   • 对每张非 SVG 位图：
     • 缺少 srcset → image_no_srcset（中）。浏览器无法选择尺寸合适的文件；移动用户会下载桌面尺寸的图片。
     • 存在 srcset，但没有 sizes 且不在 <picture> 中 → image_no_sizes（中）。浏览器会回退到基于视口宽度的假设，可能选错候选图片。
     • 已声明 srcset，但所有候选项的宽度描述符都相同（仅有 1x，或所有 w 值之间相差不超过 100 px）→ image_srcset_useless（低）。

6. 延迟加载和 LCP 信号

   • 对每张图片，按照 references/lazy-loaders.md 中的分类体系判断延迟加载机制：native / perfmatters / ewww / js-generic / none。同时报告 lazy_method 和 loading，这样就不会把由 JS 加载器驱动的页面误判为缺少 loading="lazy"（此类页面会有意省略原生属性，由加载器负责处理）。
   • LCP 候选项启发式规则。 LCP 图片通常是第一张符合以下条件的 <img>：
     • 在典型移动端视口的首屏区域内（未渲染时无法确定精确视口；启发式规则 = 渲染后 DOM 中第一张不在 <header> / <nav> / <aside> 内，且没有带 loading="lazy" 的祖先元素的 <img>），
     • 渲染面积较大（width × height 属性均 ≥ 300，或 <picture> <source> 的 sizes 覆盖整个视口）。
   • 对于 LCP 候选项：
     • 设置了 loading="lazy" → image_lcp_lazy（高）。对 LCP 图片进行延迟加载会直接损害 LCP。
     • 没有 fetchpriority="high" → image_lcp_no_fetchpriority（中）。这是 Lighthouse 的 prioritize-lcp-image 审计；设置 fetchpriority="high" 可将 LCP 图片移到浏览器网络队列的前端。
   • 对于首屏以下的图片（不是 LCP 候选项，且不在首个视口内）：
     • 既没有原生 loading="lazy"，也没有任何 JS 加载器信号 → image_below_fold_eager（中）。首屏以下的图片应延迟加载。
     • 缺少 decoding="async" → image_no_decoding_async（低）。对于非 LCP 图片，异步解码可避免图片解码阻塞主线程。

7. CLS 尺寸

   • 对每张图片：
     • 同时缺少 width 和 height 属性，且没有内联 aspect-ratio 样式 → image_unsized（高）。浏览器无法预留空间；图片加载时会导致内容偏移。对应 Lighthouse 的 unsized-images。
     • 已设置 width 和 height，但其比例与实际显示比例相差超过 5% → image_aspect_mismatch（低）。布局会在加载时发生偏移。
   • 两种问题的修复方法相同：将 width 和 height 属性设为图片的固有尺寸，并由 CSS 处理响应式缩放。

8. 文件名质量

   • 对每个图片解析后的 URL，提取文件名。标记：
     • 相机默认名称（IMG_xxxx、DSC_xxxx、DSCN_xxxx、P_xxxx、Photo_xx）→ image_camera_filename（低）。
     • 随机哈希名称（a3f9b2c.jpg、0e8d1f7.webp——没有可读词语的十六进制／Base64 模式）→ image_hash_filename（低）。图片 CDN 中很常见；请确认是否有利于 SEO 的版本可用。
     • 全大写或全由下划线组成的文件名 → image_filename_style（低）。惯例是使用小写字母和连字符。
   • 不要把所有由 CDN 提供的图片都标记为问题——许多 CMS 会对文件名进行哈希处理以更新缓存，这完全没问题。如果同一图片缺少 alt 或其 alt 内容过于笼统，那么这个信号才有意义（页面完全没有说明图片所描绘内容的信息）。

9. ImageObject JSON-LD：检测、验证、生成

   • **检测：**解析 Firecrawl 返回的每个 <script type="application/ld+json"> 区块。查找现有的 ImageObject 区块——可以是顶层区块（用于图片搜索富媒体搜索结果），也可以嵌套在 Article.image、Product.image、Recipe.image 等字段下。
   • **验证：**根据 Google 图片指南进行检查（字段列表见 references/image-checks.md § ImageObject）。对于顶层 ImageObject：
     • 必需字段：@context、@type: ImageObject、contentUrl（图片 URL）、creator 或 copyrightHolder。
     • 对于可授权图片富媒体搜索结果，建议填写：license（许可条款的 URL）、acquireLicensePage（用户可购买／获取图片许可的 URL）、creditText（应如何注明创作者）。
     • 常见错误：使用 url 而不是 contentUrl；将 author 写成裸字符串，而不是 Person／Organization 对象；将尺寸写成字符串，而不是 Number。
   • **生成：**对于尚无 ImageObject 区块，且符合“值得添加标记”门槛的每张图片（该图片是页面主图／首屏图片，且页面明确标明了创作者／所有者），使用 templates/image-object.json 生成可直接粘贴的区块，并从实时 HTML 中填入字段。将无法确定的字段标记为 {REPLACE: ...}。生成的文件输出为 02-remediation/image-object.jsonld（.jsonld 扩展名表明这是供 <script type="application/ld+json"> 使用的交付文件）。
   • **不要为每个 <img> 都生成 ImageObject。**这会造成噪声。仅限主图以及应符合可授权图片富媒体搜索结果资格的图片。

10. 可选：PageSpeed Insights 字节节省量 （仅当存在 ~/.config/seo-skills/google-api.json 且 Tier ≥ 0 时）

    • 运行 python3 scripts/pagespeed_check.py "{url}" --strategy=mobile --json 和 --strategy=desktop --json（每个目标 URL 调用 API 2 次，符合 PSI 每日 25k 次的免费额度）。
    • 从 JSON 响应中提取以下审计项，并将每张图片的 wastedBytes 合并到修复列表中：
      • modern-image-formats — 使用 WebP/AVIF 可节省的字节数（与步骤 4 重叠；以 PSI 数值为准）。
      • uses-optimized-images — 重新压缩可节省的字节数。
      • uses-responsive-images — 提供尺寸合适的文件可节省的字节数（与步骤 5 重叠）。
      • offscreen-images — 对首屏以下的图片进行延迟加载可延后加载的字节数（与步骤 6 重叠）。
      • unsized-images — 缺少尺寸的页面元素（用于交叉核对步骤 7）。
      • prioritize-lcp-image — 确认或反驳步骤 6 中的 LCP 候选项启发式判断，并提供 PSI 认定的权威 LCP 元素。
      • efficient-animated-content — 确认步骤 4 中对动画 GIF 的标记。
    • 每项 PSI 审计都会返回包含 url 和 wastedBytes 的 details.items[]。按图片 URL（解析后的绝对 URL）进行关联，并为每一行修复项添加 psi_wasted_bytes 标签，使优先级列表按实际节省量排序，而不只依赖启发式严重程度。
    • 如果已配置 PSI，但没有返回任何审计项（可能是 4xx 错误，通常是 Lighthouse 无法加载的私有/受保护 URL）：注明“PSI：无法分析 {url}（{reason}）”，并继续使用非 PSI 信号。

11. 可选：交叉核对 SE Ranking 审计 （仅当已连接 SE Ranking MCP 且存在近期审计时）

    • DATA_listAudits → 查找该域名最近的审计。如果不存在审计或审计时间超过 30 天，则跳过此步骤（不要从图片技能触发新审计；是否触发由 seo-technical-audit 决定）。
    • 对于每个与图片相关的审计代码，运行 DATA_getAuditPagesByIssue：
      • images_oversized（或 SE Ranking 当前用于表示“未压缩图片”的代码）
      • images_no_alt
      • images_broken（图片 URL 返回 404 / 5xx）
      • images_no_dimensions（CLS）
    • 合并调查结果：对于同时被审计和此技能标记的图片，将严重程度提高一级。对于审计已标记但未包含在 Firecrawl 抽样中的 URL，将其列在“审计标记但未包含在此样本中的页面”下，并建议专门针对这些 URL 重新运行。

12. 综合整理 IMAGES.md。修复表按以下顺序排序：

    1. 严重程度（Critical → High → Medium → Low），
    2. 同一严重程度内：按 PSI wastedBytes 降序排列（运行 PSI 时），否则按受影响图片数量降序排列，
    3. 然后按问题代码的字母顺序排列。

输出格式

创建文件夹 seo-images-{target-slug}-{YYYYMMDD}/，其中包含：

seo-images-{target-slug}-{YYYYMMDD}/
├── IMAGES.md                       (synthesised audit + remediation list — primary deliverable)
├── images.csv                      (every image with all audit columns — engineering pastes into Jira)
├── 01-inventory.md                 (per-page image list with raw attributes)
├── 02-remediation/
│   ├── picture-snippets.md         (paste-ready <picture> blocks for the top N legacy-format images)
│   ├── alt-text-rewrites.md        (suggested alts for missing / generic-text cases)
│   └── image-object.jsonld         (generated ImageObject for the hero image, if applicable)
├── 03-psi-report.md                (PSI image-audit breakdown — only if Google APIs configured)
└── 04-audit-cross-ref.md           (image-related SE Ranking audit issues — only if step 11 ran)

IMAGES.md 遵循以下结构：

# Image SEO Audit: {URL or domain}

> Snapshot dated {YYYY-MM-DD} · Mode: {URL | domain-sample (n pages)} · Images analysed: {n}

## Coverage at a glance

| Metric | Result |
|---|---|
| Total images | {n} |
| Missing alt text | {n} ({pct}%) |
| Generic / templated alt text | {n} ({pct}%) |
| Modern format (WebP/AVIF) coverage | {pct}% direct, {pct}% via `<picture>` fallback |
| `srcset` present (responsive) | {pct}% |
| `loading` strategy detected | native: {pct}% · JS-loader: {pct}% · none: {pct}% |
| LCP image flagged | {yes/no — element + risk} |
| Unsized (CLS risk) | {n} ({pct}%) |
| `ImageObject` JSON-LD | {present / partial / missing} |

## Top 10 remediations (severity × byte savings)

| Rank | Issue code | Severity | Images | PSI wastedBytes | Fix | Effort |
|---|---|---|---|---|---|---|
| 1 | image_lcp_lazy | High | 1 | 480 KB | Remove `loading="lazy"`; add `fetchpriority="high"` | S |
| 2 | image_legacy_format | Medium | 14 | 2.1 MB | Convert to WebP, wrap in `<picture>` with fallback | M |
| ... |

## By category

### Alt text ({n} issues)
- {n} images missing `alt` entirely. See `02-remediation/alt-text-rewrites.md` for suggested rewrites.
- {n} images with generic alt (`image.jpg`, `photo`, "click here").
- {n} images with identical alt across multiple images (templating bug).

### Format coverage ({pct}% modern)
- {n} images stuck on legacy JPEG/PNG. See `02-remediation/picture-snippets.md`.
- {n} animated GIFs >500 KB — recommend video.

### Responsive sizing ({pct}% have `srcset`)
- {n} images without `srcset`.
- {n} images with `srcset` but no `sizes`.

### Lazy loading & LCP
- LCP candidate: `{img src or selector}` — {risk summary}.
- {n} below-fold images loading eagerly.
- {n} images missing `decoding="async"`.

### CLS dimensions ({n} unsized)
- {n} images without `width`/`height` attributes.
- {n} images with aspect-ratio mismatches.

### File names ({n} flagged)
- {n} camera-default names (IMG_xxxx).
- {n} hash-only filenames coupled with a missing/generic alt.

### ImageObject JSON-LD
- Currently present: {none | block-level on hero | partial}.
- Recommended additions: {none | hero-image ImageObject for licensable-images rich result}.

## Paste-ready remediations

See `02-remediation/`:
- `picture-snippets.md` — `<picture>` blocks for the top N legacy-format images.
- `alt-text-rewrites.md` — alt-text rewrites for missing / generic cases.
- `image-object.jsonld` — `ImageObject` block for the hero image.

## Out of scope for this skill

- **File-level optimisation** (running `cwebp` / `exiftool` / ImageMagick / `ffmpeg` against the actual binary). This skill audits markup and references; converting and re-uploading the files is engineering work — see the pipeline note in `references/image-checks.md` § Optimisation pipeline if you want a starting recipe.
- **CSS background-images.** {n} likely background-image references detected via computed style, but not audited. They don't appear in Google Images and aren't subject to the `<img>`-tag rubric.
- **Site-wide audit at >10 pages.** This is a sampled audit. For domain-level "every image on every page", run `seo-technical-audit` first to surface the audit-grade signals, then come back here for sample-level deep audit.

## Recommended next steps

- {`seo-technical-audit` if domain-wide image issues need to be quantified — uncompressed-images counts, etc.}
- {`seo-schema` if `ImageObject` was generated and the page also needs `Article` / `Product` / etc. markup.}
- {`seo-google pagespeed` for the full Lighthouse breakdown (this skill only pulls image-specific audits).}

images.csv 的列：page_url,image_url,alt,alt_length,alt_issue,format,in_picture,modern_source,srcset,sizes,loading,lazy_method,fetchpriority,decoding,width,height,unsized,lcp_candidate,filename_issue,psi_wasted_bytes,severity,fix,effort。

提示

• 默认使用 URL 模式。 单页审查消耗 1 个 Firecrawl 点数，并生成完整的交付内容，适用于最常见的需求（“审查 /this/page 上的图片”）。域名模式适用于“全面了解整个网站”——它能发现单页模式遗漏的问题模式（模板错误、整个 CMS 缺少 alt 文本等）。
• <picture> 才是正确的选择。 推荐现代格式时，始终建议使用 <picture> 元素，搭配 AVIF + WebP <source> 和 JPEG 回退 <img>，而不是直接使用 <img src=".avif">。AVIF 的支持率超过 93%，WebP 超过 97%，但回退格式才能确保标记对较旧的客户端和爬虫安全。
• 不要对 LCP 图片启用延迟加载。 这是现代 CMS 上最常见的图片 SEO 错误。主题会默认在整个网站上启用 loading="lazy"，因此首屏主图也会受到影响。此技能的 LCP 启发式检测会找出最可能的问题；PSI（步骤 10）可进行权威确认。
• 对于纯装饰性图片，空 alt="" 是正确的（例如细线 SVG、纯背景间隔图片）。这会让屏幕阅读器跳过该图片。不要自动标记每个空 alt；只标记那些从文件名和上下文来看可能包含内容的图片。
• 图片较少时，逐项列出清单。 对于图片少于 10 张的页面，请在 IMAGES.md 的“按类别”部分列出每张图片及完整审查行，而不只是汇总数量。对于 100 张以上的图片，汇总输出很有用；少于这个数量时，汇总会掩盖具体细节。
• 免费版 PSI 每天限流 25k 次，但计算的是请求次数，而不是图片数量。默认情况下，每个目标 URL 调用两次 PSI（移动设备 + 桌面设备）；如果你只关心 Google 的移动优先排名信号，可以跳过桌面设备。
• CSS 背景图片确实是一个盲点——标记其数量，但不要审查它们。Google 不会将它们作为内容图片抓取。
• JPEG XL 目前还不能用于生产环境（Chromium 于 2025 年 11 月宣布恢复解码器支持，但尚未进入稳定版 Chrome）。在其进入稳定版之前，不要推荐 JPEG XL。WebP 和 AVIF 是当前安全可用的现代格式。
• 不要自动应用修复。 此技能负责诊断并生成可直接粘贴的代码片段；由人工决定采用哪些修复以及采用顺序。
• 部署后进行验证。 修复部署后，在同一 URL 上重新运行此技能——新一轮结果中的“覆盖情况一览”会反映线上状态，并确认标记确实已更改（而不是仍停留在 CMS 中、尚未推送）。

配合使用效果良好

• 前置技能：
  • seo-firecrawl — 用户已经抓取了页面，现在需要针对图片进行专项审查时使用。
  • seo-technical-audit — 全站审查发现了图片问题，用户希望按照深入的逐图评估标准进行审查时使用。
  • seo-page — URL 级别的关键词 / 流量评估结果为“更新”，且图片属于更新内容时使用。
• 后续技能：
  • seo-schema — 除 ImageObject 外，页面还需要 Article / Product / LocalBusiness schema 时使用。
  • seo-google pagespeed — 用于获取完整的 Lighthouse 报告（此技能仅挑选其中的图片审查内容；PSI 还有 100 多项其他内容）。
  • seo-drift — 用于建立图片标记基线，并在 CMS 或主题升级后检测回归。