配置站点信息

项目有两个配置入口，它们服务于不同层级：

日常配置优先集中在 site.config.ts。页面组件和构建逻辑会读取这里的数据，不应在组件中重复写作者名称、域名或社交账号。

配置单元测试只检查非空文本、有效地址、正整数、派生行为和本地资源是否存在，不固定站点名称、个人文案、账号、导航内容、数量取值或 Giscus ID。正常修改这些配置时无需同步改写测试期望；只有新增配置结构或改变配置规则时才需要更新测试。

环境变量 ​

域名和部署路径由环境变量注入，不建议硬编码到 site.config.ts。

SITE_URL 不包含末尾 /。SITE_BASE 应同时保留开头和结尾的 /；未设置或设置为 / 时表示部署在域名根路径。

本地开发不要求 SITE_URL。需要检查生产输出时，项目已提供固定占位域名的命令：

pnpm build:local
pnpm preview

GitHub Pages workflow 在 .github/workflows/deploy.yml 中声明：

env:
  SITE_URL: https://${{ github.repository_owner }}.github.io
  SITE_BASE: /

如果仓库发布到项目子路径，需要把 SITE_BASE 改成 /<repository>/，并保证 Pages 的实际访问路径与之相同。

站点信息 ​

siteConfig.site 控制全站公共信息和输出路径。

图标配置 ​

Logo 与 favicon 文件保存在 src/public，配置值使用以 / 开头的公开路径。根目录的 bean-convex-concave-concept-v33.svg 是图标源文件，运行 pnpm generate:assets 会同步生成 logo.svg、三种 favicon 文件；构建时会自动拼接 SITE_BASE。

Feed 配置 ​

这些路径同时用于静态文件生成、页面 <head> 声明和站内 RSS 链接。

作者信息 ​

siteConfig.author 用于首页、文章信息和 Feed 作者信息。

动态页配置 ​

siteConfig.moment 集中控制 /moment 的个人区和滚动批次，不需要在每条动态中重复声明作者身份。

covers 至少提供一项，空路径会导致配置加载失败，重复路径会自动去重。每次进入 /moment 时页面随机选择一张，停留期间不会自行切换：

covers: ["/moments/cover.webp", "/moments/cover-spring.webp", "/moments/cover-night.webp"],

moment.avatar 是顶部个人区和未指定头像的动态共用的默认头像。当前配置显式使用 avatar: favicon.svg，也可以独立设置为 avatar: "/moments/avatar.webp"；省略或留空仍回退到站点图标。

需要发布动态时选择不同头像，可在同一配置中通过 avatars 为图片命名：

avatar: favicon.svg,
avatars: {
  default: favicon.svg,
  daily: "/moments/daily.webp",
  travel: "https://images.example.com/travel.webp",
},

动态文件的 frontmatter 填写 avatar: daily 即可选择 avatars.daily。省略 avatar 时继续使用 moment.avatar，顶部个人区始终使用默认头像，不随单条选择变化。头像名称区分大小写，可以使用中文；名称和地址都会去除首尾空白，不能为空，规范化后的名称不能重复。未配置的名称会在构建期报告对应动态的 avatar 错误，frontmatter 中填写的是名称，不是图片地址。

本地封面和头像存放在 src/public，配置值使用以 / 开头的公开路径；也可使用完整 http/https 图片 URL。页面会为本地路径和动态图片统一拼接 SITE_BASE，远程 URL 保持原地址。完整写作格式见发布短动态。

导航配置 ​

siteConfig.navigation 是 NavItem[]。有 href 的项目是直接链接，有 children 的项目显示为下拉菜单；children 仍是 NavItem[]，因此支持继续嵌套。

const navigation = [
  { title: "文章", href: "/blog" },
  { title: "动态", href: "/moment" },
  { title: "使用手册", href: "/blog/guide/getting-started" },
  {
    title: "浏览",
    children: [
      { title: "标签", href: "/tags" },
      { title: "归档", href: "/archives" },
    ],
  },
];

社交入口 ​

homeSocials 控制首页的文字社交入口。Header 只保留导航、搜索和主题切换，不显示社交图标。

const homeSocials = [
  { label: "GitHub", href: "https://github.com/username" },
  { label: "RSS", href: "/rss.xml" },
];

没有有效地址的平台应直接从数组中移除，不保留空链接。

Giscus 评论 ​

博客使用 Giscus 将 GitHub Discussions 作为评论存储。站点不需要数据库或评论服务端；读者可以公开阅读评论，使用 GitHub 账号登录后参与讨论。

siteConfig.giscus 的类型是 GiscusConfig | null。不需要评论时保持 null；需要评论时，按照下面的流程准备 GitHub 仓库并获取配置参数。

准备 GitHub 仓库 ​

1. 确保承载评论的 GitHub 仓库是公开仓库。评论仓库可以是博客源码仓库，也可以是单独创建的公开仓库。
2. 打开仓库的 Settings，在 General > Features 中启用 Discussions。
3. 打开 Giscus GitHub App，选择 Install 或 Configure，并授权它访问承载评论的仓库。只授权实际使用的仓库即可。
4. 在仓库的 Discussions 页面确认至少有一个可用分类。推荐使用 Announcements，这样普通用户不能脱离文章随意创建新的主讨论。

如果 Giscus 配置页无法识别仓库，优先检查仓库是否公开、Discussions 是否启用，以及 Giscus App 是否已经获得该仓库的访问权限。

生成 Giscus 参数 ​

打开 Giscus 配置页，完成以下设置：

1. 在“仓库”中填写 owner/repository。页面显示仓库满足条件后再继续。
2. 在“页面 ↔️ Discussions 映射关系”中选择 pathname 对应的方案。本项目推荐 pathname，同一路径始终使用同一条 Discussion；文章 slug 改变后会被视为一篇新文章。
3. 在“Discussion 分类”中选择前面准备的分类，通常使用 Announcements。
4. 根据需要开启主贴反应，将评论框位置设为底部，并选择简体中文。
5. 在页面底部找到生成的 <script>。不需要把这段脚本粘贴进 Vue 组件，只需把其中的 data-* 属性转换为 site.config.ts 的配置。

生成脚本中的 data-theme、data-strict、data-emit-metadata 和 data-loading 不需要写入站点配置：项目已经统一管理这些行为。

写入站点配置 ​

打开 src/.vitepress/site.config.ts，将默认的 giscus: null as GiscusConfig | null 替换为完整配置：

giscus: {
  repo: "owner/repository",
  repoId: "R_...",
  category: "Announcements",
  categoryId: "DIC_...",
  mapping: "pathname",
  reactionsEnabled: "1",
  inputPosition: "bottom",
  lang: "zh-CN",
} satisfies GiscusConfig | null,

不要根据仓库名称猜测 repoId 或 categoryId，这两个值必须从 Giscus 为目标仓库生成的脚本中复制。若以后更换评论仓库或 Discussion 分类，应回到配置页重新生成全部参数。

全部字段有效时，评论区会出现在文章正文下方；首页、文章列表、标签、归档和动态页不会加载评论。组件固定使用 strict="0"、emit-metadata="0" 和 loading="lazy"，并在评论区接近视口时才加载 Giscus。评论主题会自动跟随 VitePress 的 appearance 状态，不需要在配置中重复声明。

验证评论功能 ​

1. 执行 pnpm dev，打开任意文章详情页并滚动到正文底部。
2. 确认评论框能够加载，登录 GitHub 后发送一条测试评论。
3. 打开评论仓库的 Discussions，确认对应文章已经产生 Discussion。
4. 执行 pnpm exec vitest run tests/unit/site-config.test.ts，检查配置字段和 ID 格式。

首次发表评论时，Giscus 才会为当前 pathname 创建 Discussion，这是正常行为。如果评论区没有显示，可依次检查 giscus 是否仍为 null、字段是否全部复制、Giscus App 授权、Discussions 开关、仓库可见性，以及浏览器网络或内容拦截扩展是否阻止了 giscus.app。

需要关闭评论时，将配置恢复为 giscus: null 即可，不需要删除组件或卸载依赖。已有 Discussion 会保留在 GitHub 中，但站点不再加载它们。

VitePress 基础配置 ​

src/.vitepress/config.ts 导出异步 UserConfigFn<DefaultTheme.Config>。它组合 site.config.ts、文章数据和 Markdown plugins，属于工程基础设施；只更换博客信息时不需要改这个文件。

顶层选项 ​

配置函数还会根据 command 区分环境：开发服务的系列侧栏包含草稿，生产构建会排除草稿；执行生产构建前调用 requireSiteUrl()，缺少 SITE_URL 时主动失败，避免发布带错误绝对地址的页面。

Markdown 选项 ​

这些能力由 VitePress 官方 Markdown 配置和 markdown-it plugins 提供，自定义主题只负责展示，不重复实现解析行为。

Custom Containers 使用 VitePress 保留的英文关键字，界面标题改为中文：

markdown.config(md) 依次注册下列 plugins：

具体写法分别见《使用 Markdown 扩展》《编排多图布局》和《使用 Live Photo》章节。

Sitemap、head 与构建钩子 ​

transformHead 优先使用动态页面参数中的 title、description、keywords、url 和 canonical，缺失时回退到页面数据及 siteConfig.site。带文章 slug 的页面输出 og:type=article，其它页面输出 website。

配置辅助函数 ​

site.config.ts 还导出三个辅助函数，通常不需要修改：

主题设计令牌 ​

项目参考 shadcn-vue 的语义主题方式，将可复用视觉值集中放在 src/.vitepress/theme/tailwind.css 的 @theme 中。组件优先使用 Tailwind utility，不直接读取具体颜色或尺寸数值。只有运行时生成的 DOM、复杂选择器或伪元素无法通过 utility 清晰表达时，才在对应组件中使用一个 <style scoped>，并直接读取相同的设计令牌。例如 ArticlePage.vue 使用标准 CSS Nesting 将 VitePress 生成的 Markdown DOM 规则收拢在 .article-content 下。现有 Tailwind CSS 4 + Vite 构建链可直接处理该语法，不需要额外的 nesting 插件或 PostCSS 配置。

颜色角色 ​

Tailwind 默认颜色命名空间已经关闭。通用 surface 使用基础 token / -foreground 配对，保证背景和其上的内容一起变化：

所有 --color-* 和阴影中的颜色必须使用 oklab()。亮色值定义在 @theme；@utility theme-dark 只覆盖确实不同的同名 token。根布局通过 dark:theme-dark 一次加载暗色值，组件继续使用 bg-background、text-foreground、border-border 等相同 utility。照片预览与搜索 dialog 的 mask 都使用 overlay；照片预览内直接落在 mask 上的图标和信息栏使用其通用配对 overlay-foreground，LIVE 标识和页面侧栏入口继续复用其它通用角色，不为单个组件建立专属色板。只有固定代码画布这类通用角色确实无法表达的功能才建立领域前缀，不能按页面或某次使用创建 header-*、search-* 一类颜色。

可维护尺度 ​

除颜色外，项目集中管理所有对博客有长期价值的设计尺度：

基础数值尺度使用 Tailwind 熟悉的 sm、md、lg；只有跨组件且用途稳定的值才使用 page-gutter、side-rail-top 这类语义名称。项目没有表单系统、统计图表或 dashboard sidebar，因此不会照搬 shadcn-vue 中没有实际消费者的 token；照片详情宽度属于稳定布局尺寸，可以保留 container-photo-inspector，但这不意味着照片功能需要独立颜色领域。

新增与修改规则 ​

调整全站视觉时先修改已有 token。确需新增时，先确认它满足以下条件：在多个位置重复，或代表不会随组件名称变化的稳定语义；名称描述角色而非颜色值或当前页面；有源码消费者和必要的回归断言。surface 颜色必须补齐 -foreground 配对，独立领域内部也遵循 background、foreground、card、muted、border、accent 等一致后缀。

视口 calc()、响应内容的 minmax() grid track、伪元素 content 和组合 transition property 依赖上下文，可以保留 arbitrary value。普通字号、字距、圆角、模糊、图片比例和动画已有命名尺度，不得再写 arbitrary value。不要使用 Tailwind 内置色板或任意硬编码颜色。确需 scoped CSS 时，每个组件最多使用一个 <style scoped>，不得使用全局选择器、Tailwind 指令、CSS Modules、CSS-in-JS 或内联 style；pnpm audit:styles 会检查这些边界、必需 namespace、颜色配对和旧 token 回归。

发布前检查 ​

发布前至少确认：

• site.config.ts 中的站点名称、简介、关键词和作者信息已替换。
• 导航链接和 homeSocials 中没有无效占位地址。
• favicon 和 manifest 图标文件真实存在。
• workflow 的 SITE_URL、SITE_BASE 与 GitHub Pages 实际部署方式一致。
• 不使用评论时 giscus 为 null；使用时全部字段来自目标仓库的 Giscus 配置。
• 修改 config.ts 后，相关 Markdown、动态路由、SEO 或静态生成测试同步更新。