元数据

本文档涵盖了 TanStarter 模板中的元数据系统，以及如何自定义 SEO 设置。

核心功能

TanStarter 模板内置了元数据系统，提供：

SEO 优化的页面标题和描述
社交媒体分享元数据（Open Graph 和 Twitter）
网站图标和应用图标 (Logo 和 Favicon)

理解元数据系统

TanStarter 中的元数据通过几个关键文件进行配置：

1. 网站配置

主要网站配置在 src/config/website.ts 中定义：

src/config/website.ts

import { messages } from '@/messages';

export const websiteConfig: WebsiteConfig = {
  metadata: {
    name: messages.site.name,
    title: messages.site.title,
    description: messages.site.description,
    images: {
      ogImage: '/og.png',
      logoLight: '/logo.png',
      logoDark: '/logo-dark.png',
    },
  },
  social: {
    github: 'https://github.com/MkFastHQ',
    discord: 'https://mksaas.link/discord',
    twitter: 'https://x.com/TanStarter',
    youtube: 'https://www.youtube.com/@TanStarter',
  },
  // 其他配置部分...
};

此配置定义：

网站的名称、标题和描述
Logo 和 Open Graph 图像路径
社交平台的官方账号链接

2. 消息文件

基本网站元数据（如名称、标题和描述）在消息文件中定义：

src/messages/en.ts

export const messages = {
  site: {
    name: 'TanStarter',
    title: 'TanStarter - The Best SaaS Boilerplate',
    description: 'TanStarter is a full-stack SaaS boilerplate...',
  },
  // other messages...
} as const;

src/messages/zh.ts

export const messages = {
  site: {
    name: 'TanStarter',
    title: 'TanStarter - 快速构建 SaaS 产品',
    description: 'TanStarter 是一个使用最先进技术栈构建的 SaaS 模板...',
  },
  // 其他消息...
} as const;

要切换当前使用的语言，编辑 src/messages/index.ts 将 re-export 指向目标语言文件即可。

3. SEO 辅助函数

src/lib/seo.ts 中的 seo() 函数为每个页面构建元数据和规范链接：

src/lib/seo.ts

export function seo(
  path: string,
  options: {
    title: string;
    description?: string;
    keywords?: string;
    image?: string;
    type?: 'website' | 'article';
  }
) {
  const url = getCanonicalUrl(path);
  const image = options.image ?? getOgImage();
  return {
    meta: metadata({ ...options, url, image, type: options.type ?? 'website' }),
    links: [{ rel: 'canonical', href: url }],
  };
}

此函数处理：

设置页面标题和描述
配置 Open Graph 和 Twitter 卡片元数据
设置规范 URL
生成 OG 图像 URL

4. 在路由中使用 SEO

每个路由通过 createFileRoute 中的 head() 函数定义其元数据：

src/routes/index.tsx

import { createFileRoute } from '@tanstack/react-router';
import { seo } from '@/lib/seo';

export const Route = createFileRoute('/')({
  head: () => ({
    ...seo('/', {
      title: 'TanStarter - Home',
      description: 'Welcome to TanStarter',
    }),
  }),
  component: HomePage,
});

5. 根布局元数据

根路由（src/routes/__root.tsx）定义全局元数据，包括字符集、视口、网站图标和默认的标题/描述：

src/routes/__root.tsx

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
}>()({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: websiteConfig.metadata?.title },
      { name: 'description', content: websiteConfig.metadata?.description },
    ],
    links: [
      { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' },
      { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon-32x32.png' },
      { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicon-16x16.png' },
      { rel: 'icon', href: '/favicon.ico' },
      { rel: 'manifest', href: '/manifest.json' },
    ],
  }),
  // ...
});

自定义网站元数据

基本网站信息

要更改基本网站信息（如名称、标题和描述），编辑当前使用的语言消息文件：

src/messages/en.ts

export const messages = {
  site: {
    name: '您的网站名称',
    title: '您的网站标题 - 标语',
    description: '您网站的详细描述，用于 SEO 目的',
  },
  // ...
} as const;

自定义社交图像

要更改 Open Graph 图像和 Logo：

将您的图片放在 public 目录中
在 src/config/website.ts 中更新路径：

src/config/website.ts

metadata: {
  // 其他设置...
  images: {
    ogImage: '/your-og-image.png',  // 用于社交分享
    logoLight: '/your-logo-light.png',  // 明亮模式的 Logo
    logoDark: '/your-logo-dark.png',  // 暗黑模式的 Logo
  },
}

推荐尺寸：

OG 图像：1200×630 像素，在社交平台上获得更好的显示效果
Logo：至少 512×512 像素，适用于高分辨率显示

社交媒体链接

在网站配置中更新您的社交媒体官方账号链接：

src/config/website.ts

social: {
  github: 'https://github.com/YourUsername',
  twitter: 'https://x.com/YourHandle',
  discord: 'https://discord.gg/YourInvite',
  youtube: 'https://www.youtube.com/@YourChannel',
},

网站图标和应用图标 (Favicon)

要替换默认的网站图标和应用图标：

使用 Real Favicon Generator 等工具生成完整的图标集
将生成的文件放在 public 目录中
根路由已自动链接这些文件

页面特定元数据

在每个路由中，使用 seo() 辅助函数在 head() 中设置元数据：

export const Route = createFileRoute('/about')({
  head: () => ({
    ...seo('/about', {
      title: '关于我们',
      description: '了解更多关于我们团队的信息',
      image: '/images/about-og.png',
    }),
  }),
  component: AboutPage,
});

博客文章元数据

博客文章使用 frontmatter 元数据，会自动应用：

content/blog/example-post.md

---
title: 示例博客文章
description: 这是一个带有自定义元数据的示例博客文章
image: https://example.com/images/blog/example-post.png
date: "2024-01-01"
category: tutorial
---

内容在这里...

最佳实践

保持标题简洁：目标是标题少于 60 个字符，以在搜索结果中获得更好的显示
描述性元描述：编写 150-160 个字符的引人注目的描述
使用高质量图像：为 OG 和 Twitter 卡片创建专业、相关的图像
包含关键词：在标题和描述中自然地包含相关关键词
持续更新：保持元数据与您的内容更改同步
移动优化：确保您的元数据在移动设备上看起来良好

下一步

现在您了解了如何在 TanStarter 模板中自定义元数据，探索这些相关主题：

博客

配置博客系统

组件

自定义 UI 组件

国际化

配置构建时语言支持

网站配置

配置网站核心设置

本文档涵盖了 TanStarter 模板中的元数据系统，以及如何自定义 SEO 设置。

核心功能

TanStarter 模板内置了元数据系统，提供：

SEO 优化的页面标题和描述
社交媒体分享元数据（Open Graph 和 Twitter）
网站图标和应用图标 (Logo 和 Favicon)

理解元数据系统

TanStarter 中的元数据通过几个关键文件进行配置：

1. 网站配置

主要网站配置在 src/config/website.ts 中定义：

src/config/website.ts

import { messages } from '@/messages';

export const websiteConfig: WebsiteConfig = {
  metadata: {
    name: messages.site.name,
    title: messages.site.title,
    description: messages.site.description,
    images: {
      ogImage: '/og.png',
      logoLight: '/logo.png',
      logoDark: '/logo-dark.png',
    },
  },
  social: {
    github: 'https://github.com/MkFastHQ',
    discord: 'https://mksaas.link/discord',
    twitter: 'https://x.com/TanStarter',
    youtube: 'https://www.youtube.com/@TanStarter',
  },
  // 其他配置部分...
};

此配置定义：

网站的名称、标题和描述
Logo 和 Open Graph 图像路径
社交平台的官方账号链接

2. 消息文件

基本网站元数据（如名称、标题和描述）在消息文件中定义：

src/messages/en.ts

export const messages = {
  site: {
    name: 'TanStarter',
    title: 'TanStarter - The Best SaaS Boilerplate',
    description: 'TanStarter is a full-stack SaaS boilerplate...',
  },
  // other messages...
} as const;

src/messages/zh.ts

export const messages = {
  site: {
    name: 'TanStarter',
    title: 'TanStarter - 快速构建 SaaS 产品',
    description: 'TanStarter 是一个使用最先进技术栈构建的 SaaS 模板...',
  },
  // 其他消息...
} as const;

要切换当前使用的语言，编辑 src/messages/index.ts 将 re-export 指向目标语言文件即可。

3. SEO 辅助函数

src/lib/seo.ts 中的 seo() 函数为每个页面构建元数据和规范链接：

src/lib/seo.ts

export function seo(
  path: string,
  options: {
    title: string;
    description?: string;
    keywords?: string;
    image?: string;
    type?: 'website' | 'article';
  }
) {
  const url = getCanonicalUrl(path);
  const image = options.image ?? getOgImage();
  return {
    meta: metadata({ ...options, url, image, type: options.type ?? 'website' }),
    links: [{ rel: 'canonical', href: url }],
  };
}

此函数处理：

设置页面标题和描述
配置 Open Graph 和 Twitter 卡片元数据
设置规范 URL
生成 OG 图像 URL

4. 在路由中使用 SEO

每个路由通过 createFileRoute 中的 head() 函数定义其元数据：

src/routes/index.tsx

import { createFileRoute } from '@tanstack/react-router';
import { seo } from '@/lib/seo';

export const Route = createFileRoute('/')({
  head: () => ({
    ...seo('/', {
      title: 'TanStarter - Home',
      description: 'Welcome to TanStarter',
    }),
  }),
  component: HomePage,
});

5. 根布局元数据

根路由（src/routes/__root.tsx）定义全局元数据，包括字符集、视口、网站图标和默认的标题/描述：

src/routes/__root.tsx

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
}>()({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: websiteConfig.metadata?.title },
      { name: 'description', content: websiteConfig.metadata?.description },
    ],
    links: [
      { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' },
      { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon-32x32.png' },
      { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicon-16x16.png' },
      { rel: 'icon', href: '/favicon.ico' },
      { rel: 'manifest', href: '/manifest.json' },
    ],
  }),
  // ...
});

自定义网站元数据

基本网站信息

要更改基本网站信息（如名称、标题和描述），编辑当前使用的语言消息文件：

src/messages/en.ts

export const messages = {
  site: {
    name: '您的网站名称',
    title: '您的网站标题 - 标语',
    description: '您网站的详细描述，用于 SEO 目的',
  },
  // ...
} as const;

自定义社交图像

要更改 Open Graph 图像和 Logo：

将您的图片放在 public 目录中
在 src/config/website.ts 中更新路径：

src/config/website.ts

metadata: {
  // 其他设置...
  images: {
    ogImage: '/your-og-image.png',  // 用于社交分享
    logoLight: '/your-logo-light.png',  // 明亮模式的 Logo
    logoDark: '/your-logo-dark.png',  // 暗黑模式的 Logo
  },
}

推荐尺寸：

OG 图像：1200×630 像素，在社交平台上获得更好的显示效果
Logo：至少 512×512 像素，适用于高分辨率显示

社交媒体链接

在网站配置中更新您的社交媒体官方账号链接：

src/config/website.ts

social: {
  github: 'https://github.com/YourUsername',
  twitter: 'https://x.com/YourHandle',
  discord: 'https://discord.gg/YourInvite',
  youtube: 'https://www.youtube.com/@YourChannel',
},

网站图标和应用图标 (Favicon)

要替换默认的网站图标和应用图标：

使用 Real Favicon Generator 等工具生成完整的图标集
将生成的文件放在 public 目录中
根路由已自动链接这些文件

页面特定元数据

在每个路由中，使用 seo() 辅助函数在 head() 中设置元数据：

export const Route = createFileRoute('/about')({
  head: () => ({
    ...seo('/about', {
      title: '关于我们',
      description: '了解更多关于我们团队的信息',
      image: '/images/about-og.png',
    }),
  }),
  component: AboutPage,
});

博客文章元数据

博客文章使用 frontmatter 元数据，会自动应用：

content/blog/example-post.md

---
title: 示例博客文章
description: 这是一个带有自定义元数据的示例博客文章
image: https://example.com/images/blog/example-post.png
date: "2024-01-01"
category: tutorial
---

内容在这里...