对博客主题来说,配置是「给开发者的选项」;对机构官网主题来说,配置文件就是客户的操作手册。60+ 项配置写得乱,客户就改不动;改不动,就要来找你。

这一篇讲这套配置怎么分组、怎么保证升级不丢、以及踩到的 YAML 坑。

一、分组原则:按页面区域,不按技术模块

_config.yml 的一级键顺序,就是页面从上到下的顺序:

YAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
preset: enterprise      # ① 整体气质
brand: # ② 品牌(logo / 名称 / slogan)
menu: # ③ 顶部导航
nav_button: # ④ 导航右侧按钮
sections: # ⑤ 首页板块顺序
hero: # ⑥ 以下是各板块自己的数据
quicklinks:
stats:
services:
about:
products:
news:
team:
partners:
gallery:
cta:
contact:
footer: # ⑦ 页脚
social: # ⑧ 社交链接
features: # ⑨ 功能开关
seo: # ⑩ SEO
analytics: # ⑪ 统计代码
分组要对应客户的心智

客户想改「页脚的备案号」,他会去页面底部找,然后来配置里找——如果分组是按技术模块分的(i18n / components / utils),他就找不到。

判据:客户看着页面能不能猜到配置在哪一节?

二、每个板块都遵循同一套结构

YAML
1
2
3
4
5
6
services:
enable: true # ① 开关
title: "核心业务" # ② 标题文案
subtitle: "我们提供以下专业服务" # ③ 副标题
items: # ④ 数据列表
- { icon: "shield", title: "安全检测", desc: "全流程安全检测服务", url: "/services/" }

四段式:开关 / 文案 / 数据 / (可选)跳转。所有 12 个板块都是这个结构,客户学会一个就会用全部。

文案与开关必须分离

早期我把「是否显示」和「显示什么」混在一起——不填标题就隐藏。结果是客户清空标题想临时隐藏,却发现布局塌了。

现在 enable 是唯一开关,文案为空只影响文案本身,布局不受影响。

三、升级不丢配置:站点覆盖文件

这是 Hexo 自带但很多人不知道的机制:站点根目录放 _config.<主题名>.yml,Hexo 会自动把它与主题 _config.yml 深度合并。

Text
1
2
3
my-site/
├─ _config.yml # 站点配置
└─ _config.hexo-theme-xongyi.yml # 只写「与主题默认值不同」的键
YAML
1
2
3
4
5
6
7
8
9
10
# _config.hexo-theme-xongyi.yml
brand:
name: "雄亿检测仪器"
slogan: "专业检测仪器制造商"

footer:
copyright: "© 2026 佛山市顺德区雄亿检测仪器有限公司"

seo:
description: "雄亿仪器 — 专业检测仪器研发制造,提供涂层测厚仪 · 硬度计等产品。"

好处有三:

  1. 只写差异:不用复制整份主题配置,行数少;
  2. 升级不丢:主题用 git submodule 引入,git submodule update 不会动站点根目录的文件;
  3. 一眼看见定制了什么:改过哪些默认值清清楚楚。
文件名必须完全匹配主题目录名

是 _config.hexo-theme-xongyi.yml,不是 _config.xongyi.yml。主题目录叫什么,文件名就叫什么——这也是我在第八篇讲的「仓库形态改造」里强调目录命名要遵循官方规范的原因之一。

四、预设示例:给客户一个能抄的起点

光有配置项还不够,客户需要「政务站长什么样」。所以提供完整的示例配置:

Text
1
2
3
examples/
├─ config.government.yml # 政务站完整配置(含政务口吻的文案)
└─ config.education.yml # 教育站完整配置
示例配置的价值在于「文案」而不只是「参数」

客户最难的往往不是填参数,而是不知道该写什么文案。示例里给出「办事指南」「信息公开」「在线咨询」这类行业化措辞,比给一组占位符有用得多。

五、YAML 的两个坑

坑 1:双引号字符串里不能再嵌 ASCII 双引号

YAML
1
2
3
4
5
# ❌ 解析失败
slogan: "专业制造"品质"保障"

# ✅ 中文书名号替代
slogan: "专业制造『品质』保障"

政务示例的文案里大量出现引号,统一改用『』。

坑 2:注释里的配置项要跟着代码更新

配置文件的注释就是文档。我给自己定的规则是:改了模板逻辑,必须同步改 _config.yml 对应注释和 README。

三个「文档与实物不一致」的典型
  1. 新增了板块但没在 sections 注释里的「可用板块」清单中列出 → 客户不知道有这个板块;
  2. 改了默认值但注释里还是旧值 → 客户按注释填,结果不对;
  3. README 的特性表加了功能,但配置里没这个键 → 客户照着 README 找不到。

修法:写文档时对着 _config.yml 逐项念一遍,而不是凭记忆写。

六、配置项的取舍:什么时候拒绝加配置

有客户要求「每个板块的背景色单独可配」。我拒绝了。

理由:加一个 background 键,就要处理「配置了但和预设冲突怎么办」「暗色模式下这个颜色怎么变」,然后预设机制被撕开一个口子。

加配置的三个自查
  1. 这个需求在 10 个客户里有几个会用到?
  2. 加了它,会不会和既有机制(如预设、暗色模式)冲突?
  3. 客户能不能用已有能力(自定义 CSS)解决?

三个问题里有两个答不好,就不加。配置表膨胀是慢性病,一旦失控就很难收回。

系列导航

系列导航