Hexo外挂标签指南：从入门到精通，让你的博客“活”起来
🌟 写在前面：为什么要用外挂标签？
如果你用过Hexo一段时间，大概会发现一个问题：用Markdown写文章，有些东西就是搞不定。
想插入一段音乐？想放个B站视频？想让图片在首页也能正常显示？Markdown语法表示：臣妾做不到啊。
这时候就需要请出今天的主角——Hexo外挂标签（Tag Plugins）。
简单来说，外挂标签是Hexo提供的一种特殊语法，让你可以在Markdown文章里插入那些“普通Markdown搞不定”的东西。它们长得像这样：
1 | {% 标签名 参数 %} |
看起来有点像代码块，但渲染出来就是各种炫酷的效果。
看起来有点像代码块，但渲染出来就是各种炫酷的效果。
作为一个爱折腾的射手座，我把Hexo常用的外挂标签都摸了一遍。今天这篇教程，就从最基础的资产标签讲起，再到音乐、视频、代码块，最后到那些能让你博客“开挂”的第三方插件。
跟着这篇教程走，保证你能把Hexo的外挂标签玩得明明白白。 🌿
📦 第一章：准备工作——让Hexo认识外挂标签
1.1 外挂标签从哪来？
Hexo的外挂标签主要有两种来源：
| 来源类型 | 说明 | 例子 |
|---|---|---|
| 内置标签 | Hexo核心自带，装了Hexo就能用 | asset_img, blockquote, code |
| 第三方插件 | 需要额外安装的社区插件 | hexo-tag-aplayer, hexo-tag-bilibili |
1.2 内置标签：零配置直接使用
内置标签不需要任何安装配置，只要你的Hexo版本在3.0以上（现在应该没人用更老的版本了吧），直接在文章里写就能用。
1.3 第三方插件：按需安装
第三方插件需要用npm安装。以音乐插件为例：
1 | npm install --save hexo-tag-aplayer |
安装完成后，有些插件需要在_config.yml里做简单配置，具体看插件文档。后面讲到具体插件时我会详细说。
🖼️ 第二章：资产标签——解决图片显示的世纪难题
2.1 为什么需要资产标签？
这是Hexo新手最容易踩的坑。
如果你在文章里放了一张图片，用Markdown语法引用。在文章页面看是正常的，但一回到首页——图片裂了。
为什么？因为首页的文章摘要里，图片路径解析错了。
Hexo官方提供了三种资产标签来解决这个问题：
| 标签 | 作用 | 示例 |
|---|---|---|
asset_path |
获取资产文件的路径 | {% asset_path example.jpg %} |
asset_img |
插入图片 | {% asset_img example.jpg 图片描述 %} |
asset_link |
插入文件下载链接 | {% asset_link example.pdf 点击下载 %} |
2.2 开启文章资源文件夹
要使用资产标签，必须先开启文章资源文件夹功能。在博客根目录的_config.yml里找到或添加这一行：
1 | post_asset_folder: true |
开启后，以后每次用hexo new "文章标题"创建新文章时，Hexo会自动创建一个与文章同名的文件夹。比如你创建hexo-new-标签教程.md，就会自动生成一个hexo-new-标签教程文件夹。
把图片放进去，结构是这样的：
1 | source/ |
2.3 asset_img 标签使用详解
基本语法：
示例：
渲染结果（首页和文章页都能正常显示）：
1 | <img src="/2026/03/14/hexo-new-标签教程/example.jpg" alt="这是一张示例图片"> |
带空格的文件名：
如果文件名或描述里有空格，要用引号括起来：
2.4 偷懒大法：不用标签也能用Markdown插图片
如果你嫌写{% asset_img %}太麻烦，Hexo 3.1.0以上版本提供了一个更优雅的方案。
在_config.yml里添加以下配置：
1 | post_asset_folder: true |
配置完成后，你就可以直接在文章里用普通的Markdown语法引用图片了：
Hexo会自动把它解析成正确的文章路径。这才是广东人说的“懒人有懒福”。
🎵 第三章：音乐标签——让博客会唱歌
3.1 安装音乐插件
Hexo官方推荐的音乐插件是hexo-tag-aplayer，基于APlayer播放器，支持MetingJS从各大音乐平台获取歌单。
bash
1 | npm install --save hexo-tag-aplayer |
安装完成后，在博客根目录的_config.yml里添加配置：
1 | # aplayer |
然后在主题的配置文件中引入必要的CSS和JS文件（不同主题位置不同，一般在custom_css和custom_js处添加）：
1 | custom_css: |
3.2 meting 标签语法
hexo-tag-aplayer提供了meting标签，可以从网易云、腾讯、虾米等平台插入音乐。
基本语法：
1 | {% meting 歌曲ID 平台 类型 [参数] %} |
参数说明：
| 参数 | 默认值 | 说明 |
|---|---|---|
id |
必须值 | 歌曲ID / 歌单ID / 专辑ID / 搜索关键词 |
server |
必须值 | 音乐平台：netease(网易云), tencent(腾讯), kugou(酷狗), xiami(虾米), baidu(百度) |
type |
必须值 | 类型：song(歌曲), playlist(歌单), album(专辑), search(搜索), artist(歌手) |
theme |
#ad7a86 |
播放器主题色 |
mutex |
true |
是否开启互斥模式（同时只能播放一首） |
preload |
auto |
预加载：none, metadata, auto |
autoplay |
false |
是否自动播放（移动端不支持） |
loop |
all |
循环模式：all(全部循环), one(单曲循环), none(不循环) |
order |
list |
播放顺序：list(列表顺序), random(随机) |
volume |
0.7 |
音量，0-1之间 |
3.3 常用示例
插入单首歌曲（网易云，歌曲ID：190378164）：
插入歌单（腾讯音乐，歌单ID：7724497259）：
插入歌手热门歌曲（网易云，歌手ID：2116）：
3.4 创建专属音乐页面
如果你想做一个专门的音乐页面：
1 | hexo new page music |
然后在source/music/index.md里写：
1 | --- |
最后在主题菜单里加上这个页面的链接，你的博客就有专属音乐厅了。
🎬 第四章：视频标签——让博客变成小影院
4.1 内置视频标签
Hexo内置了几个视频平台的标签：
| 标签 | 说明 | 示例 |
|---|---|---|
youtube |
插入YouTube视频 | {% youtube video_id %} |
vimeo |
插入Vimeo视频 | {% vimeo video_id %} |
YouTube示例：
1 | {% youtube dQw4w9WgXcQ %} |
4.2 B站视频插件
国内用户最常用的当然是B站。安装hexo-tag-bilibili插件：
1 | npm install --save hexo-tag-bilibili |
使用方法：
1 | {% bilibili BV号 [高度] [宽度] %} |
示例：
也可以指定尺寸：
📝 第五章：文本排版标签——让文章更有层次
5.1 块引用（blockquote）
内置的blockquote标签可以让引用更规范：
基本语法：
text
1 | {% blockquote [作者] [来源] %} |
示例：
死并非生的对立面，而是作为生的一部分永存。
5.2 代码块（code）
虽然Markdown本身支持代码块，但Hexo的code标签提供了更多功能：
1 | {% code [语言] [标题] %} |
示例：
1 | function hello() { |
5.3 链接标签（link）
link标签可以创建指向文章或外部链接的链接：
1 | {% link 文字 URL [标题] %} |
示例：
📊 第六章：数据可视化标签——让博客会说话
6.1 安装图表插件
如果你想让博客更有“技术范儿”，可以试试hexo-graph插件，它基于ECharts，可以生成各种统计图表：
1 | npm install --save hexo-graph |
6.2 支持的图表类型
| 图表类型 | 说明 | 用途 |
|---|---|---|
| 热力图 | 显示发文频率的时间分布 | 分析写作习惯 |
| 月度统计 | 每月发文数量趋势 | 观察创作节奏 |
| 分类统计 | 文章分类占比 | 了解内容分布 |
| 标签统计 | 标签使用频率 | 发现热门话题 |
6.3 使用示例
在文章中插入热力图：
1 | <div class="hexo-graph-heatmap"></div> |
插入分类统计：
1 | <div class="hexo-graph-categories"></div> |
这些图表会自动读取你博客的数据，生成可视化统计，特别适合写在“关于我”或者“年度总结”这类文章里。
🎨 第七章：进阶玩法——让标签“开挂”
7.1 Stellar主题的宝藏标签
如果你用的是Stellar主题（一个超强大的Hexo主题），那你简直是挖到宝了。它内置了海量的标签组件，而且可以互相嵌套混搭。
Stellar的标签包括：
- 提示框：
{% note %} - 时间线：
{% timeline %} - 折叠块：
{% fold %} - 标签页：
{% tabs %} - 按钮：
{% button %} - 标签组：
{% taggroup %}
具体用法可以看Stellar的官方文档，这里就不展开了，只能说：如果你追求极致的排版效果，Stellar值得拥有。
7.2 自定义标签样式
如果你用的是Butterfly等热门主题，也可以通过修改样式文件来让标签更炫酷。有技术大佬分享过如何把标签改成源计划-方舟风格——金属质感边框、发光特效、动态悬浮，像存储卡一样。
虽然这已经超出“外挂标签”的范畴，属于主题改造了，但如果你感兴趣，可以搜索“Butterfly主题 标签改造”之类的关键词。
🐛 第八章：常见问题解答
❓ Q1：为什么我的asset_img图片还是不显示？
可能原因：
post_asset_folder: true没开启- 图片没放在正确的同名文件夹里
- 文件名大小写写错了
- 用了Markdown语法但没配置
prependRoot
解决方法：对照第二章一步步检查。
❓ Q2：音乐播放器显示不出来？
可能原因：
- 插件没安装成功
- CSS/JS没引入
- 歌单ID填错了
- 音乐平台限制了外链
解决方法：
- 确认
npm list | grep aplayer能看到插件 - 检查主题配置文件里的
custom_css和custom_js - 先用单曲测试，排除歌单问题
❓ Q3：标签插件和Markdown语法混用会冲突吗？
不会冲突。Hexo会先解析标签插件，再渲染Markdown。除非你在front-matter里设置了disableNunjucks: true，那样会禁用所有Nunjucks标签（包括标签插件）。
❓ Q4：怎么知道有哪些第三方插件可用？
去Hexo官网的插件页面（hexo.io/plugins/），有500多个插件分类展示。可以按功能搜索，比如想找评论插件就搜“comment”，想找图片就搜“image”。
🌈 写在最后：标签是工具，内容是灵魂
写完这篇长文，窗外广东的天已经黑了。
回想起自己刚开始折腾Hexo的时候，也被图片显示问题困扰过，也为怎么插入音乐发愁过。后来一个个标签摸过来，才发现：原来Hexo比我想象的要强大得多。
外挂标签这东西，说到底是工具。工具的意义不是让你炫技，而是让你能更自由地表达。
想放一段音乐，就能放；想插个视频，就能插；想让首页图片不裂开，就能不裂开。工具服务于表达，表达服务于内容——这才是外挂标签存在的意义。
希望这篇教程能帮你把Hexo玩得更顺手。过程中遇到任何问题，欢迎来评论区留言。我会像广东阿妈煲汤一样，慢慢给你解答——火候不到不揭盖，问题没解决不罢休。
那么，快去给你的博客加点“外挂”吧！ 🌟
📚 附录：常用标签速查表
| 标签 | 用途 | 来源 | 示例 |
|---|---|---|---|
{% asset_img %} |
插入图片 | 内置 | {% asset_img photo.jpg 我的照片 %} |
{% asset_link %} |
插入下载链接 | 内置 | {% asset_link file.pdf 下载文档 %} |
{% meting %} |
插入音乐 | 第三方 | {% meting "190378164" "netease" "song" %} |
{% youtube %} |
插入YouTube视频 | 内置 | {% youtube dQw4w9WgXcQ %} |
{% bilibili %} |
插入B站视频 | 第三方 | {% bilibili BV1xx411c7mH %} |
{% blockquote %}` | 块引用 | 内置 | `{% blockquote 作者 %}内容{% endblockquote %} |
|||
{% code %}` | 代码块 | 内置 | `{% code lang:js %}代码{% endcode %} |
|||
{% link %} |
链接 | 内置 | {% link 文字 url %} |
[王の言]
2026年3月14日
广东，窗外有风，耳机里有歌
