讲真的，Hexo 折腾到这个阶段，主题装好了、配置能跑了、部署也通了，很多人会突然发现一个问题：自己写出来的文章，怎么看都跟别人用 Butterfly 主题写出来的效果差一截。不是内容不行，也不是主题不行，而是写作方式和 Butterfly 的渲染机制没对上。这篇文章我想把自己在实际使用 Butterfly 主题写文章时积累的一套方法、踩过的坑、以及真正好用的细节整理出来。不论你是刚切换到这个主题的新手，还是已经写了不少文章但总觉得排版不够精致的用户，这都应该是一份可以直接对照着用的写作指南。
1. 先搞懂 Butterfly 主题想要的“文章结构”
1.1 写作之前必读的 Front Matter 字段
很多人的第一篇文章就是在后台新建一个 Markdown 文件，然后从正文开始敲。这本身没错，但 Butterfly 主题对文章头部信息（即 Front Matter）的依赖程度，远超很多其他主题。别小看这几行配置，它直接决定了文章在首页、列表页、归档页以及文章页里的展示方式。
在使用 Butterfly 时，我会在每篇文章开头固定维护这样一段元信息：
--- title: 文章的完整标题 date: 2025-01-15 10:30:00 updated: 2025-01-15 15:20:00 tags: - Hexo - Butterfly categories: - 技术杂谈 cover: /img/post-cover.jpg cover_in_post: false description: 这里是文章摘要，会显示在列表页和搜索引擎结果中 keywords: [Hexo, Butterfly, 写作] top: 0 sticky: 0 ---这里面有几个字段需要特别留意。cover字段是文章封面图，如果缺失，首页文章卡片就会变成默认的纯色背景或者直接没有封面，视觉上会显得很单调。top和sticky都是置顶相关字段，前者是文章在列表中的置顶权重，后者决定文章是否固定在侧边栏或首页顶部。写技术文章时这两个字段建议保持默认，长期置顶反而容易让读者忽略最新内容。
cover_in_post是一个很容易被忽略但实际很有用的字段。默认情况下，封面图会同时显示在首页卡片和文章正文顶部。如果你觉得封面图在正文里太占空间，或者封面图本身就是文章配图的一部分，把它设为false就显得很关键了。博客的展示风格会因此干净很多。
1.2 为什么分类和标签需要提前规划
这一点我必须重点强调：不要等文章写了几十篇之后再回头整理分类和标签，那样你会崩溃的。Butterfly 的标签和分类页面会自动聚合所有文章，而且同一个标签下如果有几十上百篇文章，页面会变成一个很长的列表，阅读体验很差。
我建议你在开始写作前就先规划好一个大致的体系。比如技术博客可以这样划分分类：后端、前端、工具链、随笔。标签则是更细维度的描述，每篇文章用三到五个标签就足够了，不要堆砌。
还有一个容易被忽略的细节：Hexo 的分类是支持多级和顺序的。categories字段里如果写入多个层级，Butterfly 会生成类似“技术 / 前端 / 框架”这样的层级路径。但按我的经验，分类层级最好控制在两层以内。层级太深会让面包屑导航和侧边栏分类列表看起来非常笨重。
1.3 摘要字段与控制“阅读全文”
有些博客写文章是从不写摘要的，完全依靠首屏文字截断。Butterfly 默认会在首页列表显示文章摘要，如果 Front Matter 里面没有description，它会自动截取正文开头的一段文字。听起来很方便，但实际效果往往很糟糕。
因为很多时候正文第一段是“这篇文章我们来讲讲……”这种废话，截取出来毫无吸引力。更稳妥的做法是手动在 Front Matter 里写description，控制在100字左右，把文章的核心价值说清楚。
这里还要提一个高级技巧：如果你希望首页只显示摘要而不让全文出来，除了写description之外，还可以在正文里手动插入<!-- more -->注释标签。同样，如果你想在列表页展示一个自定义的摘要图，而不是封面图，可以设置cover为一张专门做列表缩略图的图片。很多人忽视了这种“一图两用”的思路，但实际操作起来，对博客首页整体美感的影响非常直接。
2. 从 Markdown 到 Butterfly 渲染：写作思维需要升级
2.1 代码块的展示效果完全可以更专业
对于技术类博客来说，代码块的展示效果直接决定了读者的停留时间。Butterfly 主题内置了代码高亮和复制按钮，默认的展示效果已经不错，但有几个细节是很多人在写作时没注意到的。
第一，代码块语言标记一定要写。在 Markdown 中，代码块开头需要写明语言类型，例如```javascript、```bash等。写了语言标记之后，主题才能正确调用高亮方案进行渲染。第三，代码块的折叠功能在高版本 Butterfly 中可以通过配置开启，这适合篇幅比较长的代码片段，默认折叠起来，需要时再展开，页面会清爽很多。
还有一个细节经验：在写命令类代码时，很多人喜欢在正文里既写npm install xxx又写执行过程，实际上更专业的做法是给代码块加上注释说明，或者在代码块前后用简短文字描述运行效果，而不是把终端输出也一长串贴进来。终端输出属于文本信息，可以用引用块或普通段落承载，没有必要占一整块代码。
2.2 图片排版：懒加载、居中和 alt 一个都不能少
图片是博客文章的视觉重心，但 Butterfly 对图片的处理有几个默认行为，如果不了解，写出来的文章会出问题。
主题默认给文章内的图片加上了懒加载效果。这个设计初衷是好的，可以让页面打开速度更快，但有一个副作用：如果图片本身没有设置宽度或高度，加载过程中页面布局会产生跳动。所以我的习惯是尽量对图片进行预处理，确定好宽度，而不是把原图尺寸直接丢进文章。
关于居中问题：Markdown 原生语法不支持图片居中，但 Butterfly 的渲染层是支持通过 HTML 实现居中的。当你需要一张图片单独展示并居中时，可以用下面这种方式：
<div align="center"> <img src="/img/example.png" alt="示例图片描述"> </div>如果只是行内配图，那么直接用标准 Markdown 语法加上alt属性就足够了。很多人在写作时不写alt，觉得这是小事，但无论是无障碍阅读还是 SEO 效果，alt都扮演了很重要的角色。图片加载失败时，你的博客页面显示出的是图片路径还是友好的说明文字，体验差距非常大。
2.3 引用的正确使用方式
Butterfly 主题对引用块样式的渲染在不同版本中略有差异，但整体上都是带有左侧色条的样式。很多人把引用块当作备注工具来用，导致文章里出现大量一个段落的引用，看起来非常杂乱。
我的经验是，引用块只适合两类场景。一类是引用外部文章、书籍、文档中的原话，这时需要在末尾标注出处；另一类是给自己文章里的重点内容做视觉上的加强。重点内容的引用可以配合加粗使用：
注意：不要在某篇文章里连续使用多个独立引用块，这会让阅读节奏中断。如果需要罗列多个注意点，可以用无序列表放在同一个引用块内部。
其实 Butterfly 还额外支持一种更花哨的标签外挂方式，比如{% note primary %}，这种彩色提示块能够在视觉上区分不同级别的提示信息。后面我会专门讲。
2.4 列表与段落的节奏感
Markdown 写作常见的问题是：通篇都是列表，或者通篇都是长段落。Butterfly 主题默认的正文页面宽度在阅读体验上是经过了优化的，它能够容纳适当的长段落，但也经不起摧残。
写作时要有节奏感。一个核心观点对应一个自然段，四到六行为宜。超过十行的段落，读者在屏幕上阅读起来是很累的。需要并列展现的信息，用无序列表；需要体现步骤或顺序的内容，用有序列表。在列表之间穿插少量描述性文字，效果会比连续的列表好很多。
一个容易踩的坑是：列表嵌套层级太多时，Butterfly 的渲染在移动端会有缩进过深的问题。所以列表嵌套控制在两层以内，超过两层的内容拆成段落描述更合适。
3. 玩转 Butterfly 专属标签外挂，让文章不再干巴巴
3.1 彩色提示框 note 的实际用法
Butterfly 主题一直以颜值著称，很大一部分颜值来自它内置的标签外挂功能。所谓标签外挂，就是通过类似{% note %}这样的简写语法，在 Markdown 里调用主题预定义的样式组件。
我日常用得最多的就是note提示框。它的语法是这样的：
{% note primary %} 常规提示内容 {% endnote %}颜色模式支持primary、success、info、warning、danger等几种。我实际使用中的经验是：不要过度使用，通常一篇文章中两到三个提示框就是极限了。否则读者会觉得满屏都是跳跃的颜色块，视觉重心完全丢失。
比较合理的用法是，在总结某个核心操作的意义时用primary，在强调一个容易犯错的细节时用warning，在提醒某种操作可能造成不可逆后果时用danger。这样仅仅通过颜色就能给读者传递出信息的紧急程度，比单纯写“注意”两个字有效得多。
3.2 折叠块与时间轴：长文编排的利器
写长文时，最担心的是内容太长导致读者失去耐心。Butterfly 的折叠块组件可以帮助解决这个问题。它的语法也很简单：
{% folding 点击查看答案 %} 隐藏的具体内容 {% endfolding %}我通常在两种场景下使用折叠块。第一种是 FAQ 场景：文章提出了一个问题，预留给读者思考时间，然后折叠的内容里面放上解析。第二种场景是补充材料：比如一段很长的配置代码示例、一个完整的报错日志。这些内容本身很重要，但如果直接铺开，会打断阅读主线，折叠起来反而是对阅读节奏的保护。
另一个组件timeline用来展示时间线非常合适，语法如下：
{% timeline 2024年 %} - 01月: 完成主题切换 - 06月: 完成博客速度优化 {% endtimeline %}写项目复盘、年度总结、更新日志这类文章时，时间轴组件能够让信息结构一目了然。这个组件的渲染样式在 Butterfly 中做得非常细腻，强烈建议试试。
3.3 按钮链接和图文卡片，提升文章交互感
很多时候我们会在文章里贴出跳转链接，比如参考文档、相关项目、下载地址。标准 Markdown 给出的链接样式是一个普通内联文本，在长文中并不显眼。Butterfly 的button外挂就是为了改善这个体验：
{% btn 按钮文字, https://example.com, 可选图标 %}我习惯用它来放置文末的“相关阅读”或“项目源码”入口。按钮化之后，这类跳转链接的点击率明显比纯文本链接要高。
图文卡片组件就是常说的card系列，这是它的进阶应用：
{% asset_img example.png 图片描述 %}如果你启用了文章的asset_img配置，可以配合文章资源文件夹来管理图片。整体来说，Butterfly 的标签外挂体系非常丰富，但掌握二三种核心的就足够了。太多花哨外挂反而会让文章失去原本应有的文字力量。
3.4 隐藏块、密码保护与提示气泡：高级但慎用
有些主题版本配合插件支持“隐藏文字”，鼠标选中或点击后才能看到具体内容。这个组件在写一些带有剧透性质的评测类文章时很好用。当你需要保护某篇文章的访问权限时，Butterfly 支持对指定的文章设定访问密码。效果是进入文章前先弹出一个密码框。
我得说，密码保护这个功能在日常博客写作中使用频率非常低。但从安全角度来说，如果你真的想在某种场合下做试读或限时分享，了解它的配置方式总没有坏处。用好了很酷，用不好的话，反而会让读者对你的博客产生距离感。我的建议是，除了连载和付费内容场景，其他情况还是保持文章开放阅读更好。博客的核心价值在于传播知识，设置门槛之前要仔细斟酌要不要这样做。
4. 图片处理与写作资源管理，最容易被拖延的关键环节
4.1 本地图片资源与图片文件夹配置
写作时，图片该放在哪里？这个问题听起来基础，但很多人用 Hexo 写了很长时间，仍然没有理顺。
Hexo 提供了两种主流做法。第一种是“全局图片目录”模式，即所有文章共用source/images目录，文章里引用路径写/images/xxx.png。第二种是“文章资源文件夹”模式，在_config.yml中设置post_asset_folder: true后，每篇文章都会有一个同名文件夹，文章内的图片引用可以写成{% asset_img xxx.png %}或相对路径形式。
我个人的选择更倾向于全局目录加子目录分类，比如source/images/2025/01/xxx.png。理由很简单：全站图片集中管理，备份、迁移、CDN 刷新时都非常方便。文章资源文件夹的方式在写作时确实更直观，但与很多自动化部署脚本配合时反而会多一些路径处理的问题。
4.2 图片压缩与命名规范，决定了博客能跑多久
这一点是我最想告诉新手的经验：博客写作中，图片的优化工作千万别偷懒。对技术博客来说，页面加载速度直接影响读者留存。一篇带有大量截图的教程，如果图片巨大，加载体验会非常糟糕。
我建议每个博主形成这样的习惯：截图后在本地用工具快速压缩，尽量把一张普通截图的体积压到 200KB 以下。同时，图片统一采用小写英文命名，单词间用短横线分隔。不要用中文文件名，不要混用大小写，更不要直接把微信截图那种一串数字乱码存上来。命名规范虽然简单，但随着文章量增多，它的价值会越来越明显。
关于图片格式，我个人经验是：带文字的截图或流程图用 PNG；摄影类、整体明暗过渡自然的配图用 JPEG；图标、线条类图形可以用 SVG；需要透明背景的图用 PNG 或 WebP。需要动图演示过程时，尽量控制 GIF 的帧数和尺寸，动图体积爆炸是所有博客的通病，能避免就尽量避免。
4.3 善用资源管理思维，让文章持续可维护
很多文章在发布半年后就慢慢变成“死链集中营”，最常见的原因就是图片路径失效或资源被删了。保持资源文件目录结构的稳定，是长期维护博客的基础。每次写完一篇文章后，检查一下文中引用到的图片是否都真实存在于服务器指定目录中，这个步骤虽然繁琐，但非常重要。
有条件的话，可以引入图床或对象存储来存放图片。这样本地仓库体积更小，部署更快，图片也有专门的加速通道。切换图床时需要注意防盗链问题，实践中我遇到过好几次图床开启防盗链后博客图片大面积裂掉的情况。建议选择图床服务时先阅读清楚配置规则，并在本地做好原图备份。永远记住，图床是服务的备份，本地原始资源库才是你的资产主体。
5. 写作流程中的细节锻造：从草稿到发布的必经之路
5.1 本地预览与常见的渲染差异问题
我见过不少朋友写作时直接在线上编辑器的后台敲字，敲完直接发布，这是很危险的习惯。因为某些 Markdown 语法在编辑器里看着正常，经过 Butterfly 渲染后可能会有细节差异。最好始终在本地环境中写作和预览。
Hexo 本地预览的标准命令是hexo clean && hexo generate && hexo serve。但我不建议每次都输入三连命令，实际使用中hexo clean并非每次必需，只有在更新了主题配置、修改了站点配置或出现渲染异常时才需要执行。日常只需要hexo serve就好，它会监听文件变化并自动刷新页面。
主题在更新以后，也需要重新生成一下静态文件。这时候可以直接运行hexo generate或简写hexo g。如果发现更新后样式错乱，就老老实实执行一次hexo clean再生成。本地预览时注意图片资源的引用路径，经常有人因为路径写法在本地正常、部署后失效而在线上出现问题。
5.2 写作时保持专注：先内容后排版
这一点是我踩了很多坑之后才总结出来的：写作时把注意力集中在内容上，排版优化留在二稿阶段完成。如果一边写正文一边去调整注意块颜色、插标签外挂，思路会频繁被打断，文章质量会直线下降。
我的工作流是这样的：第一遍先用纯 Markdown 把文章内容完整写出来，期间的代码块、列表、引用都用最基础的语法表达；第二遍通读全文，调整段落结构，优化语句表达，确认逻辑顺畅；第三遍才开始加 Butterfly 的标签外挂，调整提示块、折叠块、按钮和封面的设置；最后再严格检查一遍 Front Matter 信息和文章内资源路径，确认无误后再部署发布。
也许你会觉得这个过程太繁琐，但事实证明，经过这个流程写出来的文章，比草率写完立刻排版发布的文章，阅读体验要高出不少。博客文章和社交网络的碎片动态不一样，它是具沉淀价值的，值得多花一点心思。
5.3 文章写作节奏与发布频率的平衡
很多长期运营博客的人会纠结发布时间和频率的问题。我的观点是：发布频率远比发布时间重要。写作是积累性工作，连续几周保持每周至少一篇的稳定输出，比某一个月爆发式更新几篇再停更三个月对博客建设更有价值。
在 Butterfly 主题中，除了发布时间date字段外，还可以通过updated字段手动维护更新时间。一篇优质的文章经过一段时间后做修订，是很正常的事情。更新文章后记得把updated字段改成当前时间，这样文章列表会更客观地展示新鲜程度，对读者也有好处。
别小看这些细节，它们决定了你的博客是“活”的网站还是“僵尸”站点。
5.4 工作区、草稿箱与阶段管理
Hexo 原生提供一个draft机制，通过hexo new draft 文章名创建草稿，之后用hexo publish 文章名发布。这个机制配合 Butterfly 主题是完全可以正常使用的。但实际写作中，很多作者更喜欢直接在source/_posts目录手动创建文件，因为这样可以更灵活地控制文件命名和目录结构。
我的建议是把复杂文章拆分成几个步骤。先在本地维护一个“写作大纲”文档，然后把每个章节当作一个小节分开写，写完一部分再合并到正式文章文件里。这样写作压力会小很多，思路也更清晰。等到整篇文章的结构稳定了，再一次性补全正文并处理排版。
这个方法特别适合长文写作。如果把这些内容全塞在一个文件里，写到最后开头部分基本已经忘了该调整什么了。
6. 部署上线前后，必须自检的问题与排查思路
6.1 首页摘要异常与显示截断问题
自检的第一步是看首页文章列表。很多人在本地预览时会发现，有些文章列表显示的内容非常长，甚至把全文都展示了出来，这通常是没有设置摘要导致的。如果你的文章没有添加description，Hexo 默认会截取文章开头的一段纯文本，但长度会有随机性。最稳妥的做法就是按照第一节提到的写法，手动设置description字段。
另一种情况是摘要特别短，只有一行，看起来就像文章没有内容一样。这多半是因为在文章开头就放了一张图片或一个标签外挂，而 Hexo 在提取纯文本摘要时把这些内容过滤掉了，只留下了少量文字。这种情况下，你可以在文章最开始放一段真正的引言，并确保 Front Matter 中description字段内容足够丰富。
6.2 代码高亮失效或复制按钮失灵
技术博客的代码高亮如果失效，阅读质量会断崖式下跌。常见的失效原因有两类：一类是代码块的语言标记写错了，比如把javascript拼成js，虽然部分高亮方案支持别名，但最好不要赌；另一类是主题配置文件中的高亮方案被上一次修改残留配置破坏了。
复制按钮失灵的情况很少见，但如果你启用了 pjax 局部刷新，有时在页面跳转后交互会失效。解决办法是刷新一次页面，或者检查主题版本与插件版本之间的兼容性说明。这类问题我通常在升级主题后集中排查一把。
翻阅 Butterfly 的文档时，你会发现配置项之间是存在依赖关系的，改了一个开关，另一个功能可能受影响。维护一个属于自己的主题覆盖配置清单，能够大大减轻这种排查成本。
6.3 标签外挂显示为原始文本，没有正常渲染
这是一个必须高度警惕的问题。如果在文章页看到类似{% note warning %}这样的字符原封不动显示出来，说明你的文章内容根本没有经过 Hexo 渲染器的标签外挂处理流程。
实际原因往往锁定在两个层面。其一，是渲染器配置中被排除了某些文件路径，导致部分 Markdown 文件没有被渲染；其二，是文章里使用了当前主题版本不支持的标签外挂语法，或者语法格式写错，比如结束标签写成了{% endnote %}。
遇到这种情况，最直接的排查方式是先看看主题版本对应的官方文档中的写法。不同版本的外挂语法是存在差异的，不要拿老版本的文章模板直接往新版本里套。这里提醒你，切换主题版本或升级主题时，一定要在本地跑一遍典型文章的渲染检查。
6.4 URL 与永久链接的规划
在写作之初就对 URL 结构做一个规划，能在长期运营中节省大量时间精力。Hexo 支持在站点配置文件中设置permalink结构，比如:year/:month/:title/这种形式。Butterfly 主题本身不强制 URL 格式，但这个前缀会影响文章链接的规范化程度。
我的建议是始终使用以.html结尾的链接，还是无后缀的伪静态形式，关键是保持统一。分享出去的链接最好不要随意更改，否则搜索排名会受损。此外，文章标题的变更会直接影响 URL 变化，所以尽量在发布前把标题最终定稿，发布后不要轻易改写标题。
6.5 发布后常见问题的快速排查清单
根据我在多个项目与站点维护中的实践经验，整理一个自检清单是极其高效的方式。发布一篇文章前，可以依次检查：
- Front Matter 字段是否完整，尤其是
cover和description - 正文中图片路径是否有缺失或错误
- 代码块语言标记是否填写正确，是否使用了主题支持的语言别名
- 标签外挂语法是否匹配、是否匹配当前主题版本
- 文末是否生成了版权声明和打赏、分享模块
- 文章页标题、目录树、相邻文章导航是否正常展示
- 移动端页面浏览是否存在横向滚动或图片溢出
这份清单看起来琐碎，但实际操作下来每次只需要两三分钟，却可以避免很多发布后才发现问题的尴尬情况。
7. 让 Butterfly 主题下的文章长期保鲜的行动指南
写了这么多，都是可以立刻上手的实用方法。最后分享几点我在长期写作过程中的观察结论。文章质量是一个博客的根基，主题只是让好内容更好地被阅读的放大器。没有好的内容，再花哨的排版也只是空壳；反之，只有内容没有排版，再好的文章也容易让读者失去耐心。但这不是说一定要把排版做到极致，而是说要把基础做好，确保读者能够顺畅地读完全文。
我在实践中最深的一个体会是：把写作流程固定下来，形成自己的习惯，比追逐任何新功能都重要。每次都按照自己熟悉的流程去写作、排版、自检、发布，效率和稳定性都会远远高过灵感驱动式的随机创作。Butterfly 主题的文档非常详细，值得花一个完整的下午翻一遍。
建立自己的组件样例库也是一个很好的习惯。你可以在本地建一个隐藏草稿文章，把常用的note、folding、timeline、btn等组件按不同样式写进去，需要时直接打开参考或复制，不需要每次去查文档，也不需要凭记忆硬写。久而久之，这套属于自己的“写作组件库”会成为你博客更新效率和质量的坚实保障。
最后想说的是，博客写作是一件长期主义的事情，慢慢积累，稳定输出，比一时的花样翻新重要得多。希望这些细节能帮你在 Butterfly 主题下写出更称心如意的文章。
