常见问题
先按眼前的现象找答案。挑一个最接近的小标题，再顺着链接去看对应功能。如果这里都没有， 最后一节列出了报告问题时需要带上的信息。
地图上什么都没有
Section titled “地图上什么都没有”Obsidian 提示要启用内置的 Maps 插件
Section titled “Obsidian 提示要启用内置的 Maps 插件”Advanced Maps 扩展第一方 Maps 视图，而不是自带一个，所以那个视图必须存在。三件事 一起检查：Obsidian 1.13.1 或更高版本、启用 Bases、安装并启用第一方 Maps 插件。 Obsidian 加载完成后，如果这个视图仍未注册，提示会出现一次；控制台会留下更具体的 “built-in Maps view is not registered”警告。见 快速开始。
Base 确实是地图视图，但画不出东西
Section titled “Base 确实是地图视图，但画不出东西”先查 Base：地图上的图钉、轨迹和照片，都来自它返回的结果。
| 检查什么 | 在哪里看 |
|---|---|
| 筛选器有没有返回结果？ | 视图名旁边的结果计数 |
| 笔记有没有坐标？ | 地图视图的 Marker coordinates 选项指定属性 |
| 那个属性真的是坐标吗？ | 39.9042, 116.4074——一对数，按这个顺序 |
筛选器没有匹配到文件时，地图会保持空白，也不会报错；这是正常结果。 快速开始里有一份完整的 Base，可以复制过来对照。
一篇笔记出现两张地图
Section titled “一篇笔记出现两张地图”嵌入和链接是两件事，区别全在那个 ! 上：
| 笔记里写的 | 在 Base 地图上画轨迹 | 在笔记里生成地图 |
|---|---|---|
![[route.gpx]] |
会 | 会 |
[[route.gpx]] |
会 | 不会 |
track: "[[route.gpx]]"（属性） |
会 | 不会 |
所以一篇已经出现在 Base 地图上、自己又渲染出一张地图的笔记，写的是嵌入。把 ! 去掉，
轨迹照样画在这篇笔记出现的每一张地图上，笔记里不再多出第二张。
轨迹摘要和高程剖面也属于内联地图，改成普通链接后，笔记里就不再显示它们。要么保留嵌 入，要么用把轨迹数据写进属性把数据写进笔记自己的属性。见 轨迹与区域。
画出来了，但不对
Section titled “画出来了，但不对”图钉只有实心圆，没有图标，或者颜色很奇怪
Section titled “图钉只有实心圆，没有图标，或者颜色很奇怪”这两种情况通常都说明值无效，而且都不会报错：
- 只有实心圆、没有图标，说明 Lucide 里没有这个图标名。名字必须和 Lucide 自己 的拼写完全一致。
- 图钉是主题的文字颜色——浅色主题下接近黑，深色主题下接近白——说明这个颜色 CSS 解析不了。
属性缺失和属性写错是两回事：什么属性都没有时，你得到的是默认小圆点和默认蓝色。见 图钉图标与颜色。
图钉落在离马路几条街的地方
Section titled “图钉落在离马路几条街的地方”底图和保存的坐标用了不同的坐标系。国内服务商发布的是 GCJ-02 或 BD-09；你的库里存 的是 WGS-84，也就是 GPS、手机照片和 GPX 文件记录下来的坐标。
要改的是地图的瓦片坐标系（或插件的默认坐标系），不是笔记里的数字。转换只发生在 地图边界上，读出来、复制出去、写回去的值始终是 WGS-84。见 坐标与地图服务。
照片在 Base 里，但地图上没有它
Section titled “照片在 Base 里，但地图上没有它”只有可读的 GPS 标签才产生位置，插件绝不编造。没有标签的照片仍然是 Base 结果，只是地图 上没有东西；有标签但缩略图不可用的照片，仍然会有一个圆点。
整个相册都不见的话，先确认显示照片已经打开，文件是 JPG、JPEG、PNG、WebP、 HEIC、HEIF 或 AVIF，再确认目录在库内、并且被 Obsidian 索引到了。见 照片地图。
清空照片索引之后，地图没有变化
Section titled “清空照片索引之后，地图没有变化”这是正常现象。清空照片索引只会丢弃为以后启动保存的派生元数据，不会刷新已经打开 的地图，也不会改动照片；之后需要这些数据时，索引会重新生成。如果照片被其他程序修改 后 Obsidian 没有发现，可以先清空索引，再重新加载库。见 照片地图。
命令或菜单项不见了
Section titled “命令或菜单项不见了”先看功能开关。凡是会进入现有菜单、地图或文件类型的功能，都可以整项关闭；菜单项、相 关命令和后台工作会一起停下，但原来的配置仍会保留。 参考与隐私里的表列了全部七个，以及每个带走 什么。
使用离线底图是唯一默认关闭的开关；升级时如果检测到已经配好的瓦片包，则会自动 打开。
「在地图中打开」提示要先指定 Base 文件
Section titled “「在地图中打开」提示要先指定 Base 文件”在地图中打开需要知道打开哪个 Base。在设置 → 第三方插件 → Advanced Maps → 在地图 中打开里指定 Base 文件；Base 里不止一个视图的话，再指定视图名称。这个命令的 其他提示会直接说出它找不到什么：路径不存在、Base 里没有这个视图名，或者这个 Base 的视 图没有一个是地图。见周围视图与导航。
「把轨迹数据写进属性」不见了，或者什么都没写
Section titled “「把轨迹数据写进属性」不见了，或者什么都没写”只有当前打开的是 Markdown 笔记，并且能解析到至少一个支持的轨迹文件，这个命令才会出 现在面板里。命令不见时，先检查笔记里的轨迹链接。命令运行后没有写入，提示会说明原因； 常见的是：
- 没有开启任何数据项——设置 → 第三方插件 → Advanced Maps → 轨迹 → 轨迹属性里一 项都没选，也就没有东西可写。
- 没有可测量的轨迹数据——链接的文件里没有可以统计的路线数据。
读取失败或属性名冲突，也会在修改笔记之前直接提示。以后成功运行时，某个已开启的数据项 如果算不出来，它原来的属性会被删除；已关闭的数据项和其他属性不受影响。见 轨迹与区域。
底图、搜索和定位
Section titled “底图、搜索和定位”离线瓦片画不出来
Section titled “离线瓦片画不出来”按顺序检查：
- 使用离线底图是关的。除非你之前就配过瓦片包，否则它默认关。
- 路径写成了 URL，或者缺少
{z}、{x}、{y}（或{-y}）。请填写包含真实文件扩 展名的文件系统路径模板，URL 由插件自己生成。 - 瓦片不在这台设备上。手机拿到桌面端的绝对路径时，只会在背景色上画出你自己的图钉，而 且什么都不说——路径是通的，只是那里没有瓦片。
- 最低层级和最高层级没有对上瓦片包里最小和最大的
z目录。
见离线底图，那里也讲了把十万个瓦片挡在库索引之外的两种放法。
地点搜索要求填 key，或者直接失败
Section titled “地点搜索要求填 key，或者直接失败”高德需要 Web 服务 key：在设置 → 第三方插件 → Advanced Maps → 地点搜索里填写， 或者换成不需要 key 的 OpenStreetMap（Nominatim）。失败提示会带上插件收到的原因。
Nominatim 每秒允许一次请求；搜索框和反向地理编码命令共用这段间隔，所以搜索有时会稍 等一下，而不是直接失败。见 坐标与地图服务。
设备定位一直没有结果
Section titled “设备定位一直没有结果”这件事由操作系统回答——插件既没有 key，也没有自己的服务。如果还没拿到过定位，就遇到 权限被拒、设备没有定位服务，或首次请求失败，提示会说明原因，并暂停本次启动内的自动填 写；成功定位过之后，偶发失败不会停掉后续尝试。手动执行用当前定位填写坐标可以解除 暂停。定位权限要在 Obsidian 和操作系统里处理，不在本插件的设置里。见 坐标与地图服务。
Advanced Maps 在 Obsidian 移动端支持同样的地图功能，但有两个实际差别：
- **指南里提到的手势。**写着右键的地方，在手机上是长按。
- **指向库外相册的目录链接。**那是桌面文件系统的做法；手机不能复用桌面端建的链接，桌 面端的瓦片路径拿到手机上也会指向手机没有的瓦片。
每一页都会在讲到某个功能的地方说明平台限制；手机端的概览见 快速开始。
请提交 issue，并带上：
- Obsidian 版本和 Advanced Maps 版本；
- 你期待地图上出现什么，实际出现的是什么；
- Base 的筛选器，以及地图视图用的坐标属性；
- 地图的截图，以及那个画不出来的笔记或文件；请先遮掉隐私内容；
- 如果弹过提示，控制台里的相关输出。
把地图和生成它的笔记或文件放在一起看，通常很快就能找到原因。