Hexo Butterfly 主题添加 clustrmaps 访客地图教程

一、前言

本文是针对 Hexo Butterfly 主题的美化教程，核心是为个人博客添加 clustrmaps 访客地图。教程部分部署过程中可能出现的问题，适合刚上手的用户参考.

二、前置步骤（获取 clustrmaps 地图代码）

1. 注册账号

访问 clustrmaps 官网（https://clustrmaps.com/），完成账号注册或登录操作。

2. 选择地图工具

点击官网中 Free Tools 下 Website Map Widget 对应的 “Get Map Widget” 选项。

3. 输入博客网址

在跳转页面的地址输入框中，粘贴自己的博客完整网址（例如：https://XXXXXX.github.io/），然后点击 “Next”。

4. 选择地图模板

提供两种模板可选：Map widget 和 Globe Widget beta，选择喜欢的模板后点击 “Select”。

5. 复制核心代码

生成 widget 代码后，提取<script>标签中src="XXXXXXXX"双引号内的链接内容，用记事本临时保存。

三、代码插入与配置（博客端操作）

1. 新建 card_map.pug 文件

• 路径：themes\Butterfly\layout\includes\widget
• 新建文件命名为card_map.pug，写入以下代码并粘贴保存的 src 链接：

.card-widget.card-map
  .card-content
    .item-headline
      i.fa.fa-globe-asia(aria-hidden="true")
      span= _p('aside.card_map')
    script#clstr_globe(type="text/javascript" defer="defer" src="此处填入你自己的src链接")

2. 修改 index.pug 文件

• 路径：themes\Butterfly\layout\includes\widget
• 编辑index.pug，插入以下代码（建议按教程位置插入，也可调整顺序改变侧边栏显示顺序）：
• 

!=partial('includes/widget/card_map', {}, {cache: true})

• 核心说明：index.pug 中代码位置的优先级高于配置文件，直接影响地图在侧边栏的显示位置。

3. 配置 butterfly.yml 文件

• 路径：Hexo 根目录下_config.butterfly.yml
• 
• 在card_webinfo配置项下方添加以下代码，启用地图功能：

card_map:
  enable: true
  sort_order:

• 说明：sort_order 置空时默认按代码顺序排序。

4. 修改语言配置文件

• 路径：themes\Butterfly\languages\zh-CN.yml（根据网站实际语言选择对应文件）

  

• 找到card_announcement: 公告，在其下方添加：

card_map: 访客地图

• 备注：“访客地图” 文本可根据需求自定义修改。

四、最终效果

配置完成后，执行hexo clean、hexo g、hexo s命令启动本地服务，即可在博客侧边栏看到实时显示全球访客位置的地图组件。