Hexo 博客中添加字数统计功能出现标题解析异常的排查记录

在为 Hexo 博客集成字数统计功能时，我遇到一个渲染异常的问题：一段普通的文字和其后的图片被误解析为标题（<h2> 标签），导致显示错乱。这篇文章记录了该问题的排查和解决过程，供遇到类似情况的朋友参考。

一、背景与问题描述

我为 Hexo 博客安装了 hexo-wordcount 插件，并使用 Volantis 主题。在配置 top_meta 后，字数统计功能成功显示。但在文章中记录成功效果时，出现如下异常渲染：

<h2 id="最终，在文章标题下方正确显示了字数统计和阅读时长信息。">
  ...
  <img src="...">
</h2>

原因是如下 Markdown 被错误渲染为一个标题标签：

最终，在文章标题下方正确显示了字数统计和阅读时长信息。
![wordcount](../../../../images/screenshot/2025-06-13_11-18_wordcount.png)

二、原因分析

这一问题的根本原因在于 Markdown 渲染器（如 hexo-renderer-marked 或 markdown-it）在处理文字段落紧跟图片的语法时，某些情况下可能会将其视为同一个段落，并错误地转换为标题。

特别是在前一行末尾为句号或中文符号，下一行又是图片语法（![...](...)），更容易被误判。

三、解决办法

✅ 方法一：添加空行

最简单直接的方式是在文字和图片之间添加空行：

最终，在文章标题下方正确显示了字数统计和阅读时长信息。

![wordcount](../../../../images/screenshot/2025-06-13_11-18_wordcount.png)

这样就能明确告诉 Markdown 渲染器，两者为独立段落，避免误合并。

✅ 方法二：使用 HTML 显式结构

如果你希望行为更可控，也可以使用 HTML 标签来书写：

<p>最终，在文章标题下方正确显示了字数统计和阅读时长信息。</p>
<p><img src="/images/screenshot/2025-06-13_11-18_wordcount.png" alt="wordcount"></p>

适用于结构化或需要稳定渲染效果的写作场景。

四、推荐做法

如果你经常写文章涉及图片展示，建议：

• 保持图片前后有空行，避免粘连；
• 为每段落标题单独一行，加空行隔开；
• 避免中文段落结尾紧贴 Markdown 图片语法；
• 也可视情况用 HTML 标签规避解析器差异。

五、总结

Markdown 的“简洁”语法有时也容易出现歧义。在 Hexo + Volantis 环境中，特别是涉及插件渲染和主题模板的场景，更需要小心结构布局。希望本文对你遇到类似问题时有所帮助。

---

如果你在 Hexo 使用过程中也遇到其他类似问题，欢迎留言交流 🙌。