hehaiguang1123
a6f05ab2d5
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
265 lines
9.5 KiB
Markdown
265 lines
9.5 KiB
Markdown
---
|
||
title: Obsidian Maps 瓦片代理总结与使用指南
|
||
type: reference
|
||
created: 2026-04-10
|
||
tags:
|
||
- tools/obsidian
|
||
- tools/map
|
||
- project/完成
|
||
- type/指南
|
||
para:
|
||
- resources
|
||
source: "[[Obsidian Maps瓦片代理总结与使用指南]]"
|
||
description: "本地瓦片代理方案总结：解决 Obsidian Maps 无法直接加载腾讯/高德瓦片的问题"
|
||
---
|
||
|
||
# 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}` 不支持查询参数格式，这是整个问题的根源
|