足迹页面使用指南：地图、后台与迁移脚本

2026-07-11

博客指南

足迹

地图

高德地图

GitHub Gist

博客

浏览量加载中...

AI 摘要

足迹页面功能概览#

足迹页面（/life/places/）以高德地图为核心，直观展示我去过的所有地方。主要功能包括：

智能标记聚类：地图缩小时自动将相近的标记聚合为圆形数字标记，放大后展开为独立标记
区域高亮联动：点击标记时自动高亮对应省份区域，支持切换高亮模式
分类筛选：左上角分类列表根据标签自动生成，点击可筛选不同类别的地点
信息弹窗：点击任意标记展示地点名称、日期、描述、照片等信息
主题适配：地图自动跟随博客明暗主题切换
响应式设计：适配桌面和移动端

本地数据格式#

足迹数据以 Markdown 文件存储在 src/content/life/places/ 目录下，使用 YAML frontmatter 定义字段：

1
---
2
date: 2026-01-30
3
province: 河南
4
city: 商丘
5
experience: 去睢县和宝宝见面了，玩的非常开心
6
visitCount: 99
7
lat: 34.460852
8
lng: 115.071786
9
url: https://trae.io
10
urlLabel: 游记
11
photos:
12
  - https://synyan.cn/wp-content/uploads/cities/beijing.jpg
13
tags:
14
  - 去过
15
  - 探亲
16
---

字段说明#

字段	类型	必填	说明
`date`	日期	是	到访日期
`province`	字符串	是	省份
`city`	字符串	是	城市
`experience`	字符串	否	体验描述
`visitCount`	数字	否	到访次数，默认 1
`lat`	数字	是	纬度
`lng`	数字	是	经度
`url`	字符串	否	相关链接
`urlLabel`	字符串	否	链接显示文字
`photos`	数组	否	照片 URL 列表
`tags`	数组	否	标签，如「去过」「探亲」「学校」等

没有 lat 和 lng 的地点不会显示在地图上，但仍会出现在地点列表中。

足迹管理后台#

访问方式#

在浏览器中打开 /admin/places/ 即可进入足迹管理后台。

功能介绍#

1. Token 设置#

页面顶部是 GitHub Token 输入框，用于将足迹数据同步到 Gist 暂存库。需要一个包含 gist 权限的 Personal Access Token，输入后点击「保存 Token」即可，Token 会保存在浏览器 localStorage 中。

2. 创建足迹#

填写以下信息：

省份 / 城市：地点的基本信息
详细地址：用于自动获取坐标（支持村庄等小地点）
获取坐标：点击按钮调用高德地图 API 自动填充经纬度
日期 / 到访次数：到访时间和次数
体验描述：简短记录这次出行的感受
标签：添加分类标签（如「去过」「探亲」「学校」）
照片：添加照片 URL

点击「保存」后，数据会直接写入 Gist 暂存库。

3. 管理已有足迹#

页面底部展示 Gist 中所有暂存足迹，支持编辑和删除操作。

坐标获取#

后台集成了高德地图地理编码服务，支持两种方式获取坐标：

自动获取：填写省份、城市和详细地址后点击「获取坐标」按钮，系统会依次尝试地理编码和 POI 搜索
手动获取：如果自动获取失败，可使用高德坐标拾取器手动查找坐标后填入

需要在高德开放平台为 API Key 开通「Web服务 API」权限，地理编码接口才能正常工作。

Gist 暂存机制#

足迹后台采用「暂存库」设计：

后台添加的数据保存在 GitHub Gist 中，不会直接显示在博客页面上
博客页面只读取本地 src/content/life/places/ 目录下的 Markdown 文件
这种设计让你出门在外时可以随时用手机或电脑通过后台快速记录足迹，回家后再统一迁移到本地

Gist 中的数据格式与本地 frontmatter 完全一致：

1
{
2
  "id": "p-1783767954393",
3
  "province": "河南",
4
  "city": "商丘",
5
  "lat": "34.460852",
6
  "lng": "115.071786",
7
  "experience": "去睢县和宝宝见面了",
8
  "visitCount": 99,
9
  "date": "2026-01-30",
10
  "tags": ["去过", "探亲"],
11
  "url": "https://trae.io",
12
  "urlLabel": "游记",
13
  "photos": ["https://example.com/photo.jpg"],
14
  "markerColor": "sunset"
15
}

其中 id 和 markerColor 是内部字段，迁移时会自动忽略。

迁移脚本#

功能#

scripts/MigrationFootprint/index.js 脚本将 Gist 中的暂存足迹数据一键迁移为本地 Markdown 文件。

使用方法#

在项目根目录执行：

1
# 迁移全部数据（默认迁移后清空 Gist 中已迁移的数据）
2
node scripts/MigrationFootprint/index.js
3

4
# 仅预览，不写入文件也不删除 Gist 数据
5
node scripts/MigrationFootprint/index.js --dry-run
6

7
# 迁移后保留 Gist 数据（不清空）
8
node scripts/MigrationFootprint/index.js --keep-gist

脚本行为#

从 Gist 读取暂存足迹数据（无需 Token）
逐条转换为 Markdown 文件，写入 src/content/life/places/ 目录
自动按「日期 + 省份 + 城市」去重，避免重复迁移
同日期不同地点的文件自动追加序号（如 2026-07-11-2.md）
迁移完成后可选择清空 Gist 中的已迁移数据（清空操作需要 Token）

Token 配置#

读取 Gist 数据使用公开 URL，无需 Token。清空 Gist 数据需要 Token，按以下优先级读取：

环境变量 GITHUB_TOKEN
配置文件 src/config/externalPlacesConfig.ts 中的 githubToken 字段
项目根目录 .env 文件中的 GITHUB_TOKEN

输出示例#

1
╔══════════════════════════════════════╗
2
║   足迹 Gist → 本地 Markdown 迁移    ║
3
╚══════════════════════════════════════╝
4

5
Gist 中共有 3 条足迹数据
6

7
✓ 2026-07-11  河南 · 商丘
8
✓ 2026-07-10  河南 · 安阳
9
✓ 2026-07-09  北京 · 朝阳
10

11
正在清空 Gist 中已迁移的 3 条数据...
12

13
════════════════════════════════════════
14
迁移完成
15
  迁移成功: 3 条
16
  跳过重复: 0 条
17
  Gist 剩余: 0 条
18
════════════════════════════════════════