Skip to content

[Feature]: 配置项与内容统一分离——将配置纳入内容仓库(overrides 机制) #549

Description

@Dawn6666666

Is your feature request related to a problem?

Mizuki 目前已经提供了很好的内容分离机制(ENABLE_CONTENT_SYNC + sync-content),可以把文章、页面数据、图片等内容放到独立仓库,与主题代码解耦。

配置项src/config/*,如 siteConfig、profileConfig、navBarConfig、footerConfig 等)仍然必须直接修改代码仓库中的源文件,也就是把个人配置值内联进上游文件结构里。对于 fork 上游、定期 rebase/merge 跟进版本更新的用户,这会带来持续的维护成本:

  1. 配置文件是升级冲突的重灾区:上游每次调整配置结构(新增配置块、重排字段、修改默认值)都会与本地个人值发生 merge 冲突,需要人工逐个解决;
  2. 配置与代码版本强耦合:配置无法独立回滚、独立查看变更历史;
  3. 配置没有天然备份:内容已经可以通过内容仓库独立备份和版本化,配置却做不到;
  4. 配置变更与代码变更混在同一个提交历史中,难以区分"升级主题"和"调整自己的站点"。

Describe the solution you'd like

在现有内容分离机制的基础上,把配置项也纳入同一个独立仓库,实现内容与配置的统一分离。设想如下:

1. 内容仓库新增 overrides/ 目录(目录名可讨论)

按配置文件拆分为若干覆盖文件,每个文件只包含用户想改的字段,利用 TypeScript 类型约束保证安全:

// overrides/site.ts
import type { SiteConfig } from "../types/config"; // 路径示意
export default {
    title: "我的站点",
    siteURL: "https://example.com/",
    banner: { src: { desktop: ["..."], mobile: ["..."] } },
} satisfies Partial<SiteConfig>;

2. 同步脚本新增一条映射

sync-content 增加 overrides → src/data/overrides(或其他白名单目录)的映射,复用现有的同步、清理与安全校验逻辑。

3. src/config/index.ts 改为合并适配器

配置文件本身保持上游原版(默认值),统一导出入口在导出前将对应 override 深合并进来:

最终配置 = deepMerge(上游默认配置, overrides 对应文件)

4. 明确的合并语义

  • 对象:深合并(override 只覆盖写到的字段,其余取上游默认);
  • 数组:整体替换(例如 banner 图片列表不应与默认值拼接)。

收益

  • 跟进上游更新时,配置文件的冲突面从 N 个文件收敛到 1 个适配器文件;上游新增配置项自动生效、零冲突,只有上游修改结构时才会暴露问题,且表现为编译期类型错误,容易定位和修复;
  • 配置获得独立仓库的版本历史,天然支持备份与回滚;
  • 调整配置不再触碰代码仓库;
  • 与现有开关完全兼容:ENABLE_CONTENT_SYNC=false 或 overrides 缺失时,行为与现状完全一致,用户可以按需渐进采用(不写 override 的配置文件行为不变)。

Describe alternatives you've considered

  1. 各配置文件单独外置(每个配置一个独立仓库/目录):过于分散,且与现有内容同步机制重复;统一放在内容仓库的一个子目录更内聚;
  2. JSON/YAML 配置文件:会失去 TypeScript 类型检查与代码注释提示,配置错误要到运行时才暴露;satisfies Partial<XxxConfig> 的方式可以把错误提前到构建期;
  3. fork 后不合并上游更新:放弃升级等于放弃安全性与功能更新,不是可持续方案;
  4. git patch/钩子方式在升级后重放配置:使用门槛高,且本质上仍在处理冲突,只是换了个地方。

Additional context

这个设想本质上是把 Mizuki 现有的"内容与代码分离"思想自然延伸到配置层:代码仓库只保留主题本身,独立仓库承载"让站点成为用户自己的"的全部内容(文章、数据、图片 + 配置)。

实现要点小结:

  • 同步映射:overrides → src/data/overrides(复用 sync-content 白名单机制);
  • 合并适配器集中在 src/config/index.ts,各配置文件保持上游原版;
  • 合并语义:对象深合并、数组整体替换;
  • 类型安全:override 文件使用 satisfies Partial<XxxConfig>,构建期即可发现与上游结构不匹配的字段;
  • 内容仓库触发部署的 paths 过滤需要相应加入 overrides/**

如果需要,我可以提交 PR 实现该方案。

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions