seo-review

SEO 审查

评估应用的搜索引擎优化和可发现性。此审查可发现常规开发中不易察觉的 SEO 问题——缺少元标签、结构化数据损坏、抓取能力差、缺少站点地图，以及社交分享问题。许多单页应用（SPA）在发布时完全没有考虑 SEO。

适用场景

在以下情况下使用 /seo-review：

• 发布面向公众的网站或应用前
• 重新设计或迁移网站后
• 自然流量是增长渠道时
• 切换到 SPA 框架（React、Vue、Angular）后
• 社交分享（Open Graph）很重要时
• 设置内容营销页面时

参考标准

• Google Search Central — SEO 最佳实践和指南
• Schema.org — 结构化数据词汇表
• Open Graph Protocol — 社交分享元标签
• Twitter Card — Twitter 分享标记
• W3C Semantic HTML — 无障碍访问和 SEO 语义
• Web.dev SEO Guidelines — Google 的 SEO 建议

阶段概览

Phase 1: EDUCATE   → Why SEO matters and what we check
Phase 2: SCOPE     → Identify key pages, content types, SEO goals
Phase 3: ANALYZE   → Browser-based SEO validation
Phase 4: REPORT    → Findings with impact assessment and priority
Phase 5: REMEDIATE → Fix guidance + YAML regression tests

---

阶段 1：说明

重要性： 所有网站流量中有 53% 来自自然搜索（BrightEdge）。Google 搜索结果的第一位获得 27.6% 的点击量；第 10 位则获得 2.4%（Backlinko）。SPA 通常会向爬虫呈现空白 HTML，导致数百万个页面无法被搜索到。做好 SEO 不需要耍花招——只需让搜索引擎能够发现并理解你的内容。

此审查会检查技术 SEO 基础——这些事项必须先做好，内容策略才有意义。

---

阶段 2：确定范围

收集背景信息

1. 从代码库自动检测：

   • 框架和渲染策略（SSR、SSG、CSR、ISR）
   • 元标签管理（react-helmet、next/head、vue-meta 等）
   • 站点地图生成
   • robots.txt 配置
   • 结构化数据（JSON-LD、microdata）
   • i18n/hreflang 设置
   • 规范 URL 处理
   • 路由结构和页面类型

2. 向用户询问（每次一项）：

   • 目标 URL：应用运行在哪个地址？（建议使用生产环境，以便进行真实抓取）
   • 重要页面：哪些页面对搜索最重要？（主页、产品页面、博客文章、落地页）
   • 目标关键词：是否有希望获得排名的主要关键词？（可选，用于内容评估）
   • 社交分享是否重要？：是否需要 Open Graph / Twitter Cards？（公开网站默认需要）
   • 多语言？：网站是否提供多种语言？（自动检测）

3. 识别页面类型：

   • 主页
   • 内容页面（博客、文档、关于）
   • 产品／列表页面
   • 动态页面（搜索结果、用户个人资料）
   • 实用页面（登录、404、条款）

---

阶段 3：分析

使用 record_evidence: true 打开一个浏览器会话，并调用 new_session。针对每个重要页面，运行所有检查类别。

类别 A：Meta 标签与 Head 元素（META）

检查 ID	检查项	标准	方法
META-01	唯一且描述准确的 <title>（50-60 个字符）	Google 指南	提取 <title>，检查长度和唯一性
META-02	存在 Meta 描述（120-160 个字符）	Google 指南	检查 <meta name="description">
META-03	正确设置规范 URL	Google 指南	检查 <link rel="canonical">
META-04	存在 viewport Meta 标签	移动端 SEO	检查 <meta name="viewport">
META-05	已声明字符集	HTML 标准	检查 <meta charset>
META-06	没有重复的 Meta 标签	SEO 最佳实践	检查是否存在重复的标题和描述
META-07	存在网站图标	品牌建设/SEO	检查 <link rel="icon">
META-08	已声明语言	SEO/无障碍	检查 <html lang="">
META-09	重要页面没有设置 Meta robots noindex	索引	检查 <meta name="robots">
META-10	多语言页面包含 Hreflang 标签（如适用）	国际 SEO	检查 <link rel="alternate" hreflang="">

浏览器验证： 使用 inspect_page 读取 DOM。通过 JavaScript 提取所有 <head> 元素。

类别 B：结构化数据（SCHEMA）

检查 ID	检查项	标准	方法
SCHEMA-01	存在 JSON-LD 结构化数据	Schema.org	检查是否存在 <script type="application/ld+json">
SCHEMA-02	Schema 类型与页面内容匹配	Schema.org	验证类型（Organization、Product、Article 等）
SCHEMA-03	包含必需属性	Schema.org	根据类型要求进行验证
SCHEMA-04	JSON-LD 是有效的 JSON	Schema.org	解析并验证 JSON
SCHEMA-05	没有已弃用的 Schema 属性	Schema.org	检查是否存在已弃用字段
SCHEMA-06	包含面包屑结构化数据	Schema.org	检查内页是否包含 BreadcrumbList
SCHEMA-07	包含 FAQ 结构化数据（如适用）	Schema.org	检查 FAQ 部分是否包含 FAQPage
SCHEMA-08	包含评论/评分结构化数据（如适用）	Schema.org	检查是否包含 AggregateRating

浏览器验证： 通过 JavaScript 提取 JSON-LD 脚本。解析并验证结构。将页面内容与 Schema 声明进行对比。

类别 C：Open Graph 与社交分享（OG）

检查 ID	检查项	标准	方法
OG-01	存在有意义的 og:title	Open Graph	检查 <meta property="og:title">
OG-02	存在 og:description	Open Graph	检查 <meta property="og:description">
OG-03	存在且可访问 og:image	Open Graph	检查 <meta property="og:image">，验证 URL 可加载
OG-04	og:image 尺寸合适（建议为 1200x630）	Open Graph	检查图片尺寸
OG-05	og:url 与规范 URL 一致	Open Graph	比较 og:url 与规范 URL
OG-06	正确设置 og:type	Open Graph	检查 og:type 值
OG-07	存在 Twitter 卡片 Meta 标签	Twitter Cards	检查 twitter:card、twitter:title 等
OG-08	社交分享预览显示正确	用户体验	根据 OG 标签生成预览

浏览器验证： 提取所有 OG 和 Twitter Meta 标签。验证 og:image URL 是否可访问。生成预览效果。

类别 D：可抓取性与索引（CRAWL）

检查 ID	检查项	标准	方法
CRAWL-01	robots.txt 存在且有效	Google 指南	获取 /robots.txt
CRAWL-02	Sitemap.xml 存在且有效	Google 指南	获取 /sitemap.xml，验证格式
CRAWL-03	robots.txt 中引用了 Sitemap	最佳实践	检查 robots.txt 中是否有 Sitemap 指令
CRAWL-04	重要页面包含在 sitemap 中	SEO	将关键页面与 sitemap URL 交叉核对
CRAWL-05	没有失效的内部链接	可抓取性	检查关键页面上的所有内部链接
CRAWL-06	没有重定向链（>2 次跳转）	抓取效率	跟踪重定向并统计跳转次数
CRAWL-07	URL 结构简洁（没有过多参数）	SEO	检查 URL 模式是否简洁
CRAWL-08	404 页面返回正确的 HTTP 状态码	SEO	访问不存在的 URL 并检查状态码
CRAWL-09	没有孤立页面（可通过导航访问）	可抓取性	确认首页/导航中链接到关键页面
CRAWL-10	无需 JavaScript 即可看到 SSR/SSG 内容	SPA SEO	禁用 JS，检查内容是否渲染
CRAWL-11	爬虫的页面加载时间	抓取预算	测量服务器响应时间

浏览器验证： 访问 robots.txt 和 sitemap.xml。跟踪内部链接。禁用 JavaScript，以测试服务器渲染的内容。检查 HTTP 状态码。

类别 E：语义化 HTML 与内容（SEM）

检查 ID	检查项	标准	方法
SEM-01	每个页面只有一个 <h1>	SEO 最佳实践	统计 h1 元素
SEM-02	标题层级合乎逻辑（h1→h2→h3）	SEO/a11y	检查标题顺序
SEM-03	图片具有描述性 alt 文本	SEO/a11y	检查 alt 属性是否具有描述性
SEM-04	内部链接使用描述性锚文本	SEO	检查是否将「点击此处」或纯 URL 用作链接
SEM-05	使用语义化 HTML 元素（nav、main、article、section）	SEO	检查语义地标
SEM-06	内容与 HTML 的比例合理	SEO	计算文本内容与 HTML 标记的比例
SEM-07	页面之间没有重复内容	SEO	比较各页面的关键内容部分
SEM-08	URL 易于阅读	SEO	检查 slug 是否具有描述性，而非 ID/哈希值

浏览器验证： 通过 JavaScript 提取标题、链接、图片和语义化元素。分析内容结构。

类别 F：技术 SEO（TECH）

检查 ID	检查项	标准	方法
TECH-01	全站使用 HTTPS	Google 排名信号	检查协议
TECH-02	HTTP → HTTPS 重定向正常	SEO	测试 HTTP URL 重定向
TECH-03	www → 非 www（或反之）的重定向保持一致	SEO	测试两种形式
TECH-04	适配移动设备（响应式）	Google 移动优先	检查 viewport 和响应式行为
TECH-05	Core Web Vitals 达到「良好」阈值	Google 排名信号	测量 LCP、INP、CLS
TECH-06	没有阻塞渲染的资源	页面速度	检查脚本/样式的加载情况
TECH-07	内容迁移时正确设置 301 重定向	SEO	如适用，检查已知的旧 URL
TECH-08	国际定位正确（如面向多个地区）	国际 SEO	检查 hreflang 和地理定位

浏览器验证： 测试重定向、测量性能指标并检查移动端渲染。

---

第 4 阶段：报告

生成结构化报告并保存到 shiplight/reports/seo-review-{date}.md：

# SEO Review Report
**Date:** {date}
**URL:** {url}
**Pages reviewed:** {list}
**Rendering:** {SSR/SSG/CSR/ISR}

## Overall Score: {X}/10 | Confidence: {X}%

## Score Breakdown
| Category | Score | Findings |
|----------|-------|----------|
| Meta Tags (META) | 7/10 | 1 high, 2 medium |
| Structured Data (SCHEMA) | 4/10 | 1 critical, 1 high |
| Social Sharing (OG) | 6/10 | 2 high |
| Crawlability (CRAWL) | 5/10 | 1 critical, 1 high |
| Semantic HTML (SEM) | 8/10 | 1 medium |
| Technical SEO (TECH) | 7/10 | 1 high |

## Page-by-Page Summary
| Page | Title | Description | OG Image | Schema | H1 | Score |
|------|-------|-------------|----------|--------|----|-------|
| / | ✅ | ✅ | ❌ missing | ❌ none | ✅ | 6/10 |
| /blog | ✅ | ⚠️ too short | ✅ | ✅ Article | ✅ | 8/10 |

## Findings
(structured findings with evidence and impact)

置信度评分

• 90-100%：已在浏览器中验证——标签存在/缺失，URL 可访问/失效
• 70-89%：内容分析表明存在问题（例如，内容单薄、alt 文本笼统）
• 50-69%：最佳实践建议，但没有明确违规
• 低于 50%：不要报告

---

第 5 阶段：修复

1. 修复指南（示例）

#### CRAWL-10: Content not visible without JavaScript
**Impact:** Search engines may not index your content (especially Google Discover, Bing, social crawlers)
**Current:** Client-side rendered React app, empty HTML shell
**Fix:** Implement SSR or SSG:
- Next.js: Use `getServerSideProps` or `getStaticProps`
- Nuxt: Default SSR mode
- Gatsby: Static generation
- Or: Add prerendering service (prerender.io, rendertron)
**Quick win:** Ensure critical content is in initial HTML response

2. YAML 回归测试

- name: meta-01-title-present
  description: Verify each key page has a unique, properly-sized title tag
  severity: high
  standard: Google-SEO-Guidelines
  steps:
    - URL: /
    - description: Assert the page title is present and 20-60 characters
      js: |
        const title = await page.title();
        if (!title || title.trim() === '') {
          throw new Error('Page has no title');
        }
        if (title.length < 20) {
          throw new Error(`Title too short (${title.length} chars): "${title}"`);
        }
        if (title.length > 60) {
          throw new Error(`Title too long (${title.length} chars): "${title}"`);
        }
        console.log(`Title OK (${title.length} chars): "${title}"`);
    - VERIFY: Page has a descriptive title between 20 and 60 characters

将所有 YAML 测试保存到 shiplight/tests/seo-review.test.yaml。

---

深度级别

• --quick：仅检查首页的 Meta 标签、canonical 和 robots.txt。约 2 分钟。
• 默认：检查关键页面上的所有类别。约 8-12 分钟。
• --thorough：检查所有类别、爬取整个网站、覆盖所有页面类型并分析内容。约 20-30 分钟。

提示

• 禁用 JavaScript 后进行测试，查看搜索引擎能看到什么（尤其是 SPA）
• 使用 inspect_page 的 DOM 输出，高效提取 <head> 内容
• 手动检查 sitemap.xml——自动生成的网站地图通常包含不应被索引的页面
• OG 图片必须使用绝对 URL——相对 URL 无法用于社交分享
• 对于 SPA SEO，关键问题是：“初始 HTML 是否包含内容？”
• 使用 close_session 关闭会话，并使用 generate_html_report 生成证据