--- title: Obsidian Maps 瓦片代理总结与使用指南 type: reference created: 2026-04-10 tags: - wiki - tools/obsidian - tools/map - project/完成 - type/指南 para: - resources source: '[[Obsidian Maps瓦片代理总结与使用指南]]' description: 本地瓦片代理方案总结：解决 Obsidian Maps 无法直接加载腾讯/高德瓦片的问题 categories: - '[[LLM Wiki]]' --- # Obsidian Maps 瓦片代理总结与使用指南 > [!abstract] 一句话总结 > 通过本地 Node.js 代理（端口 18090），透明解决腾讯地图 Y 轴翻转 + MapLibre `{-y}` 不支持查询参数的问题，让 Obsidian Maps 可以加载腾讯矢量、高德卫星、ESRI 卫星、腾讯路况四种瓦片。 --- ## 一、问题背景 Obsidian Maps（官方插件 v0.1.6）使用 MapLibre GL 渲染地图，支持自定义瓦片 URL。但在国内使用时遇到三个核心问题： | # | 问题 | 原因 | | ---| ------|------| | 1 | 腾讯矢量瓦片加载后地图空白 | 腾讯 Y 轴编号与标准 TMS 相反（从上往下 vs 从下往上） | | 2 | MapLibre `{-y}` 翻转不生效 | MapLibre 的 `{-y}` 只支持**路径格式**（`/{z}/{x}/{y}.png`），不支持**查询参数格式**（`?z=&x=&y=`） | | 3 | 腾讯卫星底图不可用 | 腾讯 `/sateTiles` 接口已下线，`styleid=0` 返回的仍是矢量图 | > [!failure] 直接配置腾讯 URL 的结果 > `http://rt0.map.gtimg.com/tile?z={z}&x={x}&y={-y}&styleid=1` > → MapLibre 不会把 `{-y}` 替换为翻转坐标，而是发送字面量 `{-y}`，服务器返回 400 Bad Request。 --- ## 二、解决方案：本地瓦片代理 ### 架构 ``` Obsidian Maps (MapLibre) 本地代理 (Node.js) 瓦片服务器 | | | | GET /tile?z=13&x=6745 | | | &y=3124&type=vector | | | ──────────────────────────> | | | | Y翻转: 3124 → 5067 | | | GET rt0.../tile? | | | z=13&x=6745&y=5067 | | | &styleid=1 | | | ────────────────────────> | | | 200 + JPEG 7KB | | | <──────────────────────── | | 200 + JPEG 7KB | | | <────────────────────────── | | ``` ### Y 轴翻转公式 $$y_{腾讯} = 2^z - 1 - y_{TMS}$$ | TMS y | z=13 翻换后 | 说明 | |-------|------------|------| | 0 | 8191 | 最北行 | | 3124 | 5067 | 故宫附近 | | 8191 | 0 | 最南行 | ### 代理代码位置 - **代理脚本**：`tools/tile-proxy.js` - **调试工具**：`tools/map-tile-debugger.html` - **静默启动**：`tools/tile-proxy-silent.vbs` - **开机自启安装**：`tools/install-proxy-startup.ps1` --- ## 三、可用瓦片源 | type 参数 | 名称 | 上游服务器 | Y轴翻转 | 缓存 | 单瓦片大小 | |-----------|------|-----------|---------|------|-----------| | `vector` | 腾讯矢量 | rt0/1/2.map.gtimg.com | ✅ 是 | 24h | ~7KB | | `sate` | 高德卫星影像 | wprd01/02.is.autonavi.com | ❌ 否 | 24h | ~11KB | | `esri` | ESRI World Imagery | server.arcgisonline.com | ❌ 否 | 24h | ~20KB | | `traffic` | 腾讯路况 | rt0.map.gtimg.com | ✅ 是 | 24h | ~5KB | ### URL 格式 ``` http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=<类型> ``` ### 卫星源说明 > [!warning] 腾讯卫星不可用 > 腾讯 `/sateTiles` 接口已下线，`styleid=0` 返回的仍是矢量渲染图。替代方案： > - **高德卫星**（`type=sate`）：中国区域优化，加载快，标注清晰 > - **ESRI World Imagery**（`type=esri`）：全球覆盖，分辨率高，文件稍大 --- ## 四、Obsidian Maps 配置 ### 配置文件 `.obsidian/plugins/maps/data.json` ```json { "tileSets": [ { "id": "tencent-vector", "name": "腾讯矢量", "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=vector", "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=vector" }, { "id": "gaode-satellite", "name": "高德卫星影像", "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=sate", "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=sate" }, { "id": "esri-imagery", "name": "ESRI World Imagery", "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=esri", "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=esri" }, { "id": "tencent-traffic", "name": "腾讯路况", "lightTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=traffic", "darkTiles": "http://127.0.0.1:18090/tile?z={z}&x={x}&y={y}&type=traffic" }, { "id": "openfreemap-bright", "name": "OpenFreeMap 亮色", "lightTiles": "https://tiles.openfreemap.org/styles/bright", "darkTiles": "https://tiles.openfreemap.org/styles/dark" } ] } ``` ### tileSet 结构说明 | 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 唯一标识符 | | `name` | string | 显示名称（在 Maps 背景选择器中可见） | | `lightTiles` | string | 亮色模式瓦片 URL（支持逗号分隔多个） | | `darkTiles` | string | 暗色模式瓦片 URL（为空时回退到 lightTiles） | > [!tip] Maps 插件识别逻辑 > `isTileTemplateUrl()` 检查 URL 是否包含 `{z}`、`{x}` 或 `{y}`。 > - **包含** → 当作 raster 瓦片模板，MapLibre 自动替换坐标 > - **不包含** → 当作 Style JSON URL，直接 fetch 获取完整样式定义 > 查询参数格式 `?z={z}&x={x}&y={y}` 完全支持。 --- ## 五、日常使用指南 ### 启动代理 代理已配置为**开机自启**（Windows 启动目录快捷方式 → VBS 静默脚本）。 手动操作： ```powershell # 检查代理是否运行 curl http://127.0.0.1:18090/status # 手动启动（前台调试） node D:\TC_UP\2023card\tools\tile-proxy.js 18090 # 手动启动（后台静默） Start-Process node -ArgumentList "D:\TC_UP\2023card\tools\tile-proxy.js","18090" -WindowStyle Hidden ``` ### 在 Obsidian 中使用地图 1. 打开或创建一个 `.base` 文件 2. 添加 Map 视图（视图类型选 "Map"） 3. 确保笔记有 `location` 属性（经纬度，如 `location: [39.9042, 116.4074]`） 4. 在地图左上角切换背景图层 ### 调试工具 浏览器打开 `tools/map-tile-debugger.html`，可逐一测试各瓦片源是否正常加载。 ### 代理状态检查 ```powershell # 状态端点 curl http://127.0.0.1:18090/status # 返回: {"status":"ok","sources":["vector","traffic","gaode_sate","esri","sate"],"port":18090} # 测试单个瓦片 curl -o test.jpg http://127.0.0.1:18090/tile?z=14&x=13509&y=6218&type=vector ``` --- ## 六、排障指南 | 症状 | 可能原因 | 解决方法 | |------|---------|---------| | 地图全空白 | 代理未启动 | `curl http://127.0.0.1:18090/status` 检查 | | 腾讯矢量偏移到海洋 | Y 轴未翻转 | 确认用的是代理 URL（`127.0.0.1:18090`）而非直连 | | 卫星图显示矢量 | 用了腾讯 styleid=0 | 改用 `type=sate`（高德卫星）或 `type=esri` | | ESRI 返回 500 | ESRI URL 顺序错误 | ESRI 用 `/{z}/{y}/{x}`，不是 `/{z}/{x}/{y}` | | 瓦片加载慢 | 网络问题 | 代理有 8s 超时，多后端自动轮询 | | 插件设置里看不到背景 | data.json 未生效 | 重载插件：设置 → 关闭 Maps → 重新开启 | --- ## 七、技术细节 ### 瓦片源上游 URL | 类型 | 上游 URL 格式 | 备注 | |------|-------------|------| | 腾讯矢量 | `http://rt{0-2}.map.gtimg.com/tile?z={z}&x={x}&y={flippedY}&styleid=1&scene=0` | Y需翻转 | | 高德卫星 | `https://wprd{01-02}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&style=6&x={x}&y={y}&z={z}` | 标准TMS | | ESRI 卫星 | `https://server.arcgisonline.com/…/World_Imagery/MapServer/tile/{z}/{y}/{x}` | z/y/x顺序 | | 腾讯路况 | `http://rt0.map.gtimg.com/tile?z={z}&x={x}&y={flippedY}&styleid=4` | Y需翻转 | ### 腾讯 styleid 含义 | styleid | 内容 | 用途 | |---------|------|------| | 1 | 矢量底图 | ✅ 日常使用 | | 2 | 深色底图 | 暗色模式 | | 3 | 标注层 | 叠加用 | | 4 | 路况 | 实时路况 | | 6/7 | 其他渲染风格 | 不常用 | ### 代理功能 - **多后端轮询**：腾讯 rt0/1/2 自动轮询，分散请求 - **自动降级**：首选后端失败时自动尝试下一个 - **CORS 支持**：`Access-Control-Allow-Origin: *` - **缓存头**：`Cache-Control: public, max-age=86400`（24小时） - **图片验证**：检查返回数据是否以 JPEG/PNG 魔数开头 --- ## 八、文件清单 | 文件 | 位置 | 用途 | |------|------|------| | 瓦片代理 | `tools/tile-proxy.js` | 核心代理服务 | | 调试工具 | `tools/map-tile-debugger.html` | 浏览器内瓦片测试 | | 静默启动 | `tools/tile-proxy-silent.vbs` | 无窗口启动代理 | | 自启安装 | `tools/install-proxy-startup.ps1` | 创建开机自启快捷方式 | | 插件配置 | `.obsidian/plugins/maps/data.json` | Maps 插件瓦片背景配置 | --- > [!quote] 项目时间线 > - **2026-04-10**：从问题发现 → 代理开发 → 配置完成，耗时约3小时 > - 核心发现：MapLibre `{-y}` 不支持查询参数格式，这是整个问题的根源 ## 来源 > **溯源规则**：所有数字/百分比/具体结论必须标注 `[raw:{文件名}:{行号}]` 格式。 - [[Obsidian Maps瓦片代理总结与使用指南]]