svelte-meta-tags-setup

svelte-meta-tags：设置

步骤 1：安装软件包

检查 package.json 中是否已有 svelte-meta-tags。如果有，请跳至步骤 2。

如果没有，请根据项目的锁文件选择命令，不要根据全局安装的包管理器来选择：

锁文件	命令
pnpm-lock.yaml	pnpm add -D svelte-meta-tags
package-lock.json	npm install --save-dev svelte-meta-tags
yarn.lock	yarn add --dev svelte-meta-tags
bun.lock（或旧版 bun.lockb）	bun add --dev svelte-meta-tags

如果这些锁文件都不存在，请使用 package.json 中的 packageManager 字段；如果该字段也不存在，请询问要使用哪个包管理器，而不要猜测。

将其安装为 dev 依赖：这些组件会编译到使用它的应用中，因此运行时不需要此软件包中的任何内容。

步骤 2：检测是否为 SvelteKit 项目

检查 package.json 的 dependencies/devDependencies 中是否有 @sveltejs/kit，以及是否存在 src/routes/ 目录。

如果这不是 SvelteKit 项目（普通 Svelte，或其他框架/路由器）：跳过本技能的其余部分。导入 MetaTags，并使用项目现有的任何数据获取机制直接向其传递 props：

<script>
  import { MetaTags } from 'svelte-meta-tags';
</script>

<MetaTags title="My Page" description="A short description of this page." />

不要引入 deepMerge、defineBaseMetaTags 或 definePageMetaTags——这些专为 SvelteKit 基于 load 的数据流（跨 +layout.ts/+page.ts）设计，在此场景之外只会增加不必要的复杂性。

如果这是 SvelteKit 项目，请继续步骤 3。

步骤 3：查找或创建基础布局 load 文件

查找 src/routes/+layout.ts（如果项目仅使用服务端数据，则查找 +layout.server.ts）。

• 如果文件存在：阅读该文件。如果其 load 函数已经返回其他数据，请将 defineBaseMetaTags 的结果合并到现有返回对象中，不要覆盖无关字段。
• 如果文件不存在：创建该文件。

基础布局文件应如下所示：

// src/routes/+layout.ts
import { defineBaseMetaTags } from 'svelte-meta-tags';

export const load = () => {
  return {
    ...defineBaseMetaTags({
      title: 'My Site',
      titleTemplate: '%s | My Site',
      description: 'Default description for pages that do not set their own.'
    })
  };
};

步骤 4：检查嵌套布局

查找嵌套路由目录中的其他 +layout.ts 文件（例如 src/routes/blog/+layout.ts）。如果网站的某个部分需要在根布局标签的基础上使用自己的基础标签，请串联调用 deepMerge，而不要重复调用 defineBaseMetaTags：

// src/routes/blog/+layout.ts
import { deepMerge, defineBaseMetaTags } from 'svelte-meta-tags';
import type { LayoutLoad } from './$types';

export const load: LayoutLoad = async ({ parent }) => {
  const { baseMetaTags } = await parent();
  return {
    ...defineBaseMetaTags(
      deepMerge(baseMetaTags, {
        titleTemplate: '%s | Blog | My Site'
      })
    )
  };
};

当嵌套布局像这样覆盖 baseMetaTags 时，请在步骤 6 中使用 page.data.baseMetaTags，而不是 data.baseMetaTags。布局的 data prop 只包含其自身和祖先的 load 结果；子布局的覆盖不会通过 data 传递到根布局。它只会通过 page.data 显示出来，因为 page.data 会合并当前页面上的所有 load 结果，并以最深层的结果为准。

如果没有嵌套布局，请跳过此步骤——步骤 3 和步骤 5 中的标准两层（基础 + 页面）模式已足够。

步骤 5：使用 definePageMetaTags 添加页面级标签

在相关的 +page.ts（或 +page.server.ts）中，返回页面专属的覆盖项：

// src/routes/+page.ts
import { definePageMetaTags } from 'svelte-meta-tags';

export const load = () => {
  return {
    ...definePageMetaTags({
      title: 'Home',
      description: 'Welcome to my site.'
    })
  };
};

并非每个路由都需要自己的 +page.ts——只在页面需要覆盖基础标签时添加。

步骤 6：接入 +layout.svelte

<script>
  import { page } from '$app/state';
  import { MetaTags, deepMerge } from 'svelte-meta-tags';

  let { data, children } = $props();

  let metaTags = $derived(deepMerge(data.baseMetaTags, page.data.pageMetaTags));
</script>

<MetaTags {...metaTags} />

{@render children()}

请从 $app/state 导入 page，而不是 $app/stores——基于 store 的模块已在 SvelteKit 3 中移除，$app/state 是其 Svelte 5 替代方案。

如果步骤 4 添加了嵌套布局覆盖项，请改为从 page.data 读取基础标签，这样分区级覆盖项才能传递到此组件：

let metaTags = $derived(deepMerge(page.data.baseMetaTags, page.data.pageMetaTags));

步骤 7：JSON-LD（可选）

如果项目需要结构化数据（例如用于丰富搜索结果），请说明 <JsonLd schema={...} /> 是一个独立组件，并指向 https://oekazuma.github.io/svelte-meta-tags/json-ld/ 了解详情——不要在此设置流程中设计 JSON-LD 架构。

步骤 8：验证

运行项目的类型检查命令（例如 pnpm check、svelte-check，或 package.json 中定义的命令），并确认没有新增错误后，再认为设置已完成。