给 Hexo 博客加一张足迹地图：hexo-post-map 使用指南

技术
, , ,
AI文章摘要 本文介绍 hexo-post-map 0.7.0 的安装与使用，包括高德地图配置、单地点与行程标注、本地地图选点助手、GPX/GeoJSON 真实轨迹、足迹总览的恢复与分享，以及 PJAX 接入和常见问题排查。
  1. 断桥残雪

旅行文章写得越来越多以后，我一直想给博客增加一个更直观的浏览方式：读者不仅能看到文章列表，还能从地图上知道这些故事发生在哪里，同一次旅行经过了哪些地方。

为此，我在博客中接入了 hexo-post-map。它可以给单篇文章添加地点或行程地图，也可以自动生成一张汇集全站游记的“足迹地图”。本文记录插件的主要功能、实际使用效果和完整配置步骤。

这次把指南更新到 0.7.0，对应 2026 年 10 月 13 日发布的正式版本。除了最初的地点和行程示意线，现在还可以导入真实轨迹、分享地图视角，以及用本地选点助手生成文章需要的 YAML。下文示例按这个版本核对，版本变化可以查看官方更新记录。

插件能做什么

hexo-post-map 是一款面向 Hexo 静态博客的地理信息插件。目前使用高德 JS API 2.0，适合游记、城市记录、徒步、骑行、音乐节等带有明确地点的内容。

它主要提供以下功能：

  1. 在文章中展示地图：地图卡片可以出现在正文前、正文后，或通过标签插入指定位置。
  2. 支持单个或多个地点：一篇文章既可以只标记一座城市，也可以展示景点、车站、餐厅等多个点位。
  3. 绘制行程示意线：按照地点顺序连接路线，并用编号显示途经地点，也能表达 A → B → A 这样的往返行程。
  4. 展示真实轨迹：读取本地 GPX 或 GeoJSON，支持首尾隐私裁剪、轨迹统计和手动播放。
  5. 生成全站足迹地图：插件会为所有带地理信息的文章生成独立地图页面，并根据缩放级别自动聚合文章。
  6. 继续探索和分享：总览可以恢复最近视角、分享当前地图和文章预览，也可以按需开启“随机一站”。
  7. 辅助作者选点：0.7.0 新增本地地图选点助手，可以搜索地点、点击地图或手动输入坐标，再导出 map: YAML。
  8. 展示文章缩略图：优先使用文章的 thumbnail，也可以从正文图片或 Live Photo 的静态图中自动选择。
  9. 适配不同设备和主题：支持移动端文章抽屉、深色模式、减少动态效果、底图样式和常规 PJAX 页面切换。
  10. 构建时校验配置：坐标、地点 ID、代表地点和路线引用有误时，构建过程会直接指出对应文章和字段。

实际使用效果

单篇文章地图

地图

文章设置地理信息后，正文附近会出现一张高度较小的地图卡片，不会过多挤占阅读空间。

单地点文章显示一个定位图钉；多地点文章会自动调整视野，把所有地点放入可见区域。如果设置了路线，路线中的地点会按访问顺序编号并用直线连接。点击图钉可以查看地点名称。

这里的 route 连线用于表达“先去了哪里、再去了哪里”，不是高德导航规划出来的道路或徒步轨迹。有实际记录文件时，可以另外使用下文的 track 展示走过的路线。

全站足迹地图

地图

插件会生成 /map/ 页面，并把每篇地图文章的代表地点显示在同一张地图上。缩放较小时，相邻文章会合并为聚合圆；继续放大后，会展开为带缩略图的文章标记。

点击单篇文章标记可以预览标题、日期和地点，点击聚合点则会继续放大或打开文章列表。在手机上，文章列表会显示为底部抽屉。

这篇文章最初发布时，博客共有 40 篇文章，其中 26 篇已经标注地理信息，共包含 50 个地点和 11 条行程路线。原本分散在归档页面里的旅行记录，现在可以沿着地图重新浏览。上面的截图保留当时的展示效果，新增功能以下文配置为准。

准备工作

插件当前要求：

  • Node.js 20 或更高版本
  • Hexo 7 或 Hexo 8
  • 高德开放平台的 Web 端（JS API）Key
  • 地点标注使用 GCJ-02 坐标；可选的 GPX/GeoJSON 轨迹使用 WGS84 坐标

需要注意，高德控制台中的 Key 类型应选择 Web 端（JS API），而不是“Web 服务”。新申请的 JS API Key 还需要配合安全密钥或安全代理使用。

第一步：安装插件

进入 Hexo 博客根目录，执行：

1
npm install hexo-post-map@0.7.0

安装完成后，可以在 package.json 的依赖中看到 hexo-post-map。仅安装依赖不会自动启用地图，还需要继续配置站点。

已有博客也可以用这条命令升级。如果原来的版本范围是 ^0.6.0，需要显式安装 0.7.0，单独执行 npm update 不会跨到 0.7。原有地点、路线、真实轨迹和高德配置可以继续使用；升级后按第七步重新构建和发布。

第二步：申请高德地图 Key

  1. 登录高德开放平台控制台。
  2. 进入“应用管理”，创建一个应用。
  3. 在应用中添加 Key，服务平台选择“Web 端（JS API）”。
  4. 保存生成的 Key 和安全密钥 securityJsCode。
  5. 根据实际部署地址设置可使用的域名。

如果只是个人博客，可以先使用客户端安全密钥完成配置；如果对安全边界有更高要求，可以根据高德官方文档部署安全代理。

第三步：配置 Hexo

编辑博客根目录下的 _config.yml，注意不是主题目录中的配置文件。加入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
post_map:
  enabled: true
  provider: amap
  post:
    enabled: true
    position: before
    height: 220px
    default_zoom: 11
  overview:
    enabled: true
    path: map/
    title: 足迹地图
    layout: page
    exploration:
      restore: true
      share: true
      random: false
  cluster:
    grid_size: 60
    max_zoom: 18
  amap:
    key: replace-with-your-web-key
    map_style: normal
    security:
      security_js_code: replace-with-your-security-js-code

上面的 Key 和安全密钥都是占位符，需要替换为自己在高德控制台申请的内容。

几个常用选项的含义如下：

  • post.position：文章地图的位置，可选 before、after 或 manual。
  • post.height：桌面端文章地图的高度。
  • overview.path：足迹地图的访问路径，默认是 /map/。
  • overview.layout：优先使用主题的页面布局；设置为 standalone 可以使用插件自带的独立页面。
  • overview.exploration：分别控制返回恢复、地图分享和随机预览，具体效果见第六步。
  • cluster.grid_size：文章聚合的屏幕距离，单位为像素。
  • cluster.max_zoom：足迹地图允许聚合和展开的最大缩放级别。
  • amap.map_style：底图样式，默认 normal，也可设为 dark、light 等高德官方样式，或已发布的 amap://styles/… 自定义样式地址。

这些开关需要填写 YAML 布尔值 true、false，不要加引号。修改底图样式同样需要重新构建。

如果博客源码是公开仓库，不建议把真实凭据提交进去。可以将 amap 保留为空对象，并在构建环境中设置变量：

1
2
3
post_map:
  # 其余配置保持不变
  amap: {}
1
2
3
4
export HEXO_POST_MAP_AMAP_KEY='replace-with-your-web-key'
export HEXO_POST_MAP_AMAP_SECURITY_JS_CODE='replace-with-your-security-js-code'
npx hexo clean
npx hexo generate

环境变量能避免凭据进入源码仓库，但 Web Key、客户端安全密钥和文章坐标最终仍会发送到浏览器，不能把它们当作私密数据。生产环境也可以改用 HEXO_POST_MAP_AMAP_SERVICE_HOST 配置安全代理，但客户端安全密钥和安全代理只能选择一种。

第四步：给文章添加地理信息

地图信息写在文章顶部的 YAML Front Matter 中。手写 map.points 时，插件不会根据地点名称自动查询或转换坐标，需要填写 GCJ-02 坐标。也可以先用下面的本地助手选点，再把导出的配置放进文章。

用本地地图选点助手生成配置

0.7.0 起，在博客根目录可以运行：

1
npx hexo post-map-editor --open --port 4001

它会启动独立的本地编辑服务，不需要先运行 hexo server。--open 用于打开浏览器；省略后，可以自己打开终端打印的完整会话地址。默认仅监听 127.0.0.1:4001，端口被占用时可以改成 --port 4003。

整理一篇游记时，我会按这个顺序操作：

  1. 搜索地名并按回车或点击“搜索”；也可以点击地图，或者手动填写 GCJ-02 坐标。城市留空时搜索全国，填写后可限定范围。
  2. 检查候选地点的名称和位置，再点击“确认添加地点”。选择搜索结果只是填入候选，不会直接加入文章；添加后还可以拖动图钉微调。
  3. 在“地点”页签整理名称和代表地点，在“线路”页签按途经顺序加入地点。同一个地点可以重复经过，调整地点列表顺序不会改动线路顺序。
  4. 校验通过后复制或下载 map: YAML，粘贴到文章 Front Matter。已有配置也可以只取 map: 这一块导入，继续修改。

助手沿用站点的高德 Web Key、安全模式和环境变量；地点搜索只在明确提交时请求高德，仍受账号权限和额度限制。没有配置 Key 或地图暂时加载失败时，也可以继续手动编辑和导出。

它不会直接保存文章，也不会生成、上传博客。草稿只存在当前页面内存中，刷新或关闭前一定要先导出。 已有的 track 配置会作为只读内容保留，助手不会读取、编辑或预览轨迹文件。

终端地址中的 #session=… 用于本次本地服务读取地图配置，请不要分享给别人，也不要只打开不带会话片段的首页。编辑完成后按 Ctrl+C 停止服务，再次启动时使用新地址。更多操作细节见0.7.0 官方使用说明。

标记单个地点

适合城市记录、演出、展览或只涉及一个主要地点的文章：

1
2
3
4
5
6
7
8
9
10
11
---
title: 魔都
thumbnail: https://example.com/shanghai.jpg
map:
  zoom: 11
  points:
    - id: shanghai
      name: 上海
      longitude: 121.4737
      latitude: 31.2304
---

当文章只有一个地点时，这个地点会自动成为全站足迹地图中的代表位置。

标记多个地点

一篇文章包含多个景点，但不需要表达访问顺序时，可以只设置点位：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
title: 衢州一日游
map:
  representative: old-city
  points:
    - id: old-city
      name: 衢州古城
      longitude: 118.8739
      latitude: 28.9570
    - id: museum
      name: 衢州市博物馆
      longitude: 118.8762
      latitude: 28.9551
---

多地点文章必须使用 representative 指定一个代表地点。全站地图只使用这个代表地点定位文章，但文章详情地图会展示全部地点。

添加行程路线

如果文章需要体现旅行、徒步或骑行的先后顺序，可以增加 route：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
---
title: 武功山真的很美
map:
  representative: summit
  points:
    - id: visitor-center
      name: 武功山游客中心
      longitude: 114.1501
      latitude: 27.4682
    - id: cableway
      name: 一级索道
      longitude: 114.1623
      latitude: 27.4741
    - id: summit
      name: 武功山金顶
      longitude: 114.1735
      latitude: 27.4568
  route:
    - visitor-center
    - cableway
    - summit
---

route 中填写的是 points 已有的地点 ID，顺序就是地图中的编号和连线顺序。没有写进 route 的地点仍会显示，只是不会参与连线。

地点 ID 只能使用小写英文字母、数字和单个连字符，例如 west-lake。经纬度必须是数字，不能写成带引号的字符串。

添加 GPX 或 GeoJSON 真实轨迹

route 适合交代行程顺序；如果手上有徒步、骑行等实际记录文件，可以增加 track。下面是配置模板，需要先准备自己的 walk.md 和轨迹文件，并替换地点坐标：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
title: 一次步行记录
map:
  points:
    - id: public-square
      name: 公开集合点
      longitude: 118.7977
      latitude: 32.0872
  track:
    source: ./tracks/walk.gpx
    privacy:
      trim_start_meters: 300
      trim_end_meters: 300
    simplify_tolerance_meters: 5
    playback: true
---

如果文章是 source/_posts/walk.md，这里的文件路径就是 source/_posts/tracks/walk.gpx。插件只接受位于 Hexo source_dir 内的文章相对本地文件，不支持远程 URL、绝对路径或越过源码目录的路径。

地点与轨迹使用的坐标系需要分清：points 仍然必填并使用 GCJ-02，轨迹文件使用 WGS84，显示时再转换到高德地图。GPX 需要 1.1 格式，命名空间为 http://www.topografix.com/GPX/1/1，数据放在 trk → trkseg → trkpt 中；仅有航点或 rte 路线不能作为真实轨迹。

也可以把 source 换成自己的 .geojson 或 GeoJSON .json 文件。线型几何支持 LineString、MultiLineString 及相应容器，坐标顺序为 [经度, 纬度, 可选海拔]；单纯的点或面不会被当作轨迹。至少要有一段包含两个位置不同的有效点。每个源文件最多 8 MiB、200,000 个原始点，最终发布的轨迹最多 2,000 个点。

首尾裁剪的单位是米，默认都为 0；示例中的 300 需要根据真实路线长度和隐私需要调整，裁剪后仍要保留有效线段。构建时先裁剪，再计算统计和简化，距离、累计爬升与时长会在对应数据可用时显示。轨迹不会自动播放，读者可以播放、暂停和拖动进度；playback: false 则只展示完整轨迹，不显示播放控件。系统开启“减少动态效果”时仍可手动拖动进度，但连续播放和重新播放不可用。

处理后的文件会生成到 hexo-post-map/tracks/<sha256>.json。插件不会发布原始 GPX/GeoJSON、原始时间戳和附加元数据；这些公开轨迹只由文章详情地图按需加载，总览依然只使用文章代表地点。轨迹加载失败时保留地点，如果配置了 route，还会退回行程示意线。

裁剪不能让路线完全匿名，轨迹形状、附近地标和手写地点仍可能暴露位置。发布前我会一起检查代表地点、全部 points 和裁剪后的轨迹，而不只检查原始文件是否被隐藏。字段规则可以查阅轨迹 Front Matter 参考。

第五步：控制地图出现的位置

默认的 position: before 会把地图放在正文前。设置为 after 后，地图会出现在正文末尾。

如果想自己决定具体位置，可以将配置改为：

1
2
3
post_map:
  post:
    position: manual

然后在文章正文中插入：

1
{% post_map %}

每篇文章最多使用一次这个标签。即使关闭文章详情地图，已经标注的文章仍然可以出现在全站足迹地图中。

第六步：添加足迹地图入口

插件会生成地图页面，但不会自动修改主题导航。需要根据主题的配置方式，把 /map/ 添加到菜单中。

如果 Hexo 配置了 root: /blog/，最终地址会是 /blog/map/，但 overview.path 仍然只写 map/，不需要重复添加站点根路径。

返回恢复、分享地图和随机一站

前面的 overview.exploration 配置控制这三项功能，restore 和 share 默认开启，random 默认关闭：

  • 返回恢复：同一标签页中，离开总览去读文章，再返回时可以恢复最近的地图视角和文章面板；常规 PJAX 切换或刷新也能恢复，有效期为两小时。它不会跨设备同步，浏览器禁用会话存储时，恢复范围会退回当前页面文档。
  • 分享地图：地图加载后，点击“分享地图”复制当前视角；如果正在预览一篇文章，链接也会包含该文章引用。聚合组和全部文章列表只分享视角。剪贴板不可用时会显示可手动复制的链接框，有效分享链接优先于本地保存的视角。
  • 随机一站：把 random 改成 true 后，读者可以随机打开一篇地图文章的预览；它不会自动跳转文章，也不会开始播放轨迹。

三个开关相互独立，例如关闭 restore 仍能使用分享。分享链接面向公开浏览，会暴露视角和文章引用，但不包含高德凭据或轨迹内容；这与本地选点助手的会话地址是两种不同用途的链接。

PJAX 主题如何接入

从 0.4.0 起，插件会在启用后的页面中注入轻量运行时，常规主题通过 PJAX 插入或替换普通 DOM 内容时，会自动初始化、清理地图，地图资源和高德 SDK 仍按需加载。

如果主题需要手动接入，可以在新内容插入、运行时加载后调用：

1
2
3
if (window.HexoPostMap?.apiVersion === 1) {
  window.HexoPostMap.refresh(document);
}

也可以将 document 换成这次插入的容器，移除前按需调用 window.HexoPostMap.destroy(container)。这两个方法立即返回，不表示地图已经加载完成。特殊 Shadow DOM、跨文档内容或只改 URL 而不替换地图节点的路由，需要主题自行处理，具体边界见兼容性说明。

第七步：构建并预览

本地预览可以执行：

1
2
npx hexo clean
npx hexo server

确认文章地图和 /map/ 页面正常后，再生成用于部署的静态文件：

1
2
npx hexo clean
npx hexo generate

修改 Key、安全模式、点位或地图配置后，都需要重新构建。如果使用对象存储和 CDN，要重新上传 public/，让新 HTML、map/posts.json 与 hexo-post-map/ 资源一起更新，并刷新相关缓存，避免旧页面混用新脚本。已经发布过真实轨迹时，旧哈希文件应保留到旧 HTML 和缓存切换完成，避免旧页面的轨迹突然失效。

常见问题

地图没有出现

检查以下内容：

  • post_map.enabled 是否为布尔值 true。
  • 文章是否包含合法的 map.points。
  • 使用 manual 模式时，正文中是否插入了 {% post_map %}。
  • 当前主题是否正常渲染文章内容。

页面空白或高德地图加载失败

确认 Key 的服务平台是 Web 端（JS API），部署域名符合高德控制台限制，并且只配置了一种安全模式。修改配置后应重新构建；如果 SDK 加载超时，还需要刷新页面重试。

构建时报地点或路线错误

插件会严格校验 Front Matter。多地点文章必须设置 representative，路线只能引用本文已经声明的地点 ID，同一篇文章中的 ID 不能重复。根据错误信息中的文章路径和字段修正即可。

坐标显示偏移

先确认填的是地点还是轨迹。map.points 按 GCJ-02 使用，不会替手写坐标转换；原始 GPS 点需要先确认坐标系。track 的 GPX/GeoJSON 则要求 WGS84，由显示环节转换，不能把两种输入要求混用。

找不到本地助手命令，或打开后没有地图

先用 npm ls hexo-post-map 确认实际安装的是 0.7.0 或更新版本，并在博客根目录运行 npx hexo post-map-editor。0.6.x 没有这个命令。打开时使用终端完整地址，检查高德 Key 与安全模式；地图失败仍可手动填坐标并导出，草稿不会自动保存。

轨迹构建失败

检查文件相对路径、GPX namespace 或 GeoJSON 线型是否正确，确认文件没有超出大小或点数限制，首尾裁剪后仍剩有效轨迹。错误会指出文章和相关字段，原始轨迹格式不能仅靠改后缀转换。

隐私位置是否适合标注

文章详情会公开全部地点坐标，足迹地图也会公开代表地点；使用 track 时还会公开处理后的轨迹。家庭住址、临时住所等敏感位置应改用城市中心、公共地标或主动降低精度后的坐标，轨迹则需要单独检查与裁剪。

总结

hexo-post-map 把传统的文章归档变成了一张可以探索的旅行足迹。对作者来说，只需要在 Front Matter 中维护结构化地点；对读者来说，则多了一种按照空间而不是时间浏览内容的方式。

现在写新游记时，可以继续手写地点，也可以用本地助手生成配置；有真实记录时再补充 track，没有记录时保留简单的行程示意线就够了。更完整的配置、安全说明和后续版本变化，可以查看 hexo-post-map 项目仓库。