🌟 写在前面：为什么要用外挂标签？ 如果你用过Hexo一段时间，大概会发现一个问题：用Markdown写文章，有些东西就是搞不定。 想插入一段音乐？想放个B站视频？想让图片在首页也能正常显示？Markdown语法表示：臣妾做不到啊。 这时候就需要请出今天的主角——Hexo外挂标签（Tag Plugins）。 简单来说，外挂标签是Hexo提供的一种特殊语法，让你可以在Markdown文章里插入那些“普通Markdown搞不定”的东西。它们长得像这样： {% 标签名 参数 %} 看起来有点像代码块，但渲染出来就是各种炫酷的效果。 看起来有点像代码块，但渲染出来就是各种炫酷的效果。 作为一个爱折腾的射手座，我把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安装。以音乐插件为例： 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里找到或添加这一行： post_asset_folder: true 开启后，以后每次用hexo new "文章标题"创建新文章时，Hexo会自动创建一个与文章同名的文件夹。比如你创建hexo-new-标签教程.md，就会自动生成一个hexo-new-标签教程文件夹。 把图片放进去，结构是这样的： source/ _posts/ hexo-new-标签教程.md hexo-new-标签教程/ example.jpg background.png 2.3 asset_img 标签使用详解 基本语法： {% asset_img 文件名 [图片描述] %} 示例： {% asset_img example.jpg 这是一张示例图片 %} 渲染结果（首页和文章页都能正常显示）： <img src="/2026/03/14/hexo-new-标签教程/example.jpg" alt="这是一张示例图片"> 带空格的文件名： 如果文件名或描述里有空格，要用引号括起来： {% asset_img "my example.jpg" "This is my example" %} 2.4 偷懒大法：不用标签也能用Markdown插图片 如果你嫌写{% asset_img %}太麻烦，Hexo 3.1.0以上版本提供了一个更优雅的方案。 在_config.yml里添加以下配置： post_asset_folder: true marked: prependRoot: true postAsset: true 配置完成后，你就可以直接在文章里用普通的Markdown语法引用图片了： Hexo会自动把它解析成正确的文章路径。这才是广东人说的“懒人有懒福”。 🎵 第三章：音乐标签——让博客会唱歌 3.1 安装音乐插件 Hexo官方推荐的音乐插件是hexo-tag-aplayer，基于APlayer播放器，支持MetingJS从各大音乐平台获取歌单。 bash npm install --save hexo-tag-aplayer 安装完成后，在博客根目录的_config.yml里添加配置： aplayer: meting: true asset_inject: false 然后在主题的配置文件中引入必要的CSS和JS文件（不同主题位置不同，一般在custom_css和custom_js处添加）： custom_css: - //cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.css custom_js: - //cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.js - //cdn.jsdelivr.net/gh/metowolf/MetingJS@1.2/dist/Meting.min.js 3.2 meting 标签语法 hexo-tag-aplayer提供了meting标签，可以从网易云、腾讯、虾米等平台插入音乐。 基本语法： {% meting 歌曲ID 平台 类型 [参数] %} 参数说明： 参数默认值说明 id必须值歌曲ID / 歌单ID / 专辑ID / 搜索关键词 server必须值音乐平台：netease(网易云), tencent(腾讯), kugou(酷狗), xiami(虾米), baidu(百度) type必须值类型：song(歌曲), playlist(歌单), album(专辑), search(搜索), artist(歌手) theme#ad7a86播放器主题色 mutextrue是否开启互斥模式（同时只能播放一首） preloadauto预加载：none, metadata, auto autoplayfalse是否自动播放（移动端不支持） loopall循环模式：all(全部循环), one(单曲循环), none(不循环) orderlist播放顺序：list(列表顺序), random(随机) volume0.7音量，0-1之间 3.3 常用示例 插入单首歌曲（网易云，歌曲ID：190378164）： {% meting "190378164" "netease" "song" "theme:#3F51B5" "mutex:true" "preload:auto" %} 插入歌单（腾讯音乐，歌单ID：7724497259）： {% meting "7724497259" "tencent" "playlist" "theme:#3F51B5" "mutex:true" "preload:auto" %} 插入歌手热门歌曲（网易云，歌手ID：2116）： {% meting "2116" "netease" "artist" "theme:#3F51B5" "mutex:true" "preload:auto" %} 3.4 创建专属音乐页面 如果你想做一个专门的音乐页面： hexo new page music 然后在source/music/index.md里写： --- title: 我的歌单 date: 2026-03-14 --- {% meting "7724497259" "tencent" "playlist" "theme:#3F51B5" "mutex:true" "preload:auto" %} 最后在主题菜单里加上这个页面的链接，你的博客就有专属音乐厅了。 🎬 第四章：视频标签——让博客变成小影院 4.1 内置视频标签 Hexo内置了几个视频平台的标签： 标签说明示例 youtube插入YouTube视频{% youtube video_id %} vimeo插入Vimeo视频{% vimeo video_id %} YouTube示例： {% youtube dQw4w9WgXcQ %} 4.2 B站视频插件 国内用户最常用的当然是B站。安装hexo-tag-bilibili插件： npm install --save hexo-tag-bilibili 使用方法： {% bilibili BV号 [高度] [宽度] %} 示例： {% bilibili BV1xx411c7mH %} 也可以指定尺寸： {% bilibili BV1xx411c7mH 500 800 %} 📝 第五章：文本排版标签——让文章更有层次 5.1 块引用（blockquote） 内置的blockquote标签可以让引用更规范： 基本语法： text {% blockquote [作者] [来源] %} 引用内容 {% endblockquote %} 示例： {% blockquote 村上春树 《挪威的森林》 %} 死并非生的对立面，而是作为生的一部分永存。 {% endblockquote %} 5.2 代码块（code） 虽然Markdown本身支持代码块，但Hexo的code标签提供了更多功能： {% code [语言] [标题] %} 代码内容 {% endcode %} 示例： {% code lang:javascript 示例代码 %} function hello() { console.log("Hello, Hexo!"); } {% endcode %} 5.3 链接标签（link） link标签可以创建指向文章或外部链接的链接： {% link 文字 URL [标题] %} 示例： {% link 我的关于页面 /about 了解博主 %} 📊 第六章：数据可视化标签——让博客会说话 6.1 安装图表插件 如果你想让博客更有“技术范儿”，可以试试hexo-graph插件，它基于ECharts，可以生成各种统计图表： npm install --save hexo-graph 6.2 支持的图表类型 图表类型说明用途 热力图显示发文频率的时间分布分析写作习惯 月度统计每月发文数量趋势观察创作节奏 分类统计文章分类占比了解内容分布 标签统计标签使用频率发现热门话题 6.3 使用示例 在文章中插入热力图： <div class="hexo-graph-heatmap"></div> 插入分类统计： <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 %} Damon_Zhang 2026年3月14日 广东，窗外有风，耳机里有歌
Hexo外挂标签指南：从入门到精通，让你的博客“活”起来
笔记