04-站点配置

本项目的配置分散在 6 个文件，本文逐一给出参数表。

1. src/site.config.ts 顶部导出的类型

改配置前先认识这三个类型（源码第 1–22 行）：

export interface SocialLink {
  platform: string   // 平台标识，见#2.9 支持列表
  url: string        // 链接地址
}

export interface FriendLinkRaw {
  url: string        // 必填，无协议会自动补 https://
  name?: string      // 可选，缺省取域名
  desc?: string      // 可选，缺省取域名
  icon?: string      // 可选，以 /friends/ 开头的 public 路径
}

export interface MusicTrack {
  title: string      // 必填，歌曲标题
  src: string        // 必填，public/ 下的静态路径（以 / 开头）或完整 http(s) URL
  cover?: string     // 可选，留空时按钮显示音符图标或从音频元数据提取
}

2. siteConfig 字段逐项说明

使用方式

siteConfig 是一个 export const 普通对象，不是 defineConfig 包装的。它被 astro.config.mjs（构建期读取 URL 与默认语言）和大量组件 import 使用。

改动后需要重启 dev server（astro.config.mjs 在启动时读取它）。纯组件消费的字段在 HMR 下可直接生效。

2.1 url — 站点地址

影响范围（改错了会连带出问题，请逐项检查）：

尾斜杠

src/pages/rss.xml.ts:8 确实会 site.replace(/\/+$/, '') 去尾部斜杠，但 canonical 的 new URL(Astro.url.pathname, Astro.site) 在 src/layouts/BaseLayout.astro:36，依赖标准 URL 解析。建议不要在 url 末尾加 /。

2.2 站点信息三件套

description 身兼两职：既是 SEO 描述，又是首页名片上作者名下方的那行简介。想分开，需在 ProfileCard.astro 里改用独立字段。

2.3 avatar / logo

两者都以 / 开头，指向 public/ 下的文件。换图只需替换 public/avatar.webp 与 public/logo.webp，无需改配置。

BaseLayout 的 <link rel="icon" type="image/webp" href="/logo.webp"> 是硬编码的 /logo.webp，不是 siteConfig.logo。若改 logo 路径，favicon 也要同步改 BaseLayout.astro。

2.4 author

用途：页脚版权署名、首页名片用户名、JSON-LD author.name、文章页版权块的 {author}、ProfileCard 头像 alt。

2.5 defaultLang — 默认语言

影响范围：

详见 07-页面与路由.md#5。

非法值直接报错

site.config.ts 末尾会调用 validateSiteConfig(siteConfig)（实现见 src/lib/siteConfigGuard.ts）：defaultLang 不属于 zh / ja / en 时抛出 Error，dev 启动与构建都会立即中断，不再依赖 as 强转静默通过。提示为英文（示例：`defaultLang` must be one of "zh" / "ja" / "en", received "fr".），源码中每条英文提示上方都紧邻一行中文译注。

2.6 defaultTheme — 默认主题

渲染到 <html data-default-theme="…">，由 stores/theme.ts 的 defaultMode() 读取。详见 03-主题与样式定制.md#6。

2.7 postsPerPage — 首页每页文章数

消费者：

改小这个值会新增大量页面

postsPerPage 从 10 改成 5，文章数 100 时会从 10 页变成 20 页，构建时间近似线性增长。

2.8 socials — 社交按钮

示例：

socials: [
  { platform: 'github',   url: 'https://github.com/yourname' },
  { platform: 'twitter',  url: 'https://twitter.com/yourname' },
  { platform: 'email',    url: 'mailto:you@example.com' },
  { platform: 'rss',      url: '/rss.xml' },     // 站内路径，不加 target=_blank
  { platform: 'bilibili', url: 'https://space.bilibili.com/xxx' },  // 未内置，用通用图标 + 主题色
] as SocialLink[],

平台名文本：由 platform 首字母大写生成（github → Github），用作按钮的 aria-label / title（按钮为 42×42 纯图标方块、贴在名片正下方）。想改提示文案，需要在 ProfileCard.astro 中改用固定映射或增加 label 字段。

支持列表的 platform 匹配是大小写不敏感的（内部 toLowerCase()）。

2.9 statsScript — 统计插件

关键行为：统计脚本仅在构建产物（生产环境）中注入。BaseLayout.astro 的条件是：

data-stats-script={(siteConfig.statsScript && import.meta.env.PROD ? siteConfig.statsScript : undefined)}

以及

{siteConfig.statsScript && import.meta.env.PROD && <script>import '@/stats/client'</script>}

挂载点的渲染条件：只有 Boolean(siteConfig.statsScript)，不带 PROD 判断（ProfileCard.astro:40、PostCard.astro:28、PostPage.astro:40）。因此：

也就是说 dev 下能看到 PV/UV 的位置，但数字永远是 -，也不会发出任何统计请求。要验证真实数字必须 pnpm build && pnpm preview。只有把 statsScript 留空（''）时挂载点才完全不渲染。

默认是测试插件。

'random-visitor' 会显示随机数字，上线前请改成正式插件或留空。

详细契约见 08-插件系统.md#3。

2.10 friends — 友链

示例：

friends: [
  { url: 'https://astro.build', name: 'Astro', desc: 'The web framework for content-driven websites', icon: '/friends/astro.webp' },
  { url: 'example.org',        name: '示例站' },                    // 自动补 https://，无图标
  { url: 'https://foo.dev' },                                      // 名称/描述都取域名 foo.dev
] as FriendLinkRaw[],

2.11 commentScript — 评论插件

启用后还需编辑 src/comments/utterances.ts 的 config.repo 填写 GitHub 仓库，否则适配器会抛错并隐藏整个评论区。

详细契约见 08-插件系统.md#2。

2.12 autoUpdatePostUpdated — 自动写 updated

为什么默认关闭？

该功能会在构建时改写你的 markdown 源文件。若你习惯「先 build 再 commit」，开启后会把时间戳一起提交；若你在 CI 上构建，还可能因只读文件系统或权限导致构建失败。建议本地按需开启。

相关注意点（更新说明.md 原文提示）：

• pnpm format-post-meta（元数据排序）仍是手动执行，建议先排版再构建；
• 建议先 pnpm build 再 git commit，让 slug/updated 的改动一次性提交完。

2.13 musicPlayer — 右下角磁铁音乐播放器

playlist 为空时的自动扫描规则：

显式指定示例：

musicPlayer: {
  enabled: true,
  playlist: [
    { title: '预言 Prophecy', src: '/music/预言 Prophecy.flac', cover: '/music/prophecy-cover.webp' },
    { title: '闪亮',           src: '/music/闪亮.flac' },   // 封面从元数据自动提取
    { title: '原色',           src: '/music/原色.flac' },
  ] as MusicTrack[],
},

加歌最省事的做法：

直接把音频文件丢进 public/music/，保持 playlist: []，重新构建即可。标题就是文件名（所以文件名即显示名）。

2.14 nav — 顶栏导航

SiteHeader.astro 按数组顺序渲染顶栏项；首页 / 固定第一位、不可移除，不要写进数组（写了也会被过滤）。数组去重，未在组件 NAV_DEFS 注册表登记的 path 会被忽略（新增自定义页面需先在 NAV_DEFS 登记词条 key 与图标）。空数组 [] 则顶栏只剩首页一项。缺失时回退为空（仅首页）并警告：nav 被删除或写成非字符串数组时，src/lib/siteConfigGuard.ts 的 validateSiteConfig() 会输出英文 console.warn（源码中附中文译注），顶栏按空数组渲染，构建不会中断。详见 02-组件说明.md#31-siteheaderastro。

2.15 pet — 左下角宠物挂件

pet: {
  enabled: true,
},

关闭方式：把 enabled 改为 false，Pet.astro 即不输出任何 DOM（是「不渲染」而非「隐藏」），ProfileCard.astro 里那颗唤回按钮也不会渲染。

开启后多出的交互（细节见 02-组件说明.md#35-petastro）：

与 nav / musicPlayer 不同，组件读取用的是可选链 siteConfig.pet?.enabled === true，所以整个 pet 字段缺失也不会报错，只是按关闭处理；validatePet() 会在这种「缺失或非布尔」的情况下输出英文 console.warn（提示宠物按关闭处理），不中断构建。字段说明、行为与关闭方法见 02-组件说明.md#35-petastro。

3. astro.config.mjs 参数表

export default defineConfig({
  site,                                        // 来自 siteConfig.url
  server:  { host: '::' },                     // dev 监听所有网卡（IPv6 通配）
  preview: { host: '::' },                     // preview 同上
  build:   { inlineStylesheets: 'always' },    // 所有 CSS 内联进 HTML
  markdown: { ... },                           // 见#3.2
  integrations: [ swup({...}), sitemap() ],    // 见#3.3
  vite: { ... },                               // 见#3.4
})

3.1 顶层选项

3.2 markdown 配置

markdown: {
  syntaxHighlight: false,        // 关闭 Astro 内置 shiki，改用自定义 Prism 构建期高亮
  processor: unified({ ... }),
}

remark 插件链（按顺序）：

rehype 插件链（按顺序）：

顺序敏感：rehypeKatex 必须在 rehypeSlug 之前（KaTeX 会生成带 id 的元素）；rehypeRelativeLinks 必须在 rehypeImages 之后（前者需要处理后者生成的 href）。调整顺序可能破坏功能。

3.3 integrations — Swup 与 Sitemap

Swup 参数：

ignore 回调规则：

ignore: (url) => {
  if (url.includes('#')) return true                       // 含 # 的一律跳过 Swup：同页锚点由 PostPage、跨页锚点由 BaseLayout 点击委托接管，都不会原生闪现
  const path = new URL(url, 'https://example.com').pathname
  if (/\.(xml|txt|json|pdf|zip|png|jpe?g|webp|gif|svg|ico|avif|woff2?|ttf|eot)$/i.test(path)) return true
  if (/^\/(pagefind|fonts|images)\//.test(path)) return true
  return false
}

Sitemap：sitemap() 无参数，生成 /sitemap-index.xml 与 /sitemap-0.xml。SiteFooter 的 Sitemap 链接硬编码为 /sitemap-index.xml。

3.4 vite 配置

Vite 插件（构建期数据生成）：

optimizeDeps.include：

[
  'photoswipe', 'photoswipe/lightbox', 'astro/virtual-modules/transitions-*.js',
  // Swup 的 Astro 客户端模块：按需拆成 8 个入口，全部预打包
  '@swup/astro/idle', '@swup/astro/serialise',
  '@swup/astro/client/Swup', '@swup/astro/client/SwupA11yPlugin',
  '@swup/astro/client/SwupHeadPlugin', '@swup/astro/client/SwupProgressPlugin',
  '@swup/astro/client/SwupPreloadPlugin', '@swup/astro/client/SwupScriptsPlugin',
]

预打包这些依赖，避免 dev 首次访问文章页（PhotoSwipe）或首次触发换页（Swup 各插件）时出现「新依赖发现 → 重新预构建 → 页面刷新」。Swup 那 8 项是逐插件列出的，@swup/astro 升级后若入口文件名变化需同步这一份清单。

build 参数：

pure: ['console.log'] 的副作用：

如果你在客户端脚本里用 console.log 调试，生产构建会被移除（console.warn / console.error 保留）。调试请用 pnpm dev。

4. src/content.config.ts — 文章 Schema

const posts = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/posts' }),
  schema: z.object({ ... }),
})
export const collections = { posts }

normalizeList 的行为：（源码第 5–18 行）

// 输入 "a, b, a" 或 ['a','b','a']  →  输出 ['a','b']
// 规则：按逗号拆分（字符串时）→ trim → 跳过空值 → 按 toLowerCase() 去重 → 保留原始大小写

所以 tags: [Markdown, markdown] 只会保留第一个 Markdown。

加自定义字段的示例：（例如加一个 cover 封面图字段）：

// src/content.config.ts
schema: z.object({
  // ...原有字段
  cover: z.string().optional(),
}),

然后 Post 类型会自动带上 post.data.cover。别忘了同步 scripts/format-post-meta.js 的 ORDER / LAST 数组，否则 pnpm format-post-meta 会把它排到末尾。

5. tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist", "node_modules"],
  "compilerOptions": {
    "baseUrl": ".",
    "resolveJsonModule": true,
    "paths": { "@/*": ["src/*"] }
  }
}

i18n key 的类型安全（T13）

• src/i18n/ui.ts 从 zh.json 递归派生出点路径联合类型 MessageKey（深度上限 5 层，当前语言包最深 3 层），t(key: MessageKey, params?) 因此能在 pnpm check / pnpm type-check 阶段拦住拼错的键（例如 t('nav.hom') 直接编译报错）。
• 为让 TS 推导出字面量键，src/env.d.ts 不再 declare module '*.json'（那条声明会把 JSON import 统一成 Record<string, any>）；全项目只有 i18n/ui.ts import JSON。
• 取词未命中时：dev 环境在服务端日志打印 [i18n] missing message: <key> (<lang>.json)，生产环境保持静默回退（显示 key 原文），行为与之前一致（构建产物里 dev 告警分支已被消除）。
• 三份语言包键集合一致性由 pnpm check-i18n（scripts/check-i18n.js）手动校验，不一致时 exit 1 并列出缺失 / 多出的键。

加新别名：

"paths": {
  "@/*": ["src/*"],
  "@components/*": ["src/components/*"]
}

astro.config.mjs 不读取 tsconfig.json 的 paths（它是被 Vite 处理的），所以在 astro.config.mjs 里 import 必须用带扩展名的相对路径，例如 ./src/site.config.ts、./src/lib/md/rehypeCodeBlock.ts（源码确实这么写）。

6. biome.json

命令对应：

7. pagefind.yml

exclude_selectors:
  - ".katex"          # KaTeX 渲染出的公式排版节点
  - ".katex-display"  # 块级公式
  - ".code-header"    # 代码块头部（语言标签 + 复制按钮，不应进索引）
  - ".md-toc"         # markdown 内的目录块

7.1 搜索索引的范围控制

常见扩展示例：

exclude_selectors:
  - ".katex"
  - ".katex-display"
  - ".code-header"
  - ".md-toc"
  - ".img-frame"        # 图片
  - ".md-container"     # 提示容器整块

加了新选择器要重新构建：

pagefind.yml 只在 postbuild.js 里被读取（pagefind --site dist 会读项目根的 pagefind.yml），改动后必须 pnpm build。

8. 配置文件改动影响速查