Butterfly 的配置项很多，真正容易踩坑的不是“找不到开关”，而是改错文件。主题目录里的默认配置像是一份能力清单，项目根目录的主题配置才是个人站点的定制层。把这两个边界分清楚，主题升级和日常改样式都会轻松很多。

先理解两层配置

Hexo 基础行为放在根目录 _config.yml，例如站点 URL、permalink、source_dir、public_dir 和构建选项。Butterfly 的外观和交互放在根目录 _config.butterfly.yml，例如菜单、头像、目录、搜索和页脚。

仓库已经在主题配置文件开头写明了边界：保持项目级覆盖，不直接编辑 themes/butterfly/_config.yml。主题子模块可以更新，个人配置也不会因为上游变化而被覆盖。

修改前先查看工作树：

git status --short --branch

这样可以区分“本次准备改的配置”和“之前已经存在的未提交修改”。配置文件尤其不适合用 git add . 一次性加入暂存区。

菜单和公共入口

当前配置的 menu 定义了 Home、Archives、Tags、Categories 和 About 等入口。菜单值通常由路径和图标组成，例如：

menu:
  Archives: /archives/ || fas fa-archive

增加入口前先确认目标页面确实存在。页面路径写错时，主题不会替你创建页面，用户只会看到一个看似正常但无法打开的链接。

菜单数量也不宜无限增加。首页、归档、标签、分类和关于页面已经覆盖了大多数个人博客入口；新的页面应该有明确的内容职责，而不是把每一个临时想法都放进主导航。

头像、封面和顶部图片

avatar.img、index_img 和 default_top_img 控制不同位置的图片。当前配置使用 /images/ 路径引用站点资源，这类路径应当与 source/images 中的真实文件对应。

cover 配置决定首页、侧栏和归档页是否显示封面，以及封面位置。调整图片时要同时考虑图片尺寸、页面背景和没有图片时的降级效果。不要把未验证的外部 URL 直接写进主题配置；如果地址失效，问题会出现在多个页面。

图片替换后先运行本地构建，再从 public/ 中检查路径。只改配置文件而不看生成结果，很容易把拼写错误带到线上。

文章元信息和目录

post_meta.page 与 post_meta.post 控制日期、分类、标签和文字标签是否显示。当前站点已经打开这些元信息，因此文章 front matter 的分类和标签会直接影响页面结构。

toc 控制文章目录，当前配置启用了目录和编号。文章标题层级应该从 h2 开始按顺序组织，避免跳过层级后让目录难以阅读。目录是内容结构的反映，不是可以独立修复的装饰。

local_search.enable 打开了本地搜索。它依赖生成后的文章索引，所以文章是否被正确生成、标题和描述是否完整，会直接影响搜索体验。

页脚和公开信息

footer.owner 与 footer.custom_text 控制页脚内容。页脚适合放站点归属、备案和公开链接，但不应放服务器密码、密钥路径或只对维护者有意义的内部信息。

配置长字符串时要注意 YAML 的块文本缩进。修改页脚后先构建并查看页面底部，确认链接、图片 alt 文本和换行都符合预期。外部链接也要使用 target 和 rel 等安全属性，不要只复制一段未经检查的 HTML。

用最小变更调试主题

主题配置出现问题时，不要一次修改十几个字段。推荐流程是：

  1. 记录当前工作树状态；
  2. 只改一个相关配置项；
  3. 运行内容检查和本地构建；
  4. 在生成页面中确认变化；
  5. 再决定是否保留这一项。

仓库的发布前检查可以这样运行：

pwsh ./ops/check.ps1
pwsh ./ops/build.ps1

如果生成失败，先回看最近改动的 YAML 缩进和字段类型。配置错误通常比主题内部逻辑更容易定位，也不应该通过直接修改主题模板来绕过。

主题升级时怎么保护定制

themes/butterfly 是主题子模块，升级前先记录当前版本和根配置差异。升级之后重新运行 check 和 build，重点检查菜单、页脚、代码高亮、目录和搜索。

如果升级导致页面异常，先回到上一份已验证的主题版本和提交，不要在未理解差异的情况下把主题目录改成一份混合状态。主题升级应当独立于文章发布，这样出现问题时回滚范围更小。

小结

Butterfly 定制的核心技巧不是记住全部字段，而是守住三条边界：Hexo 行为放 _config.yml，主题外观放 _config.butterfly.yml，主题源文件保持由子模块管理。每次只做一个小改动，并用生成页面验证结果。

如果你想先理解配置如何影响搜索和 URL，可以阅读Hexo SEO 与站点地图；配置改完准备上线时，再看发布后的维护与回滚。