giteahh/llm_wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f21c3a1662657dc97e67d77bc833ade62e1b46e9
llm_wiki/wiki/Obsidian Maps瓦片代理总结与使用指南.md
T

9.7 KiB
Raw Blame History

title, type, created, tags, para, source, description, categories
title type created tags para source description categories
Obsidian Maps 瓦片代理总结与使用指南 reference 2026-04-10
wiki
tools/obsidian
tools/map
project/完成
type/指南
resources
Obsidian Maps瓦片代理总结与使用指南 本地瓦片代理方案总结：解决 Obsidian Maps 无法直接加载腾讯/高德瓦片的问题
LLM Wiki

Obsidian Maps 瓦片代理总结与使用指南

[!abstract] 一句话总结 通过本地 Node.js 代理（端口 18090），透明解决腾讯地图 Y 轴翻转 + MapLibre {-y} 不支持查询参数的问题，让 Obsidian Maps 可以加载腾讯矢量、高德卫星、ESRI 卫星、腾讯路况四种瓦片。

一、问题背景

Obsidian Maps（官方插件 v0.1.6）使用 MapLibre GL 渲染地图，支持自定义瓦片 URL。但在国内使用时遇到三个核心问题：

| # | 问题 | 原因 |
------
1
2
3

[!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

{
  "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 静默脚本）。

手动操作：

# 检查代理是否运行
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，可逐一测试各瓦片源是否正常加载。

代理状态检查

# 状态端点
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:{文件名}:{行号}] 格式。

Reference in New Issue View Git Blame Copy Permalink