giteahh/llm_wiki

Fork 0

Files

T

giteahh 407a9213bf feat(vault): Phase 3 tools + batch citation/relation enrichment

2026-07-01 15:20:40 +08:00

9.7 KiB

Raw Permalink Blame History

title, type, created, tags, para, source, description, categories

title

type

created

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 中使用地图

打开或创建一个 .base 文件
添加 Map 视图（视图类型选 "Map"）
确保笔记有 location 属性（经纬度，如 location: [39.9042, 116.4074]）
在地图左上角切换背景图层

调试工具

浏览器打开 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:{文件名}:{行号}] 格式。

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

9.7 KiB Raw Permalink Blame History Unescape Escape