1
.m3-btn
2
  background: var(--primary)
3
  color: var(--on-primary)
4
  border-radius: var(--shape-corner-m)

1
{
2
  "name": "button-demo",
3
  "version": "1.0.0"
4
}

1
import type { AboutConfig } from "../types/aboutConfig.ts";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
export const aboutConfig: AboutConfig = withUserConfig("about", {
5
  enable: true,
6
  title: "$t:about",
7
  description: "$t:about",
8
});

1
import type { AlbumsConfig } from "../types/albumsConfig.ts";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
export const albumsConfig: AlbumsConfig = withUserConfig("albums", {
5
  enable: true,
6
  title: "$t:albums",
7
  description: "$t:albumsBanner",
8
});

1
import type {
2
  AnimeConfig,
3
  AnimeFallbackKind,
4
  AnimeProvider,
5
  AnimeSourceKind,
6
  ResolvedAnimeOptions,
7
} from "../types/animeConfig.ts";
8
import { withUserConfig } from "../utils/config-overlay.ts";
9

10
/**
11
 * ─────────────────────────────────────────────────────────────────────────────
12
 *  Shirone 番剧页面与外部数据源配置
13
 * ─────────────────────────────────────────────────────────────────────────────
14
 *
15
 * 遵循「零额外负担」原则与双平面模型（`docs/remote-data-system.md`）：
16
 * - 本地模式 (local)：完全离线，直接使用 `src/data/anime.ts`，零网络、零构建脚本负担；
17
 * - 快照模式 (snapshot)：读取构建期抓取清洗后的本地脱敏 JSON 快照（`src/data/anime-snapshots/`）；
18
 * - 外部同步完全发生在显式 `pnpm anime:sync` 阶段，严禁页面运行时或默认构建时直接请求外部 API；
19
 * - 私密凭据（如 B站 SESSDATA）仅通过环境变量注入同步进程，绝不进入客户端代码与 Git 提交。
20
 *
21
 * ─────────────────────────────────────────────────────────────────────────────
22
 * 【常用配置场景】
23
 * ─────────────────────────────────────────────────────────────────────────────
24
 * 场景 A：使用本地手写数据（默认，最稳定安全）
25
 *   ```ts
26
 *   source: { kind: "local" }
27
 *   ```
28
 *
29
 * 场景 B：使用 Bangumi 追番快照
30
 *   1. 填入你的 Bangumi 用户 ID，将 `providers.bangumi.enable` 置为 `true`；
31
 *   2. 将 `source` 设置为 `{ kind: "snapshot", provider: "bangumi" }`；
32
 *   3. 终端执行 `pnpm.cmd anime:sync --provider bangumi` 生成快照。
33
 *
34
 * 场景 C：使用 Bilibili 追番快照
35
 *   1. 填入你的 B 站 UID (`vmid`)，将 `providers.bilibili.enable` 置为 `true`；
36
 *   2. 若追番列表设为私密，在 `.env` 中配置 `BILI_SESSDATA="your_sessdata"`；
37
 *   3. 将 `source` 设置为 `{ kind: "snapshot", provider: "bilibili" }`；
38
 *   4. 终端执行 `pnpm.cmd anime:sync --provider bilibili` 生成快照。
39
 * ─────────────────────────────────────────────────────────────────────────────
40
 */
41
export const animeConfig: AnimeConfig = withUserConfig("anime", {
42
  /** 是否启用番剧页；false 时导航入口同步隐藏，访问 /anime/ 跳转 404 */
43
  enable: true,
44
  title: "$t:anime",
45
  description: "$t:animeBanner",
46

47
  /** 主数据源选择 */
48
  source: {
49
    kind: "local",
50
    // provider: "bangumi",
51
    // file: "bangumi.json",
52
    // fetchOnDev: true,
53
  },
54

55
  /** 异常降级策略（快照丢失或解析失败时回退本地数据） */
56
  fallback: {
57
    kind: "local",
58
  },
59

60
  /** 外部提供方配置 */
61
  providers: {
62
    bangumi: {
63
      enable: false,
64
      userId: "", // 填入你的 Bangumi 数字 UID 或公开用户名（测试可填 "sai"）
65
      request: {
66
        pageSize: 50,
67
        maxItems: 300,
68
        minDelayMs: 200,
69
      },
70
    },
71
    bilibili: {
72
      enable: false,
73
      vmid: "", // 填入你的 B 站公开 UID
74
      sessdataEnv: "BILI_SESSDATA",
75
      cover: {
76
        mode: "local", // "local" 站内下载缓存（推荐）| "remote" 远程链接 | "none"
77
        useWebp: true,
78
      },
79
      request: {
80
        pageSize: 30,
81
        maxItems: 300,
82
        minDelayMs: 300,
83
      },
84
    },
85
  },
86

87
  /** 快照存储管理 */
88
  snapshot: {
89
    directory: "src/data/anime-snapshots",
90
    staleAfterDays: 30,
91
    keepLastValid: true,
92
  },
93
});
94

95
const SAFE_FILENAME_PATTERN = /^[a-zA-Z0-9_-]+\.json$/;
96

97
/**
98
 * 校验并解析 Anime 配置，返回只读的标准选项
99
 */
100
export function resolveAnimeOptions(config: AnimeConfig): ResolvedAnimeOptions {
101
  const enable = Boolean(config.enable);
102
  const fallback: AnimeFallbackKind =
103
    config.fallback?.kind === "empty" ? "empty" : "local";
104

105
  const directory =
106
    typeof config.snapshot?.directory === "string" &&
107
    config.snapshot.directory.trim() &&
108
    !config.snapshot.directory.includes("..")
109
      ? config.snapshot.directory.trim().replace(/[\\/]+$/, "")
110
      : "src/data/anime-snapshots";
111

112
  const staleAfterDays =
113
    typeof config.snapshot?.staleAfterDays === "number" &&
114
    Number.isFinite(config.snapshot.staleAfterDays) &&
115
    config.snapshot.staleAfterDays > 0
116
      ? Math.floor(config.snapshot.staleAfterDays)
117
      : 30;
118

119
  const keepLastValid = config.snapshot?.keepLastValid ?? true;
120

121
  const rawKind = config.source?.kind;
122
  let kind: AnimeSourceKind = "local";
123
  let provider: AnimeProvider | undefined;
124
  let file: string | undefined;
125

126
  if (rawKind === "snapshot") {
127
    const rawProvider = config.source?.provider;
128
    if (rawProvider === "bangumi" || rawProvider === "bilibili") {
129
      provider = rawProvider;
130
    }
131

132
    const rawFile = config.source?.file?.trim();
133
    if (
134
      rawFile &&
135
      SAFE_FILENAME_PATTERN.test(rawFile) &&
136
      // 若指定了 provider 但 file 误填了另一 provider 的 json，自动校正为对应 provider 的 json 文件
137
      !(provider === "bilibili" && rawFile === "bangumi.json") &&
138
      !(provider === "bangumi" && rawFile === "bilibili.json")
139
    ) {
140
      file = rawFile;
141
    } else if (provider) {
142
      file = `${provider}.json`;
143
    }
144

145
    const fetchOnDev = config.source?.fetchOnDev ?? true;
146

147
    if (file) {
148
      kind = "snapshot";
149
    }
150

151
    return Object.freeze({
152
      enable,
153
      source: Object.freeze({
154
        kind,
155
        ...(provider ? { provider } : {}),
156
        ...(file ? { file } : {}),
157
        fetchOnDev,
158
      }),
159
      fallback,
160
      snapshot: Object.freeze({
161
        directory,
162
        staleAfterDays,
163
        keepLastValid,
164
      }),
165
    });
166
  }
167

168
  return Object.freeze({
169
    enable,
170
    source: Object.freeze({
171
      kind,
172
      ...(provider ? { provider } : {}),
173
      ...(file ? { file } : {}),
174
      fetchOnDev: config.source?.fetchOnDev ?? true,
175
    }),
176
    fallback,
177
    snapshot: Object.freeze({
178
      directory,
179
      staleAfterDays,
180
      keepLastValid,
181
    }),
182
  });
183
}
184

185
export const resolvedAnimeOptions: ResolvedAnimeOptions =
186
  resolveAnimeOptions(animeConfig);

1
import type { AnnouncementConfig } from "@/types/announcementConfig";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
/**
5
 * 公告栏配置
6
 * 组件显示由 sidebarConfig 统一控制
7
 */
8
export const announcementConfig: AnnouncementConfig = withUserConfig(
9
  "announcement",
10
  {
11
    title: "", // 公告标题，填空使用 i18n 字符串 Key.announcement
12
    content: "The only way to do great work is to love what you do", // 公告内容
13
    closable: true, // 允许用户关闭公告
14
    link: {
15
      enable: true, // 启用链接
16
      text: "GitHub", // 链接文本
17
      url: "https://github.com", // 链接 URL
18
      external: true, // 外部链接
19
    },
20
  },
21
);

1
import type { ArticleConfig } from "@/types/articleConfig";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
/**
5
 * 文章详情页配置。
6
 */
7
export const articleConfig: ArticleConfig = withUserConfig("article", {
8
  lastUpdated: {
9
    // 关闭后不渲染最后更新提示。
10
    enable: true,
11
    // 按 UTC 日历日计算；达到该天数当天开始显示，0 表示立即显示。
12
    minimumAgeDays: 90,
13
  },
14
  discovery: {
15
    // 总开关关闭后不计算、不渲染文章尾部的延伸阅读区域。
16
    enable: true,
17
    related: {
18
      // 只展示至少共享一个标签或分类的文章。
19
      enable: true,
20
      count: 3,
21
    },
22
    random: {
23
      // 按当前文章标识稳定抽样；同一构建中的结果不会随刷新变化。
24
      enable: true,
25
      count: 2,
26
    },
27
  },
28
  share: {
29
    // 关闭后不渲染文章尾部的分享区块，不引入客户端水合。
30
    enable: true,
31
    // 生成海报时是否默认包含文章封面（封面不可用时自动降级为无封面排版）。
32
    includeCover: true,
33
  },
34
});
35

36
const MAX_DISCOVERY_COUNT = 6;
37

38
export interface ArticleDiscoveryOptions {
39
  relatedCount: number;
40
  randomCount: number;
41
}
42

43
export interface ArticleShareOptions {
44
  includeCover: boolean;
45
}
46

47
export function normalizeDiscoveryCount(value: number): number {
48
  return Number.isFinite(value)
49
    ? Math.min(MAX_DISCOVERY_COUNT, Math.max(0, Math.floor(value)))
50
    : 0;
51
}
52

53
export function resolveArticleDiscoveryOptions(
54
  config: Pick<ArticleConfig, "discovery">,
55
): ArticleDiscoveryOptions | null {
56
  if (!config.discovery.enable) return null;
57

58
  const relatedCount = config.discovery.related.enable
59
    ? normalizeDiscoveryCount(config.discovery.related.count)
60
    : 0;
61
  const randomCount = config.discovery.random.enable
62
    ? normalizeDiscoveryCount(config.discovery.random.count)
63
    : 0;
64

65
  return relatedCount > 0 || randomCount > 0
66
    ? { relatedCount, randomCount }
67
    : null;
68
}
69

70
export function resolveArticleShareOptions(
71
  config: Pick<ArticleConfig, "share">,
72
): ArticleShareOptions | null {
73
  if (!config.share.enable) return null;
74
  return { includeCover: config.share.includeCover };
75
}
76

77
export function resolveLastUpdatedNoticeOptions(
78
  config: Pick<ArticleConfig, "lastUpdated">,
79
): ArticleConfig["lastUpdated"] | null {
80
  return config.lastUpdated.enable ? config.lastUpdated : null;
81
}

1
import type {
2
  CommentConfig,
3
  GiscusConfig,
4
  TwikooConfig,
5
} from "@/types/commentConfig";
6
import { withUserConfig } from "../utils/config-overlay.ts";
7

8
/**
9
 * 评论系统配置单一真源。
10
 *
11
 * 遵循「零额外负担」原则：默认全局关闭（enable: false），
12
 * 在未开启时不产生任何外部网络请求、零额外 DOM 占位与零包体积膨胀。
13
 *
14
 * 【开启 Twikoo 评论配置步骤】
15
 * 1. 部署 Twikoo 服务端并获取环境 ID（腾讯云 CloudBase / Vercel / Railway / 私有部署等）；
16
 * 2. 将 `enable` 置为 `true`，并将 `provider` 设置为 `"twikoo"`；
17
 * 3. 填入你的 `twikoo.envId`；
18
 * 4. （可选）自定义 `scriptUrl`（如使用自建 CDN 或官方 unpkg/jsdelivr 源）。
19
 *
20
 * 【开启 Giscus 评论配置步骤】
21
 * 1. 准备一个公开 GitHub 仓库，并在仓库设置中开启 Discussions 功能；
22
 * 2. 安装 giscus App（https://github.com/apps/giscus）到该仓库；
23
 * 3. 在 https://giscus.app 按引导选择仓库与 Discussion 分类，
24
 *    取生成的 `data-repo-id` 与 `data-category-id`；
25
 * 4. 将 `enable` 置为 `true`，并将 `provider` 设置为 `"giscus"`，
26
 *    填入 `giscus.repo` / `giscus.repoId` / `giscus.categoryId` 三个必填字段；
27
 * 5. （可选）调整 `mapping`、`reactionsEnabled`、`inputPosition`、
28
 *    `theme.light` / `theme.dark`（giscus 主题键或自定义主题 CSS URL）、
29
 *    `lang` 与 `scriptUrl`（自托管 giscus 时替换）。
30
 */
31
export const commentConfig: CommentConfig = withUserConfig("comment", {
32
  /** 全局评论总开关：false 时完全不加载评论脚本与 DOM */
33
  enable: false,
34
  /** 评论提供商类型："none" | "twikoo" | "giscus" */
35
  provider: "none",
36
  /** 是否开启视口懒加载：滚动进入视口才动态加载评论组件（推荐 true） */
37
  lazy: true,
38
  /** Twikoo 专有配置 */
39
  twikoo: {
40
    /** Twikoo 环境 ID（如 "https://your-twikoo.vercel.app" 或腾讯云环境 ID） */
41
    envId: "",
42
    /** Twikoo 前端 JS 脚本 CDN 地址 */
43
    scriptUrl: "https://cdn.jsdelivr.net/npm/twikoo@1.7.20/dist/twikoo.min.js",
44
    /** 评论语言："auto"（跟随站点）| "zh-CN" | "zh-TW" | "en" | "ja" 等 */
45
    lang: "auto",
46
    /** 评论输入框占位提示文本 */
47
    placeholder: "Share your thoughts...",
48
  },
49
  /** Giscus 专有配置（基于 GitHub Discussions，评论数据存储在公开仓库中） */
50
  giscus: {
51
    /** 公开仓库，格式 "owner/repo"（必填） */
52
    repo: "",
53
    /** 仓库 ID，从 giscus.app 配置生成器获取（必填） */
54
    repoId: "",
55
    /** Discussion 分类名，如 "Announcements"；留空表示不限制分类搜索范围 */
56
    category: "Announcements",
57
    /** 分类 ID，从 giscus.app 配置生成器获取（必填） */
58
    categoryId: "",
59
    /** 页面 ↔ Discussion 映射：pathname（默认）/ url / title / og:title / specific / number */
60
    mapping: "pathname",
61
    /** 严格标题匹配（SHA-1 校验），避免 GitHub 模糊搜索误配相似标题 */
62
    strict: false,
63
    /** 是否显示主贴表情反应 */
64
    reactionsEnabled: true,
65
    /** 是否向父页面周期性发送 Discussion 元数据（供脚本消费） */
66
    emitMetadata: false,
67
    /** 评论输入框位置：bottom（默认，评论框在列表下方）| top（评论框在列表上方） */
68
    inputPosition: "bottom",
69
    /** 明暗两套 giscus 主题（giscus 主题键或自定义主题 CSS URL），跟随站点明暗切换 */
70
    theme: { light: "light", dark: "dark" },
71
    /** 评论语言："auto"（跟随站点）| giscus 语言码（如 "zh-CN"、"en"） */
72
    lang: "auto",
73
    /** giscus client.js 地址；自托管 giscus 时替换为自有地址 */
74
    scriptUrl: "https://giscus.app/client.js",
75
  },
76
});
77

78
export type ResolvedCommentOptions =
79
  | {
80
      provider: "twikoo";
81
      lazy: boolean;
82
      twikoo: TwikooConfig;
83
    }
84
  | {
85
      provider: "giscus";
86
      lazy: boolean;
87
      giscus: GiscusConfig;
88
    }
89
  | null;
90

91
/**
92
 * 解析并校验评论配置。未启用、提供商为 none 或关键参数缺失时返回 null。
93
 * 校验收敛在此纯函数中，消费组件只消费解析结果并短路。
94
 */
95
export function resolveCommentOptions(
96
  config: CommentConfig,
97
): ResolvedCommentOptions {
98
  if (!config.enable || config.provider === "none") {
99
    return null;
100
  }
101
  if (config.provider === "twikoo") {
102
    const envId = config.twikoo.envId?.trim();
103
    const scriptUrl = config.twikoo.scriptUrl?.trim();
104
    if (!envId || !scriptUrl) {
105
      return null;
106
    }
107
    return {
108
      provider: "twikoo",
109
      lazy: config.lazy,
110
      twikoo: {
111
        ...config.twikoo,
112
        envId,
113
        scriptUrl,
114
      },
115
    };
116
  }
117
  if (config.provider === "giscus") {
118
    const repo = config.giscus.repo?.trim();
119
    const repoId = config.giscus.repoId?.trim();
120
    const categoryId = config.giscus.categoryId?.trim();
121
    if (!repo || !repoId || !categoryId) {
122
      return null;
123
    }
124
    return {
125
      provider: "giscus",
126
      lazy: config.lazy,
127
      giscus: {
128
        ...config.giscus,
129
        repo,
130
        repoId,
131
        categoryId,
132
        category: config.giscus.category?.trim() ?? "",
133
        theme: {
134
          light: config.giscus.theme?.light?.trim() || "light",
135
          dark: config.giscus.theme?.dark?.trim() || "dark",
136
        },
137
        scriptUrl: config.giscus.scriptUrl?.trim(),
138
      },
139
    };
140
  }
141
  return null;
142
}

1
import type { CompassConfig } from "../types/compassConfig.ts";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
export const compassConfig: CompassConfig = withUserConfig("compass", {
5
  enable: true,
6
  title: "$t:compass",
7
  description: "$t:compassBanner",
8
});

1
import type { ContextMenuConfig } from "@/types/contextMenuConfig";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
/** Optional desktop context-menu enhancement. */
5
export const contextMenuConfig: ContextMenuConfig = withUserConfig(
6
  "contextMenu",
7
  {
8
    enable: true,
9
    actions: ["copySelection", "backToTop", "sharePageLink"],
10
  },
11
);

1
import type { DevicesConfig } from "@/types/devicesConfig";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
/**
5
 * 设备展示页行为与展示配置。
6
 *
7
 * 遵循「配置管行为，数据管内容」原则：
8
 * - enable：页面总开关；false 时导航入口同步隐藏，访问 /devices/ 跳转 404；
9
 * - categories：场景分类清单（数组顺序即页面顶部 Chips 顺序）；
10
 * - disabledIds：可选被禁用的设备 ID 列表；
11
 *
12
 * 注：设备的具体清单数据（设备名、品牌、规格、感受说明、图片等）请在 `src/data/devices.ts` 中维护。
13
 */
14
export const devicesConfig: DevicesConfig = withUserConfig("devices", {
15
  enable: true,
16
  title: "$t:devices",
17
  description: "$t:devicesBanner",
18
  categories: [
19
    {
20
      key: "desk",
21
      label: "Desk Setup",
22
      icon: "material-symbols:desktop-windows-outline-rounded",
23
      description: "Workstation & home office hardware",
24
    },
25
    {
26
      key: "mobile",
27
      label: "Mobile & EDC",
28
      icon: "material-symbols:phone-iphone",
29
      description: "Daily portable devices & smart gadgets",
30
    },
31
    {
32
      key: "audio",
33
      label: "Audio & Visual",
34
      icon: "material-symbols:headphones-rounded",
35
      description: "Headphones, speakers & monitoring gears",
36
    },
37
    {
38
      key: "peripheral",
39
      label: "Peripherals",
40
      icon: "material-symbols:keyboard-outline-rounded",
41
      description: "Keyboards, mice & desk accessories",
42
    },
43
  ],
44
  // disabledIds: [],
45
});

1
import type { ExpressiveCodeConfig } from "@/types/config";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
/**
5
 * Expressive Code 代码块主题（astro.config.mjs 与 setting-utils 消费）。
6
 * 类型见 src/types/config.ts。
7
 */
8
export const expressiveCodeConfig: ExpressiveCodeConfig = withUserConfig(
9
  "expressiveCode",
10
  {
11
    // Note: Some styles (such as background color) are being overridden, see the astro.config.mjs file.
12
    // 代码块跟随明暗模式切换深浅主题
13
    theme: "github-dark",
14
    lightTheme: "github-light",
15
    darkTheme: "github-dark",
16
  },
17
);

1
import type { FabConfig } from "@/types/fabConfig";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3

4
/**
5
 * 右下角悬浮控制流（FAB）导航配置。
6
 *
7
 * 【核心配置项】
8
 * - enable：是否开启悬浮操作栏；
9
 * - align："start"（靠左）| "end"（靠右，默认）；
10
 * - size："small" | "regular"（默认）| "large"；
11
 * - offset：右下角边距（支持 CSS 变量或具体像素）；
12
 * - items：操作按钮清单（按数组顺序渲染）：
13
 *   - type: "top" —— 平滑返回顶部按钮（滚过横幅后自动浮现）；
14
 *   - type: "toc" —— 悬浮文章目录面板（桌面端已有侧栏粘性 TOC，默认仅在 mobile/tablet 显示）；
15
 *   - type: "comment" —— 直达评论区按钮（评论系统关闭或文章关闭评论时零 DOM 产物）；
16
 *   - type: "home" —— 返回首页按钮（onlySubPages: true 表示仅在非首页展示）；
17
 *   - devices：受控设备矩阵（"mobile" | "tablet" | "desktop"），省略表示全设备生效；
18
 *   - pages：页面范围过滤（如 ["post"]）。
19
 *
20
 * 架构规范见 docs/fab-system.md。
21
 */
22
export const fabConfig: FabConfig = withUserConfig("fab", {
23
  enable: true,
24
  align: "end",
25
  size: "regular",
26
  offset: {
27
    bottom: "var(--m3e-space-8)",
28
    right: "var(--m3e-space-6)",
29
  },
30
  items: [
31
    {
32
      type: "top",
33
      enable: true,
34
      devices: ["mobile", "tablet", "desktop"],
35
    },
36
    {
37
      type: "toc",
38
      enable: true,
39
      devices: ["mobile", "tablet"],
40
      pages: ["post"],
41
      depth: 3,
42
      closeOnSelect: true,
43
    },
44
    {
45
      type: "comment",
46
      enable: true,
47
      devices: ["mobile", "tablet"],
48
      pages: ["post"],
49
    },
50
    {
51
      type: "home",
52
      enable: true,
53
      devices: ["mobile", "tablet"],
54
      onlySubPages: true,
55
    },
56
  ],
57
});

1
import type { FontConfig, ResolvedFontOptions } from "../types/fontConfig.ts";
2
import { withUserConfig } from "../utils/config-overlay.ts";
3
import { resolveFontOptions as resolve } from "../utils/font-options.ts";
4

5
/**
6
 * ─────────────────────────────────────────────────────────────────────────────
7
 *  Shirone 全站字体配置指南
8
 * ─────────────────────────────────────────────────────────────────────────────
9
 *
10
 * 博客的字体分为 3 种角色（Role），每个角色各司其职：
11
 *  1. `body`：西文与默认基础正文字体（英文字母、数字、基础标点）
12
 *  2. `cjk` ：中日韩字体（汉字、日文平假名/片假名、韩文）
13
 *  3. `mono`：等宽代码字体（文章代码块、行内代码、终端输出）
14
 *
15
 * ─────────────────────────────────────────────────────────────────────────────
16
 * 【常见修改场景】
17
 * ─────────────────────────────────────────────────────────────────────────────
18
 * 场景 A：完全使用系统默认字体（零字体打包，极速加载，最省流量）
19
 *   - 将 `mode` 设置为 `"system"`，并将 `fontFamilies` 设为空数组 `[]`。
20
 *
21
 * 场景 B：更换本地中文字体或英文字体（.woff2 文件）
22
 *   1. 准备你的 `.woff2` 字体文件，放入项目 `src/assets/fonts/` 目录下；
23
 *   2. 找到对应角色的配置（如 `role: "cjk"` 或 `role: "body"`）；
24
 *   3. 设置 `source: "local"`，并在 `file` 中填入你的字体路径（例如 `"src/assets/fonts/MyFont.woff2"`）；
25
 *   4. 将 `family` 设为该字体的真实族名称。
26
 *
27
 * 场景 C：使用 npm 的 Fontsource 字体包
28
 *   1. 安装字体包（如 `pnpm.cmd add @fontsource/inter`）；
29
 *   2. 设置 `source: "fontsource"`，并在 `file` 中填入对应的 CSS 路径（如 `"@fontsource/inter/400.css"`）；
30
 *   3. 将 `family` 设为对应的字体名称（如 `"Inter"`）。
31
 *
32
 * ─────────────────────────────────────────────────────────────────────────────
33
 * 【修改后的验证命令】
34
 *   在终端依次执行：
35
 *   1. `npx.cmd astro check`  -> 校验配置与页面语法
36
 *   2. `pnpm.cmd build`        -> 执行生产构建与字体打包
37
 *   3. `pnpm.cmd fonts:check`  -> 校验字体格式与体积预算
38
 * ─────────────────────────────────────────────────────────────────────────────
39
 */
40
export const fontConfig: FontConfig = withUserConfig("font", {
41
  /**
42
   * 构建模式：
43
   * - `"custom"`: 启用自定义字体（加载下方 fontFamilies 中配置的字体）
44
   * - `"system"`: 纯系统字体模式（不打包任何自定义字体文件，完全依赖访客设备）
45
   */
46
  mode: "custom",
47

48
  /**
49
   * 字体清单列表（按需配置 body、cjk、mono 角色）
50
   */
51
  fontFamilies: [
52
    // ---------------------------------------------------------------------
53
    // 1. 正文字体（现代几何圆润西文字体 Outfit，与 M3E 大圆角及悠哉圆体绝配）
54
    // ---------------------------------------------------------------------
55
    {
56
      id: "outfit-body",
57
      family: "Outfit",
58
      role: "body",
59
      source: "fontsource",
60
      variants: [
61
        {
62
          file: "@fontsource/outfit/400.css",
63
          weight: 400,
64
          style: "normal",
65
        },
66
        {
67
          file: "@fontsource/outfit/500.css",
68
          weight: 500,
69
          style: "normal",
70
        },
71
        {
72
          file: "@fontsource/outfit/700.css",
73
          weight: 700,
74
          style: "normal",
75
        },
76
      ],
77
      fallback: ["ui-sans-serif", "system-ui", "sans-serif"],
78
      display: "swap",
79
      preload: false,
80
    },
81

82
    // ---------------------------------------------------------------------
83
    // 2. 中文 / 日文 CJK 字体（悠哉圆体 Yozai Medium，全量简繁中日韩 100% 覆盖）
84
    // ---------------------------------------------------------------------
85
    {
86
      id: "yozai-cjk",
87
      family: "Yozai Medium",
88
      role: "cjk",
89
      source: "local",
90
      variants: [
91
        {
92
          file: "src/assets/fonts/Yozai-Medium.ttf",
93
          weight: 500,
94
          style: "normal",
95
        },
96
      ],
97
      fallback: ["system-ui", "sans-serif"],
98
      display: "swap",
99
      preload: false,
100
    },
101

102
    // ---------------------------------------------------------------------
103
    // 3. 代码等宽字体（渲染代码块与终端文本，对应 CSS 变量 --font-mono）
104
    // ---------------------------------------------------------------------
105
    {
106
      id: "jetbrains-mono",
107
      family: "JetBrains Mono",
108
      role: "mono",
109
      source: "fontsource",
110
      variants: [
111
        {
112
          file: "@fontsource-variable/jetbrains-mono/index.css",
113
          weight: "100 800",
114
          style: "normal",
115
        },
116
        {
117
          file: "@fontsource-variable/jetbrains-mono/wght-italic.css",
118
          weight: "100 800",
119
          style: "italic",
120
        },
121
      ],
122
      fallback: [
123
        "ui-monospace",
124
        "SFMono-Regular",
125
        "Menlo",
126
        "Monaco",
127
        "Consolas",
128
        "monospace",
129
      ],
130
      display: "swap",
131
      preload: false,
132
    },
133
  ],
134

135
  /**
136
   * 字体子集化配置（生产构建时自动从文章、i18n、配置及 Meting 歌曲中提取字符，生成极速精简版 .woff2）
137
   * - Dev 开发环境：自动加载完整原字体，任意输入新汉字实时可见，极速 HMR 零等待；
138
   * - Build 生产构建：自动执行子集裁剪，将几十兆大字体压缩为几百 KB 的专属子集，秒开加载。
139
   */
140
  subsetting: {
141
    enable: true, // 启用自动化子集裁剪
142
    includeContent: true, // 扫描 src/content/ 下所有文章
143
    includeI18n: true, // 扫描全部 10 种语言词典
144
    includeConfig: true, // 扫描站点配置与导航
145
    includeCommon: true, // 包含常用标点与基础字符
146
    allowRemoteText: true, // 允许抓取 Meting 云端歌单曲目文本参与字形提取
147
  },
148

149
  /**
150
   * 字体打包体积预算限制（子集化后通常仅 300KB ~ 1MB）
151
   */
152
  budget: {
153
    maxTotalBytes: 6 * 1024 * 1024, // 全站引用自定义字体总大小上限：6MB
154
    maxFamilyBytes: 4 * 1024 * 1024, // 单个字体族文件大小上限：4MB
155
  },
156
});
157

158
/** 经过校验与标准化处理后的字体配置对象，由 Astro 模板与 CSS 消费 */
159
export const resolvedFontOptions: ResolvedFontOptions = resolve(fontConfig);
160

161
/** 字体配置解析与校验函数 */
162
export const resolveFontOptions: (config: FontConfig) => ResolvedFontOptions =
163
  resolve;