站点与外观配置
Mizuki 主题将站点身份信息（标题、语言、时区、站点 URL）与外观行为（主题色、壁纸模式、横幅轮播、字体、页面缩放、文章列表布局、超宽屏布局、标签样式）集中在 src/config/ 下的 TypeScript 模块中，并通过 src/config/index.ts 统一导出、可选地与 src/config/overrides/ 覆盖文件深合并后供全站消费。
目的与范围
本页覆盖以下内容：
- 站点核心配置
src/config/siteConfig.ts：标题、副标题、siteURL、siteStartDate、timeZone、lang、themeColor、featurePages、navbarTitle、pageScaling、font、postListLayout、ultrawidePostLayout、tagStyle、wallpaperMode、banner等字段的确切含义与默认值。 - 配置体系与覆盖机制：
src/config/index.ts作为统一导出入口，如何通过withOverride（overrideLoader.ts）+deepMerge把overrides/目录中的同名覆盖文件合并进上游默认值。 - 派生常量
SITE_LANG的来源与其对评论配置的联动约束。
以下内容属于兄弟页面，本页仅引用不展开：
- 导航栏菜单与多级下拉菜单：见
src/config/navBarConfig.ts（navBarConfig）。 - 全屏壁纸模式的图片源/透明度/模糊细节：见
src/config/backgroundWallpaper.ts（fullscreenWallpaperConfig）。 - 侧边栏组件布局：见
src/config/sidebarConfig.ts（sidebarLayoutConfig）。 - 页脚自定义 HTML：见
src/config/footerConfig.ts（footerConfig）。 - 番剧/Bangumi/Bilibili 数据抓取流程：本页仅记录其在
siteConfig中的开关字段。
概述
Mizuki 是一个 Astro 博客主题，其设计原则是「配置即代码」：所有站点与外观定制不依赖后台界面，而是直接编辑 src/config/ 下的类型安全 TypeScript 模块。这样做的好处是：
- 类型约束：所有配置结构由
src/types/config.ts中的 TypeScript 接口（如SiteConfig）约束，字段拼错会在构建期报错。 - 模块化拆分：配置按职责拆分为约 20 个模块（站点核心、壁纸、导航、资料、评论、音乐、特效等），避免单文件膨胀。
- 上游/内容分离：各配置文件保存上游默认值，
src/config/index.ts在导出前把src/config/overrides/下的同名覆盖文件深合并进来，使内容仓库可以独立携带配置差异（由sync-content从内容仓库的overrides/同步）。
典型的使用场景：克隆主题后，用户至少需要把 siteConfig.siteURL 替换为自己部署后的公开网址（以斜杠结尾），再按需调整 themeColor.hue、wallpaperMode.defaultMode、banner.src 等外观字段。
架构
配置体系自下而上分为四层：默认值模块 → 覆盖层 → 统一导出入口 → 消费方。
架构要点（均可在源码中验证）：
src/config/siteConfig.ts持有站点核心与外观默认值，导出siteConfig: SiteConfig对象，类型来自src/types/config.ts。src/config/index.ts以withOverride("siteConfig", siteDefaults)的形式包装每个默认导出（见 src/config/index.ts），并把SITE_LANG从合并后的siteConfig.lang派生。- 覆盖合并公式（
index.ts头部注释明确给出）：最终配置 = deepMerge(上游默认配置, overrides/<导出名>.ts 的 default 导出)。覆盖目录不存在时，所有配置等同上游默认值。 - 消费方包括 Astro 组件（三种引用方式
@/config、../config、src/config均解析到index.ts）、astro.config.mjs（从./src/config/index.ts引入siteConfig、permalinkConfig等用于站点元数据与路由），以及构建脚本。直接 import 某个配置文件会绕过覆盖合并，因此官方约定「请始终从本入口读取配置」。
wallpaper 与外观相关模块在 index.ts 中的注册方式：
1import { fullscreenWallpaperConfig as fullscreenWallpaperDefaults } from "./backgroundWallpaper";
2import { withOverride } from "./overrideLoader";
3import { siteConfig as siteDefaults } from "./siteConfig";
4
5// ─── 站点核心 ───────────────────────────────────────────────
6export const siteConfig = withOverride("siteConfig", siteDefaults);
7
8// SITE_LANG 从合并后的站点配置派生，覆盖 siteConfig.lang 后会一并生效。
9// 注意：commentConfig.ts 在模块顶层引用了 siteConfig.ts 里的同名常量填充评论
10// 语言，若覆盖了 siteConfig.lang，需要同时覆盖 commentConfig 的对应字段。
11export const SITE_LANG = siteConfig.lang;
12
13// ─── 外观与壁纸 ─────────────────────────────────────────────
14export const fullscreenWallpaperConfig = withOverride(
15 "fullscreenWallpaperConfig",
16 fullscreenWallpaperDefaults,
17);Source: src/config/index.ts
这段代码揭示了两个关键设计意图：其一，withOverride 以导出名字符串作为覆盖文件的查找键（overrides/siteConfig.ts 对应导出名 siteConfig）；其二，SITE_LANG 不再是一个独立可覆盖的常量，而是合并后配置的派生值，但注释同时警告了 commentConfig.ts 在模块顶层静态引用旧常量带来的联动陷阱（详见「失败模式与边界情况」）。
实现详解：siteConfig 字段逐一解析
siteConfig.ts 文件开头先定义语言常量，再导出整个 SiteConfig 对象：
1import type { SiteConfig } from "../types/config";
2
3// 定义站点语言
4const SITE_LANG = "en"; // 语言代码，例如：'en', 'zh_CN', 'ja' 等。
5
6export const siteConfig: SiteConfig = {
7 title: "Mizuki",
8 subtitle: "One demo website",
9 siteURL: "https://mizuki.mysqil.com/", // 请替换为你的站点URL，以斜杠结尾
10 siteStartDate: "2025-01-01", // 站点开始运行日期，用于站点统计组件计算运行天数
11 timeZone: "Asia/Shanghai", // 文章日期使用的 IANA 时区，可改为 Asia/Tokyo、Europe/Berlin 等
12
13 lang: SITE_LANG,
14
15 themeColor: {
16 hue: 240, // 主题色的默认色相，范围从 0 到 360。例如：红色：0，青色：200，蓝绿色：250，粉色：345
17 fixed: false, // 对访问者隐藏主题色选择器
18 },Source: src/config/siteConfig.ts
注意这里存在两个 SITE_LANG：文件内的模块私有常量（默认 "en"），以及 index.ts 从合并后配置派生并导出的 SITE_LANG。前者只在 siteConfig.ts 内部（以及被 commentConfig.ts 顶层静态引用）使用；后者才是全站应消费的版本。
站点身份字段
title/subtitle：站点标题与副标题，用于页面<title>、SEO 与首页展示。siteURL：部署前必改字段，必须以斜杠结尾（如https://mizuki.mysqil.com/）。README 明确要求「部署前，请在src/config/siteConfig.ts中更新siteURL」。siteStartDate：站点开始运行日期（"2025-01-01"），供站点统计组件计算运行天数。timeZone：文章日期使用的 IANA 时区（默认Asia/Shanghai），可改为Asia/Tokyo、Europe/Berlin等。lang：站点语言代码（'en'、'zh_CN'、'ja'等）。
themeColor：主题色
1themeColor: {
2 hue: 240,
3 fixed: false,
4},hue（默认240）：主题色的默认色相，范围 0–360。注释给出了直观参照：红色 0、青色 200、蓝绿色 250、粉色 345。主题采用 HSL 色相驱动的配色方案，改一个数值即可全局换色。fixed（默认false）：设为true时对访问者隐藏主题色选择器，锁定站点配色。
featurePages：特色页面开关
1// 特色页面开关配置（关闭未使用的页面有助于提升 SEO，关闭后请记得在 navbarConfig 中移除对应链接）
2featurePages: {
3 anime: true, // 番剧页面开关
4 diary: true, // 日记页面开关
5 friends: true, // 友链页面开关
6 projects: true, // 项目页面开关
7 skills: true, // 技能页面开关
8 timeline: true, // 时间线页面开关
9 albums: true, // 相册页面开关
10 devices: true, // 设备页面开关
11 aiTools: true, // AI 工具页面开关
12},Source: src/config/siteConfig.ts
九个布尔开关分别控制番剧、日记、友链、项目、技能、时间线、相册、设备、AI 工具页面的生成。设计意图写在注释里：关闭未使用的页面有助于提升 SEO（避免生成大量空壳路由），且关闭后需同步在 navBarConfig 中移除对应链接，否则会出现死链。
navbarTitle：顶栏标题
1// 顶栏标题配置
2navbarTitle: {
3 // 显示模式："text-icon" 显示图标+文本，"logo" 仅显示Logo
4 mode: "text-icon",
5 // 顶栏标题文本
6 text: "MizukiUI",
7 // 顶栏标题图标路径，默认使用 public/assets/home/home.webp
8 icon: "assets/home/home.webp",
9 // 网站Logo图片路径
10 logo: "assets/home/default-logo.webp",
11},Source: src/config/siteConfig.ts
mode 是二选一的联合类型："text-icon" 同时展示图标与文本，"logo" 只展示 Logo 图片。icon 与 logo 都是相对 public/ 的资源路径。
pageScaling 与 ultrawidePostLayout：两套互不冲突的宽度方案
这是 siteConfig 中最值得注意的一组「易混淆但被刻意区分」的配置：
1// 旧版页面自动缩放配置。默认关闭，页面尺寸优先交由响应式布局处理。
2pageScaling: {
3 enable: false, // 兼容旧站点的可选缩放；不建议通过根字号控制整体布局
4 targetWidth: 2000, // 目标宽度，低于此宽度时开始缩放
5},Source: src/config/siteConfig.ts
1// 文章页超宽屏布局配置
2// 在 2K/4K 视口下扩展文章容器、侧栏与正文阅读轨道；1920px 以下不生效。
3// 与 pageScaling 互不影响：断点按 CSS 视口判断，且 pageScaling 在 2000px 以上是空操作。
4ultrawidePostLayout: {
5 enable: true, // 访客未手动切换时的初始状态
6 allowSwitch: true, // 是否在设置面板中显示开关
7},Source: src/config/siteConfig.ts
设计意图：pageScaling 是遗留兼容机制（默认关闭，通过根字号缩放整页，官方不推荐），仅在视口宽度低于 targetWidth: 2000 时介入；ultrawidePostLayout 则是面向 2K/4K 的现代增强，在 1920px 以下不生效。两者作用区间天然错开——pageScaling 在 2000px 以上是空操作——因此注释明确声明「互不影响」。ultrawidePostLayout.allowSwitch 决定访客是否能在设置面板中手动切换该布局。
font：字体加载策略
1font: {
2 // custom 保持 ZenMaruGothic -> Loli -> 系统字体的显示顺序；system 不加载任何自定义字体
3 mode: "custom",
4},Source: src/config/siteConfig.ts
"custom" 模式按 ZenMaruGothic → Loli → 系统字体 的回退顺序加载；"system" 则完全不加载自定义字体，节省字体请求体积。
postListLayout 与 tagStyle：列表外观
1// 文章列表布局配置
2postListLayout: {
3 // 默认布局模式："list" 列表模式（单列布局），"grid" 网格模式（双列布局）
4 // 注意：如果侧边栏配置启用了"both"双侧边栏，则无法使用文章列表"grid"网格（双列）布局
5 defaultMode: "list",
6 // 是否启用布局切换功能
7 enable: true,
8 // 是否允许用户切换布局
9 allowSwitch: true,
10 // 文章列表页分类导航条配置
11 categoryBar: {
12 enable: true, // 是否在文章列表页显示分类导航条
13 },
14},Source: src/config/siteConfig.ts
1// 标签样式配置
2tagStyle: {
3 // 是否使用新样式（悬停高亮样式）还是旧样式（外框常亮样式）
4 useNewStyle: false,
5},Source: src/config/siteConfig.ts
defaultMode 支持 "list"（单列）与 "grid"（双列）。注释指出一个硬约束：若 sidebarLayoutConfig 启用了 "both" 双侧边栏，则 grid 双列布局不可用。enable 与 allowSwitch 是两层控制：前者是功能总开关，后者决定访客能否手动切换。
壁纸模式与横幅
wallpaperMode：整体布局方案
1// 壁纸模式配置
2wallpaperMode: {
3 // 默认壁纸模式：banner=顶部横幅，fullscreen=全屏壁纸，none=无壁纸
4 defaultMode: "banner",
5 // 整体布局方案切换按钮显示设置（默认："desktop"）
6 // "off" = 不显示
7 // "mobile" = 仅在移动端显示
8 // "desktop" = 仅在桌面端显示
9 // "both" = 在所有设备上显示
10 showModeSwitchOnMobile: "both",
11},Source: src/config/siteConfig.ts
defaultMode 三选一：banner（顶部横幅）、fullscreen（全屏壁纸）、none（无壁纸）。showModeSwitchOnMobile 控制布局切换按钮的显示范围（注释说明默认值为 "desktop"，示例配置显式设为 "both"），这是为移动端极窄屏幕保留的开关——切换按钮本身也占空间，因此允许按设备隐藏。
全屏壁纸模式下的图片源、轮播、透明度、模糊等细节配置位于独立模块 backgroundWallpaper.ts（导出名 fullscreenWallpaperConfig），本页不展开。
banner：顶部横幅与首页文案
1banner: {
2 // 支持单张图片或图片数组，当数组长度 > 1 时自动启用轮播
3 src: {
4 desktop: [
5 "/assets/desktop-banner/1.webp",
6 "/assets/desktop-banner/2.webp",
7 "/assets/desktop-banner/3.webp",
8 "/assets/desktop-banner/4.webp",
9 ], // 桌面横幅图片
10 mobile: [
11 "/assets/mobile-banner/1.webp",
12 "/assets/mobile-banner/2.webp",
13 "/assets/mobile-banner/3.webp",
14 "/assets/mobile-banner/4.webp",
15 ], // 移动横幅图片
16 }, // 使用本地横幅图片
17
18 position: "center", // 等同于 object-position，仅支持 'top', 'center', 'bottom'。默认为 'center'
19
20 carousel: {
21 enable: true,
22 interval: 3,
23 switchable: true,
24 },Source: src/config/siteConfig.ts
设计意图：横幅按桌面/移动两组数组分别提供，数组长度大于 1 时自动升级为轮播，无需额外开关。position 映射到 CSS object-position，仅支持 'top' | 'center' | 'bottom' 三个取值。carousel.interval 单位为秒（示例 3 秒），switchable 允许访客手动切换轮播图。
横幅还内置波浪动画与外部图片 API：
1 waves: {
2 enable: true,
3 performanceMode: false,
4 mobileDisable: false,
5 switchable: true,
6 },
7
8 // PicFlow API支持(智能图片API)
9 imageApi: {
10 enable: false, // 启用图片API
11 url: "http://domain.com/api_v2.php?format=text&count=4", // API地址，返回每行一个图片链接的文本
12 },
13 // 这里需要使用PicFlow API的Text返回类型,所以我们需要format=text参数
14 // 项目地址:https://github.com/matsuzaka-yuki/PicFlow-API
15 // 请自行搭建APISource: src/config/siteConfig.ts
waves.performanceMode 与 waves.mobileDisable 提供了两档降级：前者牺牲效果换性能，后者直接在移动端禁用波浪。imageApi 默认关闭；启用后从 PicFlow API 拉取随机横幅，必须带 format=text 参数（服务端返回每行一个图片链接的纯文本），注释同时要求自行部署 PicFlow-API。
首页横幅文字（homeText）含标题、多条轮换副标题与打字机效果：
1 homeText: {
2 enable: true,
3 title: "わたしの部屋",
4 switchable: true,
5
6 subtitle: [
7 "特別なことはないけど、君がいると十分です",
8 "今でもあなたは私の光",
9 "君ってさ、知らないうちに私の毎日になってたよ",
10 "君と話すと、なんか毎日がちょっと楽しくなるんだ",
11 "今日はなんでもない日。でも、ちょっとだけいい日",
12 ],
13 typewriter: {
14 enable: true, // 启用副标题打字机效果
15
16 speed: 100, // 打字速度（毫秒）
17 deleteSpeed: 50, // 删除速度（毫秒）
18 pauseTime: 2000, // 完全显示后的暂停时间（毫秒）Source: src/config/siteConfig.ts
副标题是字符串数组，轮换展示；typewriter 的三个时间参数（打字 100ms、删除 50ms、停顿 2000ms）粒度足够细，可精确调节打字机节奏。
配置选项总表
siteConfig 主要字段一览（默认值取自源码）：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | "Mizuki" | 站点标题 |
subtitle | string | "One demo website" | 站点副标题 |
siteURL | string | "https://mizuki.mysqil.com/" | 站点 URL，部署前必改，以斜杠结尾 |
siteStartDate | string | "2025-01-01" | 站点起始日期，用于运行天数统计 |
timeZone | string | "Asia/Shanghai" | 文章日期的 IANA 时区 |
lang | string | "en" | 站点语言代码（en、zh_CN、ja 等） |
themeColor.hue | number | 240 | 主题色色相，0–360 |
themeColor.fixed | boolean | false | 隐藏访客主题色选择器 |
featurePages.* | object（9 个布尔） | 全 true | anime/diary/friends/projects/skills/timeline/albums/devices/aiTools 页面开关 |
navbarTitle.mode | "text-icon" | "logo" | "text-icon" | 顶栏标题显示模式 |
navbarTitle.text | string | "MizukiUI" | 顶栏标题文本 |
navbarTitle.icon | string | "assets/home/home.webp" | 顶栏标题图标路径 |
navbarTitle.logo | string | "assets/home/default-logo.webp" | 网站 Logo 路径 |
pageScaling.enable | boolean | false | 旧版整页缩放，默认关闭 |
pageScaling.targetWidth | number | 2000 | 低于此宽度开始缩放 |
font.mode | "custom" | "system" | "custom" | 自定义字体链 ZenMaruGothic→Loli→系统，或纯系统字体 |
postListLayout.defaultMode | "list" | "grid" | "list" | 文章列表默认布局 |
postListLayout.enable | boolean | true | 布局切换功能开关 |
postListLayout.allowSwitch | boolean | true | 是否允许访客切换布局 |
postListLayout.categoryBar.enable | boolean | true | 列表页分类导航条 |
ultrawidePostLayout.enable | boolean | true | 2K/4K 超宽屏布局初始状态 |
ultrawidePostLayout.allowSwitch | boolean | true | 设置面板中是否显示开关 |
tagStyle.useNewStyle | boolean | false | 新样式（悬停高亮）或旧样式（外框常亮） |
wallpaperMode.defaultMode | "banner" | "fullscreen" | "none" | "banner" | 默认壁纸模式 |
wallpaperMode.showModeSwitchOnMobile | "off" | "mobile" | "desktop" | "both" | "desktop"（示例为 "both"） | 布局切换按钮显示范围 |
banner.src.desktop / .mobile | string[] | 各 4 张 webp | 横幅图片数组，长度 > 1 自动轮播 |
banner.position | "top" | "center" | "bottom" | "center" | object-position 取值 |
banner.carousel.enable | boolean | true | 轮播开关 |
banner.carousel.interval | number | 3 | 轮播间隔（秒） |
banner.carousel.switchable | boolean | true | 访客可手动切换 |
banner.waves.enable | boolean | true | 波浪动画 |
banner.waves.performanceMode | boolean | false | 性能优先模式 |
banner.waves.mobileDisable | boolean | false | 移动端禁用波浪 |
banner.imageApi.enable | boolean | false | PicFlow 随机横幅 API |
banner.imageApi.url | string | "http://domain.com/api_v2.php?format=text&count=4" | API 地址（需 format=text） |
banner.homeText.enable | boolean | true | 首页横幅文字 |
banner.homeText.title | string | "わたしの部屋" | 横幅标题 |
banner.homeText.subtitle | string[] | 5 条日文短句 | 轮换副标题 |
banner.homeText.typewriter.enable | boolean | true | 打字机效果 |
banner.homeText.typewriter.speed | number | 100 | 打字速度（ms） |
banner.homeText.typewriter.deleteSpeed | number | 50 | 删除速度（ms） |
banner.homeText.typewriter.pauseTime | number | 2000 | 停顿时间（ms） |
另有与第三方数据源相关的字段：bangumi.userId / bangumi.fetchOnDev、bilibili.vmid / fetchOnDev / coverMirror / useWebp、anime.mode（"bangumi" | "local" | "bilibili"）、diaryApiUrl（留空使用静态数据）。
核心流程：配置如何变成页面
流程要点：
- 开发者编辑
src/config/siteConfig.ts中的默认值（或通过内容仓库的overrides/siteConfig.ts提供差异）。 withOverride("siteConfig", siteDefaults)在导出前尝试读取覆盖文件并deepMerge。index.ts导出合并后的siteConfig并派生SITE_LANG。- Astro 组件与
astro.config.mjs通过统一入口消费配置，渲染出顶栏标题、主题色、横幅轮播、列表布局等外观元素。
使用示例
最小定制：换站点身份
1export const siteConfig: SiteConfig = {
2 title: "Mizuki",
3 subtitle: "One demo website",
4 siteURL: "https://mizuki.mysqil.com/", // 请替换为你的站点URL，以斜杠结尾
5 siteStartDate: "2025-01-01",
6 timeZone: "Asia/Shanghai",
7 lang: SITE_LANG,
8 themeColor: {
9 hue: 240,
10 fixed: false,
11 },Source: src/config/siteConfig.ts
README 的快速开始明确要求：克隆后至少将 siteURL 替换为部署后的公开网址。title/subtitle/timeZone/lang 是其余最常改的身份字段。
进阶定制：多图轮播 + 外部图片 API
1src: {
2 desktop: [
3 "/assets/desktop-banner/1.webp",
4 "/assets/desktop-banner/2.webp",
5 "/assets/desktop-banner/3.webp",
6 "/assets/desktop-banner/4.webp",
7 ],
8 mobile: [
9 "/assets/mobile-banner/1.webp",
10 "/assets/mobile-banner/2.webp",
11 "/assets/mobile-banner/3.webp",
12 "/assets/mobile-banner/4.webp",
13 ],
14},
15position: "center",
16carousel: {
17 enable: true,
18 interval: 3,
19 switchable: true,
20},
21imageApi: {
22 enable: false,
23 url: "http://domain.com/api_v2.php?format=text&count=4",
24},Source: src/config/siteConfig.ts
示例展示了两种横幅来源的组合：本地多图自动轮播（数组长度 > 1 即轮播）与可选的 PicFlow 随机图片 API（启用后可完全替代本地图片，但必须使用 format=text 返回类型）。
失败模式、边界情况与并发
以下陷阱均在源码注释或 README 中有明确记载：
- 绕过覆盖合并：直接
import某个配置文件（如import { siteConfig } from "../config/siteConfig"）会拿到未合并覆盖的上游默认值。index.ts头部注释明确警告「请始终从本入口读取配置，直接 import 某个配置文件会绕过覆盖合并」。 lang覆盖的联动陷阱：commentConfig.ts在模块顶层静态引用了siteConfig.ts内的模块级SITE_LANG常量来填充评论语言。若通过 overrides 只覆盖siteConfig.lang，index.ts导出的SITE_LANG会更新，但评论语言不会跟随——需同时覆盖commentConfig的对应字段。这是模块顶层副作用（import 时机）导致的时序问题。- siteURL 格式：必须以斜杠结尾，否则基于它拼接的绝对 URL 会出错。
- grid 布局与双侧边栏互斥：
sidebarLayoutConfig启用"both"双侧边栏时，文章列表"grid"双列布局不可用（postListLayout注释中的硬约束）。 - featurePages 与 navBarConfig 需同步：关闭某特色页面后未在导航栏移除对应链接，将产生死链，同时注释提醒关闭未使用页面有利于 SEO。
- 凭证安全：
bilibili配置注释明确要求 SESSDATA 只能放在.env（本地）或 GitHub Secrets（远程构建），不可硬编码；若泄露需在 B 站客户端一键退登销毁凭证。 - pageScaling 与 ultrawidePostLayout 的区间隔离：两者断点按 CSS 视口判断，
pageScaling在 2000px 以上是空操作，因此互不影响——但若手动把targetWidth调得过高，可能与超宽屏布局产生叠加缩放，官方默认关闭pageScaling正是为此。
性能与运维要点
- 性能降级开关：
banner.waves.performanceMode、banner.waves.mobileDisable为低端设备与移动端提供逐级降级；font.mode: "system"可完全避免自定义字体网络请求。 - SEO 运维：
featurePages关闭未用页面可减少空路由；siteURL、timeZone直接影响 sitemap 与结构化数据的正确性。 - 开发态数据抓取：
bangumi.fetchOnDev/bilibili.fetchOnDev默认false，且 Bangumi 注释说明「获取前先执行pnpm build构建 json 文件」，避免开发服务器每次热更新都打外部 API。 - 覆盖目录同步：
overrides/由sync-content从内容仓库同步，不存在时所有配置等同上游默认值；细节见docs/CONTENT_SEPARATION.md（本页不展开）。
扩展点
- 新增外观配置字段：在
src/config/siteConfig.ts增加字段后，必须同步更新src/types/config.ts中SiteConfig接口（index.ts头部注释的硬性要求），否则类型检查失败。 - 新增配置模块：参照
backgroundWallpaper.ts的模式——导出默认配置对象，在index.ts中以withOverride("<导出名>", defaults)包装并导出，即可自动获得 overrides 覆盖能力。 - 配置文件索引维护：
index.ts头部维护了「导出名称 │ 文件 │ 说明」的注释表格，新增模块时需同步登记，保持文档与代码一致。
相关链接
- src/config/siteConfig.ts — 站点核心与外观默认配置
- src/config/index.ts — 统一导出入口与覆盖合并
- src/config/overrideLoader.ts —
withOverride实现 - src/config/deepMerge.ts — 深合并工具
- src/types/config.ts —
SiteConfig等全部类型定义 - astro.config.mjs — 消费
siteConfig的 Astro 配置 - README.md — 快速开始与部署要求（
siteURL必改项）