seo-meta-tags

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SEO Meta Tags

SEO元标签

Boilerplate and component library for production-ready metadata across three framework targets.

适用于三个框架目标的生产就绪型元数据模板和组件库。

Decision Tree

决策树

Determine the correct framework path first:

Static HTML site or any-backend project — Read references/html.md
Next.js 13+ App Router — Read references/nextjs.md
Vite + React — Read references/vite.md, React section
Vite + Vue 3 — Read references/vite.md, Vue section
Multiple frameworks at once — Read all relevant reference files

Then determine action type:

Creating metadata from scratch? — Read matching reference → copy boilerplate → replace placeholders.
Updating existing metadata? — Load file → keep structure → change requested values → verify parity across tag families.
Auditing / reviewing metadata? — Run through Quality Gate below → report issues.
Migrating between frameworks? — Read source reference → read target reference → map fields.

首先确定正确的框架路径：

静态HTML站点或任意后端项目 — 阅读references/html.md
Next.js 13+ App Router — 阅读references/nextjs.md
Vite + React — 阅读references/vite.md中的React章节
Vite + Vue 3 — 阅读references/vite.md中的Vue章节
同时使用多个框架 — 阅读所有相关参考文件

然后确定操作类型：

从零开始创建元数据？ — 阅读对应参考文档 → 复制模板 → 替换占位符。
更新现有元数据？ — 加载文件 → 保留结构 → 修改指定值 → 确保各元数据家族内容一致。
审核/检查元数据？ — 执行下方的质量检查项 → 报告问题。
在框架间迁移？ — 阅读源框架参考文档 → 阅读目标框架参考文档 → 映射字段。

Framework Selection

框架选择

Framework	When to use	Reference
HTML	Static sites, any backend, SSGs	references/html.md
Next.js	Next.js 13+ App Router projects	references/nextjs.md
Vite	Vite + React or Vite + Vue apps	references/vite.md

Read only the reference file that matches the user's target framework.

框架	使用场景	参考文档
HTML	静态站点、任意后端、静态站点生成器	references/html.md
Next.js	Next.js 13+ App Router 项目	references/nextjs.md
Vite	Vite + React 或 Vite + Vue 应用	references/vite.md

仅阅读与用户目标框架匹配的参考文件。

Metadata Families

元数据家族

Every framework target must keep parity across these families. When modifying one family, verify the others remain consistent.

每个框架目标都必须保持这些元数据家族之间的一致性。修改其中一个家族时，需验证其他家族内容是否一致。

1. Essential / Primary

1. 核心/基础元数据

Tag	Constraint
`<title>` / `title`	Under 60 characters
`description`	150-160 characters
`keywords`	5-10 terms max, comma-separated
`author`	Full name
`robots`	`index, follow` by default; include `max-image-preview:large` , `max-snippet:-1` , `max-video-preview:-1`
`canonical`	Absolute URL, must match deployment URL
`viewport`	`width=device-width, initial-scale=1.0`

标签	约束条件
`<title>` / `title`	长度不超过60个字符
`description`	长度为150-160个字符
`keywords`	最多5-10个术语，用逗号分隔
`author`	完整姓名
`robots`	默认值为 `index, follow` ；需包含 `max-image-preview:large` , `max-snippet:-1` , `max-video-preview:-1`
`canonical`	绝对URL，必须与部署URL一致
`viewport`	`width=device-width, initial-scale=1.0`

2. Open Graph (

og:*

)

2. Open Graph（

og:*

）

Property	Notes
`og:type`	`website` for home/landing; `article` for blog posts; `product` for e-commerce
`og:url`	Absolute URL
`og:title`	Can differ from `<title>` for social context
`og:description`	Can differ from meta description
`og:image`	Absolute URL, 1200x630px, JPG or PNG, under 1 MB
`og:image:width` / `og:image:height`	`1200` / `630`
`og:image:alt`	Required when image is present
`og:site_name`	Brand name
`og:locale`	e.g. `en_US`

For

article

type also include:

article:published_time

article:modified_time

article:author

article:tag

属性	说明
`og:type`	首页/落地页用 `website` ；博客文章用 `article` ；电商页面用 `product`
`og:url`	绝对URL
`og:title`	可与 `<title>` 不同，适配社交场景
`og:description`	可与meta description不同
`og:image`	绝对URL，尺寸1200x630px，格式为JPG或PNG，大小不超过1 MB
`og:image:width` / `og:image:height`	`1200` / `630`
`og:image:alt`	存在图片时必须设置
`og:site_name`	品牌名称
`og:locale`	示例： `en_US`

对于

article

类型，还需包含：

article:published_time

article:modified_time

article:author

article:tag

。

3. Twitter Cards (

twitter:*

)

3. Twitter Cards（

twitter:*

）

Property	Notes
`twitter:card`	`summary_large_image` (default) or `summary`
`twitter:site`	Organization handle with `@` prefix
`twitter:creator`	Author handle with `@` prefix
`twitter:title`	Under 70 characters
`twitter:description`	Under 200 characters
`twitter:image`	Same spec as OG image
`twitter:image:alt`	Required when image is present

属性	说明
`twitter:card`	默认值为 `summary_large_image` ，或使用 `summary`
`twitter:site`	带 `@` 前缀的机构账号
`twitter:creator`	带 `@` 前缀的作者账号
`twitter:title`	长度不超过70个字符
`twitter:description`	长度不超过200个字符
`twitter:image`	与Open Graph图片规格一致
`twitter:image:alt`	存在图片时必须设置

4. Theme Color

4. 主题色

Provide three values:

Default:
```
<meta name="theme-color" content="...">
```
or single value
Light:
```
media="(prefers-color-scheme: light)"
```
Dark:
```
media="(prefers-color-scheme: dark)"
```

Next.js uses the

themeColor

array in the Metadata object.

提供三个值：

默认值：
```
<meta name="theme-color" content="...">
```
或单个值
浅色模式：
```
media="(prefers-color-scheme: light)"
```
深色模式：
```
media="(prefers-color-scheme: dark)"
```

Next.js 中需在Metadata对象的

themeColor

数组中配置。

5. Icons and Manifest

5. 图标和清单

Asset	Size	Format
`favicon.ico`	32x32 or multi-size	ICO
`icon-16x16.png`	16x16	PNG
`icon-32x32.png`	32x32	PNG
`apple-touch-icon.png`	180x180	PNG
`site.webmanifest`	n/a	JSON

Generate with favicon.io or RealFaviconGenerator.

资源	尺寸	格式
`favicon.ico`	32x32 或多尺寸	ICO
`icon-16x16.png`	16x16	PNG
`icon-32x32.png`	32x32	PNG
`apple-touch-icon.png`	180x180	PNG
`site.webmanifest`	无要求	JSON

可通过favicon.io或RealFaviconGenerator生成。

6. Structured Data (JSON-LD)

6. 结构化数据（JSON-LD）

Emit a

<script type="application/ld+json">

block (HTML/Vite) or use a separate Script component in Next.js. Required keys:

json

{
	"@context": "https://schema.org",
	"@type": "WebSite",
	"name": "",
	"description": "",
	"url": "",
	"image": { "@type": "ImageObject", "url": "", "width": 1200, "height": 630 },
	"author": { "@type": "Person", "name": "" },
	"publisher": {
		"@type": "Organization",
		"name": "",
		"logo": { "@type": "ImageObject", "url": "" }
	}
}

Common

@type

values:

WebSite

Article

Organization

Product

FAQPage

BreadcrumbList

在HTML/Vite中添加

<script type="application/ld+json">

代码块，在Next.js中使用独立的Script组件。必填字段：

json

{
	"@context": "https://schema.org",
	"@type": "WebSite",
	"name": "",
	"description": "",
	"url": "",
	"image": { "@type": "ImageObject", "url": "", "width": 1200, "height": 630 },
	"author": { "@type": "Person", "name": "" },
	"publisher": {
		"@type": "Organization",
		"name": "",
		"logo": { "@type": "ImageObject", "url": "" }
	}
}

常见的

@type

值：

WebSite

Article

Organization

Product

FAQPage

BreadcrumbList

。

7. Internationalization (hreflang)

7. 国际化（hreflang）

html

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Next.js equivalent:

alternates.languages

in the Metadata object.

html

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Next.js 中的等效配置：在Metadata对象的

alternates.languages

中设置。

8. Performance Hints

8. 性能提示

Include when external resources are used:

html

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="dns-prefetch" href="https://www.google-analytics.com" />

使用外部资源时需添加：

html

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="dns-prefetch" href="https://www.google-analytics.com" />

Placeholder Tokens

占位符标记

All boilerplate files use

{{PLACEHOLDER_NAME}}

tokens. Common tokens:

Token	Purpose
`{{PAGE_TITLE}}`	Page `<title>`
`{{PAGE_DESCRIPTION}}`	Meta description
`{{PAGE_URL}}`	Page URL (absolute)
`{{CANONICAL_URL}}`	Canonical URL
`{{KEYWORDS}}`	Comma-separated keywords
`{{AUTHOR_NAME}}`	Content author
`{{SITE_NAME}}`	Brand / site name
`{{THEME_COLOR}}` / `{{THEME_COLOR_LIGHT}}` / `{{THEME_COLOR_DARK}}`	Hex color codes
`{{OG_TITLE}}` / `{{OG_DESCRIPTION}}` / `{{OG_IMAGE_URL}}` / `{{OG_IMAGE_ALT}}`	Open Graph
`{{TWITTER_TITLE}}` / `{{TWITTER_DESCRIPTION}}` / `{{TWITTER_IMAGE_URL}}` / `{{TWITTER_IMAGE_ALT}}`	Twitter
`{{TWITTER_HANDLE}}` / `{{TWITTER_CREATOR_HANDLE}}`	Twitter handles
`{{SCHEMA_TYPE}}` / `{{SCHEMA_IMAGE_URL}}`	JSON-LD
`{{PUBLISHER_NAME}}` / `{{PUBLISHER_LOGO_URL}}`	Publisher org
`{{FAVICON_32x32_URL}}` / `{{FAVICON_16x16_URL}}` / `{{APPLE_TOUCH_ICON_URL}}`	Icons
`{{AUTHOR_URL}}`	Author website URL (Next.js)
`{{CREATOR_NAME}}`	Content creator name (Next.js)
`{{CATEGORY}}`	Site category (Next.js)
`{{GOOGLE_VERIFICATION_CODE}}` / `{{YANDEX_VERIFICATION_CODE}}` / `{{FACEBOOK_VERIFICATION_CODE}}`	Search engine verification codes (Next.js)
`{{EN_URL}}` / `{{ES_URL}}`	Language-specific alternate URLs (Next.js)
`{{ALTERNATE_EN_URL}}` / `{{ALTERNATE_DEFAULT_URL}}`	hreflang alternate URLs (HTML/Vite)

When implementing for a user, replace every

{{...}}

token. Never leave placeholders in production output.

所有模板文件均使用

{{PLACEHOLDER_NAME}}

占位符标记。常见标记：

标记	用途
`{{PAGE_TITLE}}`	页面 `<title>`
`{{PAGE_DESCRIPTION}}`	Meta描述
`{{PAGE_URL}}`	页面URL（绝对路径）
`{{CANONICAL_URL}}`	规范URL
`{{KEYWORDS}}`	逗号分隔的关键词
`{{AUTHOR_NAME}}`	内容作者
`{{SITE_NAME}}`	品牌/站点名称
`{{THEME_COLOR}}` / `{{THEME_COLOR_LIGHT}}` / `{{THEME_COLOR_DARK}}`	十六进制颜色代码
`{{OG_TITLE}}` / `{{OG_DESCRIPTION}}` / `{{OG_IMAGE_URL}}` / `{{OG_IMAGE_ALT}}`	Open Graph相关参数
`{{TWITTER_TITLE}}` / `{{TWITTER_DESCRIPTION}}` / `{{TWITTER_IMAGE_URL}}` / `{{TWITTER_IMAGE_ALT}}`	Twitter相关参数
`{{TWITTER_HANDLE}}` / `{{TWITTER_CREATOR_HANDLE}}`	Twitter账号
`{{SCHEMA_TYPE}}` / `{{SCHEMA_IMAGE_URL}}`	JSON-LD相关参数
`{{PUBLISHER_NAME}}` / `{{PUBLISHER_LOGO_URL}}`	发布机构信息
`{{FAVICON_32x32_URL}}` / `{{FAVICON_16x16_URL}}` / `{{APPLE_TOUCH_ICON_URL}}`	图标地址
`{{AUTHOR_URL}}`	作者网站URL（Next.js）
`{{CREATOR_NAME}}`	内容创作者名称（Next.js）
`{{CATEGORY}}`	站点分类（Next.js）
`{{GOOGLE_VERIFICATION_CODE}}` / `{{YANDEX_VERIFICATION_CODE}}` / `{{FACEBOOK_VERIFICATION_CODE}}`	搜索引擎验证代码（Next.js）
`{{EN_URL}}` / `{{ES_URL}}`	多语言替代URL（Next.js）
`{{ALTERNATE_EN_URL}}` / `{{ALTERNATE_DEFAULT_URL}}`	hreflang替代URL（HTML/Vite）

为用户实现时，需替换所有

{{...}}

标记。生产环境中绝不能保留占位符。

Quality Gate

质量检查项

Run these checks before considering any metadata task complete:

No placeholders — grep for
```
{{
```
in all modified files; count must be zero.
Absolute URLs — canonical, OG url, OG image, Twitter image, JSON-LD url/image must start with
```
https://
```
.
Image alt text — every
```
og:image
```
/
```
twitter:image
```
must have a corresponding alt field.
No duplicate tags — no two conflicting
```
<title>
```
,
```
description
```
, or
```
canonical
```
tags in the same scope.
Title length — verify under 60 characters.
Description length — verify 150-160 characters.
JSON-LD validity — valid JSON with required
```
@context
```
and
```
@type
```
keys.
OG/Twitter parity — if OG title is set, Twitter title should also be set (and vice versa).
Canonical consistency — canonical URL matches the actual page URL or intended redirect target.
Theme color — includes both light and dark media variants.
hreflang — includes
```
x-default
```
when language alternates exist.
Robots — allows indexing unless user explicitly requests noindex.

在完成任何元数据任务前，执行以下检查：

无占位符 — 在所有修改的文件中搜索
```
{{
```
，结果数量必须为零。
绝对URL — 规范链接、Open Graph URL、Open Graph图片、Twitter图片、JSON-LD URL/图片必须以
```
https://
```
开头。
图片替代文本 — 每个
```
og:image
```
/
```
twitter:image
```
必须对应一个替代文本字段。
无重复标签 — 同一作用域内（布局 vs 页面）不能存在冲突的
```
<title>
```
、
```
description
```
或
```
canonical
```
标签。
标题长度 — 验证长度不超过60个字符。
描述长度 — 验证长度为150-160个字符。
JSON-LD有效性 — 包含必填的
```
@context
```
和
```
@type
```
字段的有效JSON。
Open Graph/Twitter一致性 — 若设置了Open Graph标题，也需设置Twitter标题（反之亦然）。
规范链接一致性 — 规范URL与实际页面URL或预期重定向目标一致。
主题色 — 包含浅色和深色模式的媒体查询变体。
hreflang — 存在多语言替代链接时需包含
```
x-default
```
。
Robots设置 — 允许索引，除非用户明确要求禁止索引。

Image Specifications

图片规格

Use case	Dimensions	Ratio	Format	Max size
OG / Twitter	1200x630	1.91:1	JPG or PNG	1 MB
Favicon 32	32x32	1:1	PNG	n/a
Favicon 16	16x16	1:1	PNG	n/a
Apple Touch	180x180	1:1	PNG	n/a

使用场景	尺寸	比例	格式	最大尺寸
Open Graph / Twitter	1200x630	1.91:1	JPG或PNG	1 MB
32x32图标	32x32	1:1	PNG	无要求
16x16图标	16x16	1:1	PNG	无要求
Apple触摸图标	180x180	1:1	PNG	无要求

Testing Tools

测试工具

Recommend to users after deployment:

部署后推荐用户使用以下工具：

Common Mistakes

常见错误

Mistake	Impact	Fix
Relative URLs in `og:image` or `twitter:image`	Social platforms can't fetch the image	Always use absolute URLs starting with `https://`
Missing `<HelmetProvider>` in Vite React	All `<SEO>` tags silently fail to render	Wrap app root in `<HelmetProvider>` in `main.tsx`
Missing `createHead()` in Vite Vue	`useHead()` throws at runtime	Call `app.use(createHead())` in `main.ts`
Committing verification codes to public repos	Exposes site ownership tokens	Use environment variables for `verification` values
Duplicate `<title>` or `description` tags	Crawlers pick an unpredictable one	Use only one source of truth per scope (layout vs. page)
`og:image` set without `og:image:alt`	Accessibility failure, some validators warn	Always pair image with alt text
Using `generateMetadata` for static pages	Unnecessary async overhead on every request	Use static `export const metadata` when values are known at build time
Leaving `{{...}}` placeholder tokens	Broken display on social platforms, poor SEO	Grep for `{{` before shipping
JSON-LD with trailing commas or comments	Invalid JSON, structured data ignored	Validate JSON before finishing
`twitter:card` set to `summary` when image is 1200x630	Image gets cropped to tiny square	Use `summary_large_image` for landscape images

错误	影响	修复方案
`og:image` 或 `twitter:image` 中使用相对URL	社交平台无法获取图片	始终使用以 `https://` 开头的绝对URL
Vite React中缺少 `<HelmetProvider>`	所有 `<SEO>` 标签无法渲染	在 `main.tsx` 中用 `<HelmetProvider>` 包裹应用根组件
Vite Vue中缺少 `createHead()`	`useHead()` 运行时抛出异常	在 `main.ts` 中调用 `app.use(createHead())`
将验证代码提交到公共仓库	暴露站点所有权令牌	使用环境变量存储 `verification` 值
重复的 `<title>` 或 `description` 标签	爬虫会随机选择其中一个	每个作用域（布局 vs 页面）仅保留一个可信数据源
设置 `og:image` 但未设置 `og:image:alt`	可访问性不达标，部分验证工具会发出警告	始终为图片添加替代文本
静态页面使用 `generateMetadata`	每次请求都会产生不必要的异步开销	若构建时已知值，使用静态 `export const metadata`
遗留 `{{...}}` 占位符标记	社交平台显示异常，SEO效果差	上线前搜索 `{{` 检查是否有遗留占位符
JSON-LD中存在尾随逗号或注释	JSON无效，结构化数据被忽略	完成前验证JSON格式
图片尺寸为1200x630时 `twitter:card` 设为 `summary`	图片被裁剪为小方形	横向图片使用 `summary_large_image`

Migration Paths

迁移路径

From	To	Notes
`react-helmet`	Vite React ( `SEO.tsx` )	Replace with `react-helmet-async` ; wrap root in `<HelmetProvider>`
`vue-meta`	Vite Vue ( `SEO.vue` )	Replace `metaInfo` with `@unhead/vue` `useHead()` composable
`next-seo`	Next.js ( `metadata.ts` )	Remove `<NextSeo>` ; use exported `metadata` or `generateMetadata`
Pages Router `<Head>`	App Router	Replace `import Head` with `export const metadata`

源框架/库	目标框架/库	说明
`react-helmet`	Vite React（ `SEO.tsx` ）	替换为 `react-helmet-async` ；用 `<HelmetProvider>` 包裹根组件
`vue-meta`	Vite Vue（ `SEO.vue` ）	用 `@unhead/vue` 的 `useHead()` 组合式API替换 `metaInfo`
`next-seo`	Next.js（ `metadata.ts` ）	移除 `<NextSeo>` ；使用导出的 `metadata` 或 `generateMetadata`
Pages Router `<Head>`	App Router	替换 `import Head` 为 `export const metadata`

seo-meta-tags

Original

Translation

SEO Meta Tags

SEO元标签

Decision Tree

决策树

Framework Selection

框架选择

Metadata Families

元数据家族

1. Essential / Primary

1. 核心/基础元数据

2. Open Graph (
`og:*`
)

2. Open Graph（
`og:*`
）

3. Twitter Cards (
`twitter:*`
)

3. Twitter Cards（
`twitter:*`
）

4. Theme Color

4. 主题色

5. Icons and Manifest

5. 图标和清单

6. Structured Data (JSON-LD)

6. 结构化数据（JSON-LD）

7. Internationalization (hreflang)

7. 国际化（hreflang）

8. Performance Hints

8. 性能提示

Placeholder Tokens

占位符标记

Quality Gate

质量检查项

Image Specifications

图片规格

Testing Tools

测试工具

Common Mistakes

常见错误

Migration Paths

迁移路径

seo-meta-tags

Original

Translation

SEO Meta Tags

SEO元标签

Decision Tree

决策树

Framework Selection

框架选择

Metadata Families

元数据家族

1. Essential / Primary

1. 核心/基础元数据

2. Open Graph (og:*)

2. Open Graph（og:*）

3. Twitter Cards (twitter:*)

3. Twitter Cards（twitter:*）

4. Theme Color

4. 主题色

5. Icons and Manifest

5. 图标和清单

6. Structured Data (JSON-LD)

6. 结构化数据（JSON-LD）

7. Internationalization (hreflang)

7. 国际化（hreflang）

8. Performance Hints

8. 性能提示

Placeholder Tokens

占位符标记

Quality Gate

质量检查项

Image Specifications

图片规格

Testing Tools

测试工具

Common Mistakes

常见错误

Migration Paths

迁移路径

2. Open Graph (
`og:*`
)

2. Open Graph（
`og:*`
）

3. Twitter Cards (
`twitter:*`
)

3. Twitter Cards（
`twitter:*`
）