Is your feature request related to a problem?
Mizuki 目前已经提供了很好的内容分离机制(ENABLE_CONTENT_SYNC + sync-content),可以把文章、页面数据、图片等内容放到独立仓库,与主题代码解耦。
但配置项(src/config/*,如 siteConfig、profileConfig、navBarConfig、footerConfig 等)仍然必须直接修改代码仓库中的源文件,也就是把个人配置值内联进上游文件结构里。对于 fork 上游、定期 rebase/merge 跟进版本更新的用户,这会带来持续的维护成本:
- 配置文件是升级冲突的重灾区:上游每次调整配置结构(新增配置块、重排字段、修改默认值)都会与本地个人值发生 merge 冲突,需要人工逐个解决;
- 配置与代码版本强耦合:配置无法独立回滚、独立查看变更历史;
- 配置没有天然备份:内容已经可以通过内容仓库独立备份和版本化,配置却做不到;
- 配置变更与代码变更混在同一个提交历史中,难以区分"升级主题"和"调整自己的站点"。
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
- 各配置文件单独外置(每个配置一个独立仓库/目录):过于分散,且与现有内容同步机制重复;统一放在内容仓库的一个子目录更内聚;
- JSON/YAML 配置文件:会失去 TypeScript 类型检查与代码注释提示,配置错误要到运行时才暴露;
satisfies Partial<XxxConfig> 的方式可以把错误提前到构建期;
- fork 后不合并上游更新:放弃升级等于放弃安全性与功能更新,不是可持续方案;
- git patch/钩子方式在升级后重放配置:使用门槛高,且本质上仍在处理冲突,只是换了个地方。
Additional context
这个设想本质上是把 Mizuki 现有的"内容与代码分离"思想自然延伸到配置层:代码仓库只保留主题本身,独立仓库承载"让站点成为用户自己的"的全部内容(文章、数据、图片 + 配置)。
实现要点小结:
- 同步映射:
overrides → src/data/overrides(复用 sync-content 白名单机制);
- 合并适配器集中在
src/config/index.ts,各配置文件保持上游原版;
- 合并语义:对象深合并、数组整体替换;
- 类型安全:override 文件使用
satisfies Partial<XxxConfig>,构建期即可发现与上游结构不匹配的字段;
- 内容仓库触发部署的 paths 过滤需要相应加入
overrides/**。
如果需要,我可以提交 PR 实现该方案。
Is your feature request related to a problem?
Mizuki 目前已经提供了很好的内容分离机制(
ENABLE_CONTENT_SYNC+sync-content),可以把文章、页面数据、图片等内容放到独立仓库,与主题代码解耦。但配置项(
src/config/*,如 siteConfig、profileConfig、navBarConfig、footerConfig 等)仍然必须直接修改代码仓库中的源文件,也就是把个人配置值内联进上游文件结构里。对于 fork 上游、定期 rebase/merge 跟进版本更新的用户,这会带来持续的维护成本:Describe the solution you'd like
在现有内容分离机制的基础上,把配置项也纳入同一个独立仓库,实现内容与配置的统一分离。设想如下:
1. 内容仓库新增
overrides/目录(目录名可讨论)按配置文件拆分为若干覆盖文件,每个文件只包含用户想改的字段,利用 TypeScript 类型约束保证安全:
2. 同步脚本新增一条映射
sync-content增加overrides → src/data/overrides(或其他白名单目录)的映射,复用现有的同步、清理与安全校验逻辑。3.
src/config/index.ts改为合并适配器配置文件本身保持上游原版(默认值),统一导出入口在导出前将对应 override 深合并进来:
4. 明确的合并语义
收益
ENABLE_CONTENT_SYNC=false或 overrides 缺失时,行为与现状完全一致,用户可以按需渐进采用(不写 override 的配置文件行为不变)。Describe alternatives you've considered
satisfies Partial<XxxConfig>的方式可以把错误提前到构建期;Additional context
这个设想本质上是把 Mizuki 现有的"内容与代码分离"思想自然延伸到配置层:代码仓库只保留主题本身,独立仓库承载"让站点成为用户自己的"的全部内容(文章、数据、图片 + 配置)。
实现要点小结:
overrides → src/data/overrides(复用 sync-content 白名单机制);src/config/index.ts,各配置文件保持上游原版;satisfies Partial<XxxConfig>,构建期即可发现与上游结构不匹配的字段;overrides/**。如果需要,我可以提交 PR 实现该方案。