seo-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SEO Optimizer

SEO优化指南

Transform your web application from invisible to discoverable. This skill analyzes your codebase and implements comprehensive SEO optimizations that help search engines and social platforms understand, index, and surface your content.

将你的Web应用从无人问津变为易于被发现。本指南会分析你的代码库，并实施全面的SEO优化，帮助搜索引擎和社交平台理解、索引并展示你的内容。

Philosophy: SEO as Semantic Communication

理念：SEO是语义沟通

SEO is not about gaming algorithms—it's about clearly communicating what your content IS to machines (search engines, social platforms, AI crawlers) so they can properly understand and surface it.

Before optimizing, ask:

What is this page actually about? (not what keywords we want to rank for)
Who is the intended audience and what are they searching for?
What unique value does this content provide?
How should machines categorize and understand this content?

Core Principles:

Accuracy Over Optimization: Describe what IS, not what you wish would rank
User Intent First: Match content to what searchers actually want
Semantic Clarity: Use structured data to make meaning machine-readable
Progressive Enhancement: Basic SEO for all pages, rich optimization for key pages
Framework-Native: Use each framework's idioms, not generic hacks

The SEO Hierarchy (prioritize in order):

1. Content Quality      ← Foundation: Valuable, accurate, unique content
2. Technical Access     ← Can crawlers find and index your pages?
3. Semantic Structure   ← Do machines understand your content's meaning?
4. Meta Optimization    ← Are your titles/descriptions compelling?
5. Structured Data      ← JSON-LD for rich search results
6. Performance          ← Core Web Vitals affect rankings

SEO并非操纵算法，而是清晰地向机器（搜索引擎、社交平台、AI爬虫）传达你的内容本质，让它们能够正确理解并展示你的内容。

优化前，请思考：

这个页面的核心内容是什么？（而非我们想排名的关键词）
目标受众是谁？他们在搜索什么？
该内容能提供哪些独特价值？
机器应该如何分类和理解该内容？

核心原则：

准确性优先于优化：描述内容本身，而非你希望排名的关键词
用户意图至上：内容匹配搜索者的真实需求
语义清晰：通过结构化数据让内容含义可被机器读取
渐进式增强：所有页面基础SEO优化，核心页面深度优化
框架原生实现：使用各框架的原生方式，而非通用hack方案

SEO优先级层级（按顺序优先处理）：

1. 内容质量      ← 基础：有价值、准确、独特的内容
2. 技术可访问性     ← 爬虫能否找到并索引你的页面？
3. 语义结构   ← 机器能否理解内容的含义？
4. 元标签优化    ← 标题/描述是否具有吸引力？
5. 结构化数据      ← 用于富搜索结果的JSON-LD
6. 性能优化          ← Core Web Vitals影响排名

Codebase Analysis Workflow

代码库分析流程

ALWAYS analyze before implementing. Different codebases need different approaches.

实施前务必先进行分析。不同的代码库需要不同的优化方案。

Step 1: Discover Framework and Structure

步骤1：识别框架与结构

Identify the framework and routing pattern:

Next.js: Look for
```
next.config.js
```
,
```
app/
```
or
```
pages/
```
directory
Astro: Look for
```
astro.config.mjs
```
,
```
src/pages/
```
React Router: Look for route configuration,
```
react-router-dom
```
Gatsby: Look for
```
gatsby-config.js
```
,
```
gatsby-node.js
```
Static HTML: Look for
```
.html
```
files in root or
```
public/
```

确定使用的框架和路由模式：

Next.js：查找
```
next.config.js
```
、
```
app/
```
或
```
pages/
```
目录
Astro：查找
```
astro.config.mjs
```
、
```
src/pages/
```
目录
React Router：查找路由配置、
```
react-router-dom
```
依赖
Gatsby：查找
```
gatsby-config.js
```
、
```
gatsby-node.js
```
静态HTML：查找根目录或
```
public/
```
下的
```
.html
```
文件

Step 2: Audit Current SEO State

步骤2：审计当前SEO状态

Check for existing implementations:

Meta tags in
```
<head>
```
(title, description, viewport)
Open Graph tags (
```
og:title
```
,
```
og:image
```
, etc.)
Twitter Card tags (
```
twitter:card
```
,
```
twitter:image
```
)
Structured data (
```
<script type="application/ld+json">
```
)
Sitemap (
```
sitemap.xml
```
or generation config)
Robots.txt file
Canonical URLs
Alt text on images

检查已有的SEO实现：

```
<head>
```
中的元标签（title、description、viewport）
Open Graph标签（
```
og:title
```
、
```
og:image
```
等）
Twitter Card标签（
```
twitter:card
```
、
```
twitter:image
```
等）
结构化数据（
```
<script type="application/ld+json">
```
）
站点地图（
```
sitemap.xml
```
或生成配置）
Robots.txt文件
规范URL
图片的alt文本

Step 3: Identify Page Types

步骤3：识别页面类型

Different pages need different SEO approaches:

Page Type	Priority	Key Optimizations
Landing/Home	Critical	Brand keywords, comprehensive structured data
Product/Service	High	Product schema, reviews, pricing
Blog/Article	High	Article schema, author, publish date
Documentation	Medium	HowTo/FAQ schema, breadcrumbs
About/Contact	Medium	Organization schema, local business
Legal/Privacy	Low	Basic meta only, often noindex

不同页面需要不同的SEO优化方案：

页面类型	优先级	核心优化点
首页/落地页	最高优先级	品牌关键词，全面的结构化数据
产品/服务页	高优先级	产品Schema，评论，定价信息
博客/文章页	高优先级	文章Schema，作者信息，发布日期
文档页	中优先级	HowTo/FAQ Schema，面包屑导航
关于/联系页	中优先级	组织Schema，本地商家信息
法律/隐私页	低优先级	仅基础元标签，通常设置noindex

Step 4: Generate Implementation Plan

步骤4：生成实现计划

Based on analysis, prioritize:

Quick wins: Missing meta tags, viewport, basic structure
High impact: Structured data for key pages, sitemap
Refinement: Performance, advanced schema, social optimization

See

references/analysis-checklist.md

for detailed audit procedures.

基于分析结果，按优先级处理：

快速优化项：缺失的元标签、viewport、基础结构
高影响项：核心页面的结构化数据、站点地图
精细化优化：性能优化、高级Schema、社交分享优化

详细审计流程见

references/analysis-checklist.md

。

Meta Tags Implementation

元标签实现

Essential Meta Tags (Every Page)

必备元标签（所有页面）

html

<!-- Required -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{Page Title} | {Site Name}</title>
<meta name="description" content="{150-160 char description}">

<!-- Recommended -->
<link rel="canonical" href="{full canonical URL}">
<meta name="robots" content="index, follow">

html

<!-- Required -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{Page Title} | {Site Name}</title>
<meta name="description" content="{150-160 char description}">

<!-- Recommended -->
<link rel="canonical" href="{full canonical URL}">
<meta name="robots" content="index, follow">

Title Tag Best Practices

标题标签最佳实践

Format:

{Primary Content} | {Brand}

{Primary Content} - {Brand}

Guidelines:

50-60 characters (Google truncates at ~60)
Front-load important keywords
Unique for every page
Accurately describe page content
Include brand for recognition (usually at end)

Title Patterns by Page Type:

Homepage:     {Brand} - {Value Proposition}
Product:      {Product Name} - {Key Benefit} | {Brand}
Article:      {Article Title} | {Brand}
Category:     {Category} Products | {Brand}
Search:       Search Results for "{Query}" | {Brand}

格式：

{核心内容} | {品牌名}

或

{核心内容} - {品牌名}

指南：

长度控制在50-60字符（Google约在60字符处截断）
重要关键词前置
每个页面标题唯一
准确描述页面内容
末尾加入品牌名以提升辨识度

不同页面类型的标题格式：

首页:     {品牌名} - {价值主张}
产品页:      {产品名} - {核心优势} | {品牌名}
文章页:      {文章标题} | {品牌名}
分类页:     {分类名} 产品 | {品牌名}
搜索结果页:       "{搜索关键词}" 搜索结果 | {品牌名}

Meta Description Best Practices

元描述最佳实践

Guidelines:

150-160 characters (Google may truncate at ~155)
Include a call to action when appropriate
Accurately summarize page content
Unique for every page
Include primary keyword naturally

DO NOT:

Stuff keywords unnaturally
Use the same description across pages
Write descriptions that don't match content
Start with "Welcome to..." or similar filler

指南：

长度控制在150-160字符（Google可能在约155字符处截断）
适当加入行动号召
准确概括页面内容
每个页面描述唯一
自然融入核心关键词

请勿：

刻意堆砌关键词
多个页面使用相同描述
描述与实际内容不符
以“欢迎来到...”等无意义内容开头

Open Graph Tags (Social Sharing)

Open Graph标签（社交分享）

html

<meta property="og:type" content="website">
<meta property="og:url" content="{canonical URL}">
<meta property="og:title" content="{title}">
<meta property="og:description" content="{description}">
<meta property="og:image" content="{1200x630 image URL}">
<meta property="og:site_name" content="{Site Name}">

html

<meta property="og:type" content="website">
<meta property="og:url" content="{canonical URL}">
<meta property="og:title" content="{title}">
<meta property="og:description" content="{description}">
<meta property="og:image" content="{1200x630 image URL}">
<meta property="og:site_name" content="{Site Name}">

Twitter Card Tags

Twitter卡片标签

html

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@{handle}">
<meta name="twitter:title" content="{title}">
<meta name="twitter:description" content="{description}">
<meta name="twitter:image" content="{image URL}">

See

references/meta-tags-complete.md

for comprehensive tag reference.

html

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@{handle}">
<meta name="twitter:title" content="{title}">
<meta name="twitter:description" content="{description}">
<meta name="twitter:image" content="{image URL}">

完整元标签参考见

references/meta-tags-complete.md

。

Structured Data (JSON-LD)

结构化数据（JSON-LD）

Structured data enables rich search results (star ratings, prices, FAQs, etc.).

结构化数据可实现富搜索结果（如星级评分、价格、FAQ等）。

When to Use Which Schema

不同内容类型对应的Schema选择

Content Type	Schema	Rich Result
Organization info	Organization	Knowledge panel
Products	Product	Price, availability, reviews
Articles/Blog	Article	Headline, image, date
How-to guides	HowTo	Step-by-step in search
FAQs	FAQPage	Expandable Q&A
Events	Event	Date, location, tickets
Recipes	Recipe	Image, time, ratings
Local business	LocalBusiness	Maps, hours, contact
Breadcrumbs	BreadcrumbList	Navigation path

内容类型	Schema	富搜索结果
组织信息	Organization	知识面板
产品	Product	价格、库存、评论
文章/博客	Article	标题、图片、日期
教程指南	HowTo	搜索结果中的分步展示
常见问题	FAQPage	可展开的问答
活动	Event	日期、地点、票务
菜谱	Recipe	图片、时长、评分
本地商家	LocalBusiness	地图、营业时间、联系方式
面包屑导航	BreadcrumbList	导航路径

Implementation Pattern

实现模式

html

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Company Name",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://twitter.com/company",
    "https://linkedin.com/company/company"
  ]
}
</script>

html

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Company Name",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://twitter.com/company",
    "https://linkedin.com/company/company"
  ]
}
</script>

Multiple Schemas Per Page

单页多Schema实现

Use

@graph

to combine schemas:

json

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", ... },
    { "@type": "WebSite", ... },
    { "@type": "BreadcrumbList", ... }
  ]
}

See

references/structured-data-schemas.md

for complete schema examples.

使用

@graph

组合多个Schema：

json

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", ... },
    { "@type": "WebSite", ... },
    { "@type": "BreadcrumbList", ... }
  ]
}

完整Schema示例见

references/structured-data-schemas.md

。

Technical SEO

技术SEO

Sitemap Generation

站点地图生成

XML Sitemap Requirements:

Include all indexable pages
Exclude noindex pages, redirects, error pages
Update
```
<lastmod>
```
when content changes
Submit to Google Search Console

Framework implementations: See

references/framework-implementations.md

XML站点地图要求：

包含所有可索引页面
排除noindex页面、重定向页面、错误页面
内容更新时更新
```
<lastmod>
```
字段
提交至Google Search Console

框架实现方案：详见

references/framework-implementations.md

Robots.txt

Standard Template:

txt

User-agent: *
Allow: /

标准模板：

txt

User-agent: *
Allow: /

Block admin/private areas

拦截后台/私有区域

Disallow: /admin/ Disallow: /api/ Disallow: /private/

Point to sitemap

指定站点地图位置

Sitemap: https://yourdomain.com/sitemap.xml

undefined

Sitemap: https://yourdomain.com/sitemap.xml

undefined

Canonical URLs

规范URL

Always set canonical URLs to:

Prevent duplicate content issues
Consolidate link equity
Specify preferred URL version

Handle:

www vs non-www
http vs https
Trailing slashes
Query parameters

务必设置规范URL以：

避免重复内容问题
整合链接权重
指定首选URL版本

需处理的场景：

www与非www域名
http与https协议
末尾斜杠
查询参数

Performance (Core Web Vitals)

性能优化（Core Web Vitals）

Core Web Vitals affect rankings. Monitor:

Metric	Target	What It Measures
LCP	< 2.5s	Largest Contentful Paint (loading)
INP	< 200ms	Interaction to Next Paint (interactivity)
CLS	< 0.1	Cumulative Layout Shift (visual stability)

Quick wins:

Optimize images (WebP, lazy loading, proper sizing)
Minimize JavaScript bundles
Use efficient fonts (display: swap)
Implement proper caching

Core Web Vitals会影响排名，需监控以下指标：

指标	目标值	衡量内容
LCP	< 2.5s	最大内容绘制（加载性能）
INP	< 200ms	交互到下一次绘制（交互性）
CLS	< 0.1	累积布局偏移（视觉稳定性）

快速优化方案：

优化图片（WebP格式、懒加载、合适尺寸）
最小化JavaScript包体积
使用高效字体（设置display: swap）
实施合理的缓存策略

Anti-Patterns to Avoid

需避免的反模式

❌ Keyword Stuffing

html

<!-- BAD -->
<title>Best Shoes | Buy Shoes | Cheap Shoes | Shoes Online | Shoe Store</title>

<!-- GOOD -->
<title>Running Shoes for Marathon Training | SportShop</title>

Why bad: Search engines penalize unnatural keyword repetition. Users don't click spammy titles.

❌ Duplicate Descriptions Using the same meta description across multiple pages. Why bad: Misses opportunity for page-specific relevance. Google may ignore and auto-generate.

❌ Description/Content Mismatch Writing descriptions for keywords rather than actual content. Why bad: High bounce rates signal low quality. Users feel deceived.

❌ Missing Alt Text

html

<!-- BAD -->
<img src="product.jpg">

<!-- GOOD -->
<img src="product.jpg" alt="Blue Nike Air Max running shoe, side view">

Why bad: Accessibility violation. Missed image search opportunity.

❌ Blocking Crawlers Unintentionally

txt

undefined

❌ 关键词堆砌

html

<!-- 错误示例 -->
<title>Best Shoes | Buy Shoes | Cheap Shoes | Shoes Online | Shoe Store</title>

<!-- 正确示例 -->
<title>马拉松训练跑鞋 | SportShop</title>

为何错误：搜索引擎会惩罚不自然的关键词重复，用户也不会点击此类垃圾标题。

❌ 重复描述 多个页面使用相同的元描述。为何错误：错失页面相关性优化机会，Google可能会忽略并自动生成描述。

❌ 描述与内容不符 为了关键词而撰写与实际内容不符的描述。为何错误：高跳出率会向搜索引擎传递低质量信号，用户会有被欺骗的感觉。

❌ 缺失图片Alt文本

html

<!-- 错误示例 -->
<img src="product.jpg">

<!-- 正确示例 -->
<img src="product.jpg" alt="蓝色Nike Air Max马拉松跑鞋，侧面视图">

为何错误：违反无障碍要求，错失图片搜索的曝光机会。

❌ 意外拦截爬虫

txt

undefined

Accidentally blocking everything

意外拦截所有爬虫

User-agent: * Disallow: /

Why bad: Complete deindexing. Check robots.txt carefully.

❌ **Ignoring Mobile**
Not having responsive design or mobile-specific considerations.
Why bad: Google uses mobile-first indexing. Most traffic is mobile.

❌ **Over-Optimization**
Adding structured data for content that doesn't exist.
Why bad: Schema violations can result in penalties. Trust erosion.

❌ **Generic Auto-Generated Content**
```html
<!-- BAD: Template without customization -->
<meta name="description" content="Welcome to our website. We offer great products and services.">

Why bad: Provides no value. Won't rank. Won't get clicks.

User-agent: * Disallow: /

为何错误：会导致网站被完全移除索引，需仔细检查robots.txt。

❌ **忽略移动端优化**
未做响应式设计或移动端专属优化。
为何错误：Google采用移动端优先索引，大部分流量来自移动端。

❌ **过度优化**
为不存在的内容添加结构化数据。
为何错误：Schema违规会导致惩罚，损害用户信任。

❌ **通用自动生成内容**
```html
<!-- 错误示例：无定制化的模板内容 -->
<meta name="description" content="欢迎来到我们的网站，我们提供优质的产品和服务。">

为何错误：无实际价值，无法获得排名，也无法吸引用户点击。

Variation Guidance

差异化优化指南

IMPORTANT: SEO implementation should vary based on context.

Vary based on:

Industry: E-commerce needs Product schema; SaaS needs Software schema
Content type: Blog posts vs landing pages vs documentation
Audience: B2B vs B2C affects tone and keywords
Competition: Highly competitive niches need more sophisticated optimization
Framework: Use native patterns (Next.js metadata API vs manual tags)

Avoid converging on:

Same title format for all page types
Generic descriptions that could apply to any site
Identical structured data without page-specific content
One-size-fits-all sitemap configuration

重要提示：SEO实现需根据场景调整。

需根据以下因素调整：

行业：电商需Product Schema；SaaS需Software Schema
内容类型：博客文章、落地页、文档页的优化方式不同
受众：B2B与B2C的语气和关键词选择不同
竞争程度：竞争激烈的领域需要更精细化的优化
框架：使用原生方案（如Next.js metadata API而非手动标签）

需避免的同质化：

所有页面使用相同的标题格式
使用适用于任何网站的通用描述
未根据页面内容定制结构化数据
一刀切的站点地图配置

Framework Quick Reference

框架快速参考

Next.js (App Router)

Next.js（App Router）

typescript

// app/page.tsx
import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Page Title | Brand',
  description: 'Page description',
  openGraph: {
    title: 'Page Title',
    description: 'Page description',
    images: ['/og-image.png'],
  },
}

typescript

// app/page.tsx
import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Page Title | Brand',
  description: 'Page description',
  openGraph: {
    title: 'Page Title',
    description: 'Page description',
    images: ['/og-image.png'],
  },
}

Next.js (Pages Router)

Next.js（Pages Router）

typescript

// pages/index.tsx
import Head from 'next/head'

export default function Page() {
  return (
    <Head>
      <title>Page Title | Brand</title>
      <meta name="description" content="Page description" />
    </Head>
  )
}

typescript

// pages/index.tsx
import Head from 'next/head'

export default function Page() {
  return (
    <Head>
      <title>Page Title | Brand</title>
      <meta name="description" content="Page description" />
    </Head>
  )
}

Astro

astro

---
// src/pages/index.astro
import Layout from '../layouts/Layout.astro';
---
<Layout
  title="Page Title | Brand"
  description="Page description"
  ogImage="/og-image.png"
/>

astro

---
// src/pages/index.astro
import Layout from '../layouts/Layout.astro';
---
<Layout
  title="Page Title | Brand"
  description="Page description"
  ogImage="/og-image.png"
/>

React (react-helmet)

React（react-helmet）

jsx

import { Helmet } from 'react-helmet';

function Page() {
  return (
    <Helmet>
      <title>Page Title | Brand</title>
      <meta name="description" content="Page description" />
    </Helmet>
  );
}

See

references/framework-implementations.md

for complete guides.

jsx

import { Helmet } from 'react-helmet';

function Page() {
  return (
    <Helmet>
      <title>Page Title | Brand</title>
      <meta name="description" content="Page description" />
    </Helmet>
  );
}

完整框架指南见

references/framework-implementations.md

。

Scripts

脚本工具

analyze_seo.py

Analyzes a codebase for SEO issues and opportunities:

bash

python scripts/analyze_seo.py <path-to-project>

Output:

Current SEO state (what's implemented)
Missing elements by priority
Page-by-page recommendations
Structured data opportunities

分析代码库中的SEO问题与优化机会：

bash

python scripts/analyze_seo.py <path-to-project>

输出内容：

当前SEO状态（已实现的功能）
按优先级排列的缺失项
逐页优化建议
结构化数据优化机会

generate_sitemap.py

Generates sitemap.xml from project routes:

bash

python scripts/generate_sitemap.py <path-to-project> --domain https://example.com

根据项目路由生成sitemap.xml：

bash

python scripts/generate_sitemap.py <path-to-project> --domain https://example.com

Remember

谨记

SEO is semantic communication, not algorithm manipulation.

The best SEO:

Accurately describes what content IS
Helps machines understand meaning through structured data
Prioritizes user value over keyword optimization
Uses framework-native patterns
Implements progressively based on page importance

Focus on making your content findable and understandable. The rankings follow from genuine value clearly communicated.

Claude is capable of comprehensive SEO analysis and implementation. These guidelines illuminate the path—they don't fence it.

SEO是语义沟通，而非算法操纵。

优秀的SEO具备以下特点：

准确描述内容本质
通过结构化数据帮助机器理解含义
优先考虑用户价值而非关键词优化
使用框架原生方案
根据页面重要性渐进式实施优化

专注于让你的内容易于被发现和理解，排名自然会随之提升。

Claude可完成全面的SEO分析与实现工作。本指南为你指明方向，而非限制你的思路。