元数据

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

核心功能

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

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

理解元数据系统

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

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.webp',
      logoDark: '/logo-dark.png',
    },
  },
  social: {
    github: 'https://github.com/ShipSaaS',
    twitter: 'https://x.com/ShipSaaS',
    youtube: 'https://www.youtube.com/@ShipSaaS',
  },
  // 其他配置部分...
};

此配置定义：

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

2. 消息文件

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

messages/en.ts

src/messages/en.ts

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

messages/zh.ts

src/messages/zh.ts

export const messages = {
  site: {
    name: 'ShipSaaS',
    title: 'ShipSaaS - 快速构建 SaaS 产品',
    description: 'ShipSaaS 是一个使用最先进技术栈构建的 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: 'ShipSaaS - Home',
      description: 'Welcome to ShipSaaS',
    }),
  }),
  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：

1. 将您的图片放在 public 目录中
2. 在 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',
  youtube: 'https://www.youtube.com/@YourChannel',
},

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

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

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

页面特定元数据

在每个路由中，使用 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 卡片创建专业、相关的图像
• 包含关键词：在标题和描述中自然地包含相关关键词
• 持续更新：保持元数据与您的内容更改同步
• 移动优化：确保您的元数据在移动设备上看起来良好

下一步

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

• 博客 - 配置博客系统

• 组件 - 自定义 UI 组件

• 国际化 - 配置构建时语言支持

• 网站配置 - 配置网站核心设置

• 联盟营销

• 页面