Hexo + Fluid 中使用选项卡（Tabs）踩坑记录

本文介绍如何在 Hexo + Fluid 主题下，为文章添加选项卡（Tabs）。➡️

1. 问题背景：想在 Hexo 中实现选项卡效果

在写一篇博客时，我想做一个 中英文对照的选项卡，效果是：

这里是中文内容。

Here is English content.

在 https://homulilly.com/post/hexo-use-note-and-tabs-block.html 给出的教程中，需要在 Hexo 的 Markdown 里写类似如下语法：

1
2
3
4
5
6
7
8
9
10
11
{% tabs 语言切换，1 %}

<!-- tab 中文 -->
这里是中文内容。
<!-- endtab -->

<!-- tab English -->
Here is English content.
<!-- endtab -->

{% endtabs %}

于是我直接在文章里加上上述 tabs 语法，准备 hexo g 一把梭，结果直接 FATAL。

2. 报错现象：unknown block tag: tabs

在博客根目录下执行：

1
hexo g

报错如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
Nunjucks Error: _posts/编程/python/CvxPy.md [Line 70, Column 109] unknown block tag: tabs
    =====               Context Dump               =====
    === (line number probably different from source) ===
  65 | </blockquote>
  66 | <hr>
  67 | <h2 id="2-常见的求解器类型"><a href="#2-常见的求解器类型" class="headerlink" title="2. 常见的求解器类型"></a>2. 常见的求解器类型</h2><blockquote>
  68 | <p>使用方式统一是：<br><code>prob.solve(solver=cp.XXX, 参数名=...)</code><br>下面“常用参数”里提到的名字，都是可以直接写在 <code>solve()</code> 里的 keyword 参数。</p>
  69 | </blockquote>
  70 | <h3 id="2-1-常见开源求解器"><a href="#2-1-常见开源求解器" class="headerlink" title="2.1. 常见开源求解器"></a>2.1. 常见开源求解器</h3>{% tabs 语言切换 %}
  71 |
  72 | <!-- tab 中文 -->
  73 | 这里是中文内容。
  74 | <!-- endtab -->
  75 |
    =====             Context Dump Ends            =====

关键信息只有一句话： > unknown block tag: tabs

翻译成人话就是：模板引擎 Nunjucks 看到了 {% tabs ... %}，但它完全不认识这个标签，没有任何插件/主题帮它注册过一个叫 tabs 的 block，因此直接抛错。

3. 第一次误解：以为是“插件没装好”

一开始 GPT 给出的解决思路是：

  1. 网上很多 tabs 教程都是 配合 Butterfly 主题 使用的；

  2. 这些教程会提示安装一个插件，比如 hexo-butterfly-tag-plugins-plus；

  3. 然后在 _config.yml 中加入类似下面的配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# tag-plugins-plus 
# see https://akilar.top/posts/615e2dec/
tag_plugins:
  enable: true        # 开关
  priority: 5         # 过滤器优先级，数值越小越早执行
  issues: false       # issues 标签开关，不用可以先关掉
  link:
    placeholder: /img/link.png   # link_card 默认图标，可以先随便写个路径
  CDN:
    anima: https://npm.elemecdn.com/hexo-butterfly-tag-plugins-plus@latest/lib/assets/font-awesome-animation.min.css
    jquery: https://npm.elemecdn.com/jquery@latest/dist/jquery.min.js
    issues: https://npm.elemecdn.com/hexo-butterfly-tag-plugins-plus@latest/lib/assets/issues.js
    iconfont: //at.alicdn.com/t/font_2032782_8d5kxvn09md.js
    carousel: https://npm.elemecdn.com/hexo-butterfly-tag-plugins-plus@latest/lib/assets/carousel-touch.js
    tag_plugins_css: https://npm.elemecdn.com/hexo-butterfly-tag-plugins-plus@latest/lib/tag_plugins.css

结果无论怎么改，hexo g 依然报 unknown block tag: tabs。

4. 关键点：主题不一样，插件语法也未必通用

后来理了一下：

  • hexo-butterfly-tag-plugins-plus 是 围绕 Butterfly 主题设计的外挂标签插件；

  • 它依赖 Butterfly 的结构和脚本，虽然理论上可以在别的主题里用，但教程都是基于 Butterfly 编写的；

  • 而我当前的主题是 Fluid，Fluid 本身并不内置 {% tabs %} 这个标签；

  • 我一边用着 Fluid，一边照着 Butterfly 的玩法去装插件、写 {% tabs %}，自然是各种不匹配。

换句话说：

  • 标签语法 {% tabs %} 不是 Hexo 核心功能；

  • 是“主题 + 某个特定插件”组合出来的；

  • 不同主题的 tabs 语法未必一样，有的主题根本就没有 tabs。

真正的需求其实很简单：

我只需要一个“和主题无关”的通用选项卡插件，让任何主题都能用 {% tabs %}。

5. 真正的解决方案：使用通用插件 hexo-tag-common

最后采用的方案是：

使用 和主题无关的通用标签插件 —— hexo-tag-common， 它提供了 tabs 功能，而且不依赖于 Butterfly、Fluid 等特定主题。

5.1 安装 hexo-tag-common

在博客根目录下执行：

1
2
3
4
5
6
7
cd D:\github\03-blog\myblog

# 清理之前装错的 Butterfly 插件（可选）
npm uninstall hexo-butterfly-tag-plugins-plus --save

# 安装通用标签插件
npm install hexo-tag-common --save

5.2 修改根 _config.yml 配置（注意：不是 _config.fluid.yml）

在 站点根目录 的 _config.yml 中添加如下配置（可以替换掉之前的 tag_plugins 配置）：

1
2
3
4
5
6
7
# hexo-tag-common 通用标签插件
tag_common:
  cdn: https://fastly.jsdelivr.net/npm/   # 默认 CDN，照抄即可
  layout:
    - post
    - page
    # - home   # 如果希望首页也启用标签解析，可以把这一行的注释去掉

5.3 在 Markdown 中使用 hexo-tag-common 的 Tabs 语法

1
2
3
4
5
6
7
8
9
10
{% tabs 语言切换，1 %}      # 语言切换：这一组 tabs 的名字，用来标识一整块选项卡； 1：默认选中第几个 tab（从 1 开始计数）；

<!-- tab 中文 -->          # Tab 标签标题；每个 tab 用 HTML 注释写
这里是中文内容。
<!-- endtab -->

<!-- tab English -->
Here is English content.
<!-- endtab -->
{% endtabs %}              # Tab 结束标记。

5.4 重新生成博客

完成上述修改后，在根目录重新生成：

1
2
3
hexo clean
hexo g
hexo s

然后浏览器访问： http://localhost:4000 ，找到对应的文章，就可以看到“语言切换”的选项卡效果了。

6. 顺便说说 VS Code 预览为什么看不到 tabs 效果

  • VS Code 的 Markdown 预览只渲染 标准 Markdown 语法；

  • {% tabs %}、{% xxx %} 这类是 Hexo 标签插件语法，属于生成阶段的东西；

  • Hexo 在 hexo g / hexo s 阶段才会把这些标签解析成 HTML + JS + CSS；

  • 也就是说：

    • VS Code 只会显示“源代码”（包含 {% tabs %} 这些标记）；

    • 真正的 tabs UI 要看 Hexo 生成后的网页。

所以：

  • VS Code 中看不到选项卡，是正常现象；

  • 真正的效果必须在 http://localhost:4000 或部署后的博客站点上查看。

7. 这次踩坑的几个小总结

  1. 报错信息要看懂关键字

    • unknown block tag: tabs 的意思就是：

      模板引擎压根不认识 tabs 这个标签；

    • 不是“语法写错一点点”，而是“压根没人注册这个标签”。

  2. 主题 + 插件要匹配

    • 网上很多 tabs 教程都是基于 Butterfly 主题；

    • 我实际使用的是 Fluid；

    • 盲目照搬 Butterfly + hexo-butterfly-tag-plugins-plus 的配置，基本就是“南辕北辙”。

  3. 通用插件更适合多主题场景

    • 如果不想绑死在某个主题上，可以优先找 和主题无关的通用插件；

    • 这次解决方案就是：Fluid + hexo-tag-common。

  4. 配置文件位置要分清楚

    • Hexo 全局配置：_config.yml（站点根目录）；

    • 主题配置：_config.<theme>.yml（例如 _config.fluid.yml）；

    • 插件的配置一般写在 根 _config.yml 中，而不是写在主题配置里。

  5. VS Code 预览只当“编辑器”，不要拿它当“最终效果”

    • 带 {% xxx %} 的标签插件语法，预览不了是正常的；

    • 只要 hexo g 没报错，浏览器里看到的才是最终效果。

8. 用 tab 的其他踩坑经验总结

  1. 如果在一篇博客中使用多组 tabs，每组 tabs 的名字（{% tabs 页面内不重复的ID，1 %} 中的“页面内不重复的ID”）要不一样，否则插件会把它们当成同一个选项卡组来处理，导致后面的 tab 内容识别不完整。
编程 > Web
#github pages #fluid #Hexo #tabs
Hexo + Fluid 中使用选项卡（Tabs）踩坑记录
https://nanana-szz.github.io/02-hexo_tab/
作者
John Doe
发布于
2025年12月1日
许可协议