配置体系说明

English

配置来源与优先级

同名配置项的优先级：

1. Notion Config 表
2. 环境变量
3. 本地配置文件（blog.config.js / conf/*.config.js）

推荐实践

• 将大块配置拆分到 conf/*.config.js
• blog.config.js 仅做聚合，避免文件无限膨胀
• 新增配置项时，写清楚：
  • 默认值
  • 环境变量名
  • Notion Config 同名键

开源协作高风险点（必须遵守）

1) 不要提交个性化配置

以下内容通常属于个人环境，不应提交：

• .env.local
• 带私人 key/token 的配置
• 带个人广告 ID、统计 ID、第三方埋点 ID 的默认值
• 仅个人站点使用的导航/菜单/主题私有配置

2) 避免修改与任务无关的配置文件

例如你只修复一个组件 bug，不应顺手改动大量 conf/*.config.js 排序或格式。

3) 新增全局配置时要文档化

至少更新：

• conf/*.config.js 注释
• 本目录文档或 PR 描述中的使用说明

主题级配置也遵守同一原则。新增 themes/<theme>/config.js 配置项时，请同步更新 docs/user-guide/themes/<theme>.md，说明默认值、开启/关闭效果，以及是否支持 Notion Config 或环境变量覆盖。不要把用户可见配置标记为“文档不适用”。