> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 空间参考系

# 空间参考系

> 空间参考系的标准流程是  认清数据坐标系 => 认清底图坐标系 => 匹配则直叠、不匹配才转换 => 用偏移现象校验结果
> 成败的关键在"底图和数据是不是同一个坐标系"——转换用错方向比不转换更糟

管网叠加底图时常见这样的现象：**悬停、点击都正常，但管网整体偏离底图道路几百米**。这不是渲染 bug，而是坐标系不匹配：或者数据被错误地做了偏移转换，或者国产底图本身的加密偏移没有处理。

本文同时回答两类高频问题：

* **坐标问题**：高斯/投影坐标被直接当成经纬度，前端报 `Invalid LngLat latitude value: must be between -90 and 90`。
* **数据链路问题**：工具导入/导出一直失败，误以为"选了文件就应该能导入"。

> **先看结论：** 高斯坐标本身没有错，错在直接喂给只认 4326 的地图库；三条处理路线见第四节。选文件只是第一步，导入/导出还需要服务端（或前端解析库）；原因和排查见第六节。

## 一、四种坐标系与对应底图

Web 制图中会遇到四种"看起来都是经纬度"的坐标系，但它们给的**不是同一个点**：

| 坐标系 | 全称 | 性质 | 使用方 |
| :- | :- | :- | :- |
| WGS84 (EPSG:4326) | 全球定位系统坐标 | 真实地理坐标，无偏移 | GPS、GeoJSON 标准、PostGIS 常用 SRID、OSM |
| CGCS2000 (EPSG:4490) | 2000 国家大地坐标系 | 真实地理坐标，无偏移 | **天地图**、国内测绘成果口径 |
| GCJ02 | 国测局加密坐标（火星坐标） | 对 WGS84 加密偏移 | **高德、腾讯**地图 |
| BD09 | 百度加密坐标 | 在 GCJ02 基础上二次偏移 | **百度地图** |

两组关键事实：

* **WGS84 与 CGCS2000 在 Web 制图精度下差异可忽略**（米级以内），可以互相直叠。
* **GCJ02 相对 WGS84 偏移约 500 米，BD09 相对 GCJ02 再偏移一段**。五年前离线地图时代偏移量小，如今地图数据持续更新，偏移已肉眼可见——管网"贴"在高德/百度底图上出现明显错位就是这个原因。

> 高斯-克吕格、UTM、Web 墨卡托（3857）这类**投影坐标**不在这张表里：它们的单位是米，不是度，不能直接当日经度、纬度使用。见第三节。

## 二、底图与数据的匹配决策

核心原则：**底图与数据同系则直叠，任何"帮你对齐底图"的转换都必须与底图的选择绑定**。

| 底图 | 数据现状 | 正确做法 |
| :- | :- | :- |
| 天地图 / OSM | WGS84 / CGCS2000 | **直接叠加，不做任何转换** |
| 百度地图 | WGS84 | 数据坐标 WGS84 → BD09 后再叠加（完整实现 WGS84 ↔ GCJ02 ↔ BD09 三向转换） |
| 高德 / 腾讯 | WGS84 | 数据坐标 WGS84 → GCJ02（**只转一级**，别顺手转成 BD09） |
| 任意 | 投影坐标（3857 / 高斯分带等） | 先重投影回 4326 / 4490 再按上表处理（见[遥感影像](https://gisagent.mapgis.com/docs/remote-sensing.md)的投影预处理一节） |

一个真实反面案例：某管网专题图最初为匹配**百度底图**实现了 `WGS2BD` 转换；后来把底图换成**天地图**，转换代码留在数据加载、地质分区、地图中心点、`fitBounds`、`flyTo` 等多处没有清理，结果管网偏离常州实际位置约 500 米。**修复方式不是加一个反变换，而是把所有 BD09 转换点全部移除**，让数据以 WGS84 原始坐标直接喂给天地图。

## 三、投影坐标不是经纬度：高斯坐标实战

### 3.1 报错现场

前端地图报：

```text theme={null}
Uncaught (in promise) Error: Invalid LngLat latitude value: must be between -90 and 90
    at LngLat.setLat (lng_lat.ts:73)
```

同时数据里的坐标是：

```text theme={null}
[39529378.6941, 4258612.733999999240041]
```

报错的关键在第二个数：MapLibre 把 `4258612.734` 当成纬度，超过 90 就直接抛错。

这不是数据坏了，而是**坐标系/单位不对**：MapLibre、Mapbox GL JS、Cesium 这些地图库的数据入口要的是 `[经度, 纬度]`（EPSG:4326，单位度），这组值是**高斯-克吕格投影坐标**（单位米）。

按 CGCS2000 3 度带 39 带（EPSG:4527）解读（仅凭数值推断，最终以 `.prj` 为准）：

* `39529378.6941` 是东坐标：`39` 是带号，去掉带号后为 `529378.6941`，再减去 500 km 假东偏移，得到相对中央子午线 117°E 的 29.378 km；
* `4258612.734` 是北坐标，约 38.46°N；
* 换算成经纬度约为 `[117.3366, 38.4600]`。

**这组数本身没有错，错在把它直接喂给了只认经纬度的地图库。** 如果文件里存的是 `[北坐标, 东坐标]`，也只是轴序不同，仍然是米，仍然不能直接显示——不要靠"交换一下"解决。

> 更准确地说，不是浏览器限制坐标，而是**前端地图库的数据入口只接受 EPSG:4326 的 `[经度, 纬度]`**；底图瓦片内部再用 3857/墨卡托切片。

### 3.2 30 秒识别坐标类型

| 类型 | 中国范围内的典型数值 | 单位 | 能否直接给 MapLibre |
| :- | :- | :- | :- |
| EPSG:4326 / 4490 经纬度 | 经度 73~~135，纬度 3~~54 | 度 | **可以** |
| Web 墨卡托 3857 | x / y 约 ±20037508 | 米 | 不可以，先转 4326 |
| 高斯 3 度带（带号） | 东坐标 8 位、以带号开头（如 `39xxxxxx.xxx`）；北坐标 7 位 | 米 | 不可以 |
| 高斯 3 度带（无带号） | 东坐标 6 位（如 `529378.xxx`）；北坐标 7 位 | 米 | 不可以 |
| UTM | 东坐标 6 位；北坐标 7 位 | 米 | 不可以 |
| 地方独立坐标 | 数值可能很小，也可能任意 | 米/自定义 | 不可以 |

快速判断：**在中国范围内，经度不在 73~~135、纬度不在 3~~54，就要怀疑不是经纬度**；6 位以上、百万级，基本就是投影坐标。

### 3.3 高斯带号与 EPSG：差一个前缀，位置差几十公里

| 数据特征 | 可能 CRS | 关键参数 | 备注 |
| :- | :- | :- | :- |
| 东坐标 `39xxxxxx` | CGCS2000 / 3-degree GK zone 39（EPSG:4527） | 中央子午线 117°E；假东 39,500,000 | 带号前缀 |
| 东坐标 `529378` 左右 | CGCS2000 / 3-degree GK CM 117E（EPSG:4548） | 中央子午线 117°E；假东 500,000 | 无带号 |
| 北京 54 / 西安 80 高斯 | 对应的 GK CRS | 需要 7 参数或网格 | **不能直接套 EPSG:4527** |

`EPSG:4527` 和 `EPSG:4548` 只差一个带号前缀，但把 `39529378` 喂给 4548，或把 `529378` 喂给 4527，都会得到完全错误的位置。**先看 `.prj`，不要只看数值。**

3 度带 39 带覆盖约 115.5°E\~118.5°E；6 度带同理，但带号和中央子午线算法不同（`CM = 6N - 3`），不要套 3 度带的 117°E。跨带数据应先转到 4326 或统一到同一个带，不能把两个带的高斯坐标混在一张图里。

### 3.4 轴序：X/Y、northing/easting、lng/lat

同一组数，按不同轴序解释会得到完全不同的结果：

| 场景 | 顺序 | 示例 |
| :- | :- | :- |
| SHP 几何 / 投影坐标数组 | `[x, y]` = `[easting, northing]` | `[39529378.6941, 4258612.734]` |
| GeoJSON 4326 的 `coordinates` | `[x, y]` = `[lng, lat]` | `[117.3366, 38.4600]` |
| EPSG:4527 官方轴序 | `[northing, easting]` | `[4258612.734, 39529378.6941]` |
| 中国测绘习惯 X/Y | X=北坐标，Y=东坐标 | X=4258612.734，Y=39529378.6941 |
| MapLibre / Mapbox GL | `[lng, lat]` | `[117.3366, 38.4600]` |
| proj4js | 投影坐标 `[x, y]`；4326 输出 `[lng, lat]` | 见下方代码 |

命令行工具也要注意：`cs2cs EPSG:4527 EPSG:4326` 按官方轴序读入 `[northing, easting]`，而 `ogr2ogr`、proj4js、Shapefile 几何通常按 `[easting, northing]`。**转换前先用一个已知点验证**，不要盲信字段名或数组顺序。

### 3.5 其他常见报错与现象

| 报错/现象 | 含义 | 处理 |
| :- | :- | :- |
| `Invalid LngLat latitude value...` at `lng_lat.ts` | 把投影米制/轴序错的坐标当成 `[lng, lat]` | 按本节识别 CRS，转 4326 后再渲染 |
| `Invalid LngLat longitude value...` | 同上，或坐标是 `NaN`/`undefined` | 检查空几何、转换结果 |
| 底图正常、图层空白 | 坐标超出 ±180/±90，被地图库丢弃 | 查数据范围，转 4326 |
| `fitBounds` 跳到几内亚湾/0,0 | bounds 用了投影坐标或空几何 | 用转换后的坐标重算 bounds |
| 所有要素挤在一点 | 带号/中央子午线/单位错 | 查 `.prj`、EPSG、假东 |
| 转换后整体偏几百米 | GCJ02 底图或基准面错 | 先转 4326，再按底图处理 GCJ02 |
| 转换后偏几十米到几百米 | 北京 54/西安 80 缺 7 参数/网格 | 用正确 datum/参数，不要 `towgs84=0,0,0` |
| 属性乱码 | `.dbf` 编码/`.cpg` 问题 | 不是坐标问题，见第六节 |
| 请求 `/api/...` 404 | 页面没有后端 | 见第六节 |

## 四、三条落地路线

坐标问题没有唯一解，取决于**要不要地图显示、要不要保留原始坐标**：

| 路线 | 做法 | 适合 | 代价 |
| :- | :- | :- | :- |
| 1. 导入时转 4326 | 在数据进入前端前用 proj4/GDAL 统一转成 4326 | 纯展示、简单分析 | 距离/面积若继续用经纬度算，精度有限；原始投影信息可能丢 |
| 2. 去掉地图显示 | 不引入地图库，只在投影坐标里做拓扑/统计/导出 | 桌面工具、批处理、非图形化运算 | 没有可视化，用户看不到结果 |
| 3. 显示层转 4326 | 原数据不动，构造 GeoJSON 时转换；计算仍用米 | 工程管网、规划、需要精度 | 代码要在所有入口一致转换（地图、弹窗、`fitBounds`、导出） |

```text theme={null}
需要地图显示？
├─ 否 → 路线 2：不转 4326，保留投影坐标做运算/导出
└─ 是 → 需要米级精度或保留原始坐标？
   ├─ 是 → 路线 3：数据保持原坐标，只在显示层转 4326
   └─ 否 → 路线 1：导入时统一转 4326
```

推荐：

* **以地图为主**：路线 3 最稳——原始数据不动，显示前转换；如果嫌麻烦，路线 1 也可以，但要接受 4326 下距离/面积算法的精度。
* **只做拓扑/导出**：路线 2 最省事，不要为了地图强行引入 4326。
* **既要地图又要精确计算**：路线 3 + 在投影坐标里算，显示前再转。

### 4.1 proj4 最小实现

```js theme={null}
import proj4 from 'proj4';

// EPSG:4527 = CGCS2000 / 3-degree Gauss-Kruger zone 39
// 输入 [easting, northing]（东坐标、北坐标，单位米）
const GK39 = '+proj=tmerc +lat_0=0 +lon_0=117 +k=1 +x_0=39500000 +y_0=0 +ellps=GRS80 +units=m +no_defs';

export function gk39ToLngLat(easting, northing) {
  const [lng, lat] = proj4(GK39, 'EPSG:4326', [easting, northing]);
  if (!Number.isFinite(lng) || !Number.isFinite(lat) ||
      lng < -180 || lng > 180 || lat < -90 || lat > 90) {
    throw new Error(`坐标转换失败: [${easting}, ${northing}] -> [${lng}, ${lat}]`);
  }
  return [lng, lat];
}

// 示例：约 [117.3366, 38.4600]
console.log(gk39ToLngLat(39529378.6941, 4258612.734));
```

如果数据是 GeoJSON `FeatureCollection`，需要递归转换 `coordinates`，并重算 `bbox`：

```js theme={null}
function transformCoords(coords) {
  if (typeof coords[0] === 'number') {
    const [lng, lat] = gk39ToLngLat(coords[0], coords[1]);
    return coords.length > 2 ? [lng, lat, coords[2]] : [lng, lat];
  }
  return coords.map(transformCoords);
}

function transformGeoJSON(geojson) {
  const features = geojson.features.map((feature) => ({
    ...feature,
    geometry: feature.geometry && {
      ...feature.geometry,
      coordinates: transformCoords(feature.geometry.coordinates),
    },
  }));
  return { ...geojson, features };
}
```

要点：

* `GeometryCollection` 需要额外递归 `geometries`；`bbox` 要按转换后的坐标重算。
* **只转一次**。如果后端已经返回 4326，前端不要再跑一遍 proj4，否则会二次偏移。
* 地图中心点、`fitBounds` 的角点、弹窗坐标、导出坐标要使用同一套转换逻辑，不能只转图层数据。
* 大文件不要在主线程逐点转换；放 Web Worker，或直接在后端用 GDAL 转好。

### 4.2 服务端/命令行转换

```bash theme={null}
# 1. 先确认源 CRS（.prj 是否存在、是否识别）
ogrinfo -al -so input.shp
gdalsrsinfo input.prj

# 2. 转成 4326 GeoJSON（.prj 正确时可省略 -s_srs）
ogr2ogr -f GeoJSON -s_srs EPSG:4527 -t_srs EPSG:4326 input_4326.geojson input.shp

# 3. 导出 SHP 时保留完整 sidecar，并打包
ogr2ogr -f "ESRI Shapefile" output.shp input_4326.geojson -lco ENCODING=UTF-8
zip -r output_shp.zip output.shp output.shx output.dbf output.prj
# 有 .cpg 时把它也加进 zip
```

数据库里用 `ST_Transform(geom, 4326)`；入库成果常用 4490，前端出图时再按 4326 处理。

### 4.3 精度与边界

* proj4js 适合 Web 展示和一般工程应用；**测绘、权属、法定边界**要用 PROJ/GDAL + 官方参数/网格复核。
* CGCS2000 与 WGS84 在 Web 精度下可视为一致；**北京 54、西安 80、地方独立坐标**需要 7 参数/网格或控制点，不能只换椭球。
* `+towgs84=0,0,0` 不是万能的基准面转换；对北京 54/西安 80 直接写 0 可能差几十到几百米。
* 校验方法：已知点对比、4326 → 源坐标 → 4326 往返、转换后范围是否落在预期区域、叠加天地图看是否贴合。

## 五、偏移现象速查

拿到一个"对不上"的图，先量偏移，再下结论：

| 现象 | 大概率原因 | 处理 |
| :- | :- | :- |
| 整体稳定偏移约 500 m | GCJ02 底图叠了 WGS84 数据（高德/腾讯），或反过来 | 数据端补做 WGS84 → GCJ02，或换天地图底图 |
| 整体偏移 > 1 km 且随位置变化 | BD09 与 GCJ02/WGS84 混用，或转换只做了一半 | 统一到底图对应坐标系，检查是否漏转/多转 |
| 越往东/北偏得越多 | 投影坐标被当成经纬度渲染（或反过来） | 用 `gdalinfo` / `ST_SRID` 确认真实 SRID 后重投影 |
| 数据是百万级米制，地图空白/报错 | 高斯/UTM/3857 被当成 4326 | 按第三节识别 CRS，转 4326 |
| 地图上只有一部分要素 | 跨带、超出有效范围，或混了两种坐标系 | 统一 CRS；跨带先转 4326 或相邻带 |
| 悬停、点击、筛选全部正常，只有画面错位 | 渲染链路没问题，纯坐标匹配问题 | 按上面三类定位，不要浪费轮次去查前端逻辑 |
| 个别要素错位、大部分正常 | 数据源口径不一（如互联网坐标未纠偏就入库） | 对互联网来源坐标先做坐标纠偏再统一 |

## 六、导入/导出：为什么"选了文件"还是不行

这一节回答对话里最常见的两句：

* "不是直接选择要导入的文件吗？"
* "导出 SHP/压缩包为什么一直不成功？"

最常见的不是文件坏了，而是四件事：

1. **页面没有后端**：静态页/双击 HTML，选完文件也没有接口处理。
2. **只传/只导出了 `.shp`**：缺 `.shx/.dbf/.prj`，数据集不完整。
3. **ZIP 没有被解压**：上传接口只保存，或 ZIP 里套了目录/不是真 ZIP。
4. **坐标不是 4326**：处理或渲染在中途失败，表现成"导入不进去"。

### 6.1 选择文件 ≠ 导入

浏览器的文件选择框只返回一个 `File` 对象；它**不会自动解析 SHP、不会自动解压 ZIP、也不会把文件写进数据库**。后面必须有人做：

* **前端解析**：页面引入 `shpjs`、`jszip` 等库；
* **或后端解析**：把文件上传到服务端，由 GDAL/pyshp/GeoPandas 处理。

如果页面是双击打开的静态 HTML，既没有前端解析器、也没有后端接口，那么"选完文件没反应"是必然结果。

在 GIS Agent 网页里，上传后文件会落到当前会话的工作目录，并把路径作为消息的一部分交给 Agent；Agent 再调用工具解析/转换/入库。**只点选择文件、不发送消息/不触发工具，文件不会被处理。**

完整的导入/导出链路是：

```text theme={null}
[选择文件] → [上传/读取] → [解压/解析] → [坐标转换/入库] → [生成结果] → [打包下载]
   前端          前端/后端        后端/库          后端/库          后端          后端
```

任何一环缺失，都会表现成"导入/导出失败"，但根因完全不同。

### 6.2 运行形态：有没有"服务端"决定成败

| 形态 | 页面/后端 | 文件在哪 | 导入/导出 | 常见失败 |
| :- | :- | :- | :- | :- |
| GIS Agent 网页/容器 | Web UI + Agent 服务 | 服务端会话工作目录 | 上传 → Agent 处理 → 服务端打包下载 | 坐标错、缺 sidecar、权限 |
| 本机双击 HTML（`file://`） | 只有浏览器 | 本地磁盘 | 没有上传接口，`fetch` 受限 | 选文件没反应、404、CORS |
| 本机静态 HTTP（`python -m http.server`） | 静态文件服务器 | 本地磁盘 | 能打开页面，但没有业务 API | 导入/导出仍失败 |
| Electron 桌面版 | Web UI + 主进程/本地服务 | 本机 `userData`/工作目录 | 取决于是否实现 IPC/本地 API | 渲染进程无 `fs`、打包目录只读 |

> **"服务端容器"不一定指 Docker**，而是指能接收文件、执行解析/转换、写结果的那个后端进程；本地 Node 服务、Electron 主进程、Docker 容器都算。

**在线场景和本地场景要分开排查**：GIS Agent 网页里能上传但不出图，优先查坐标（第三节）；本地下载/双击打开后连上传都没反应，优先查运行形态（本节）。两者混在一起看，很容易把"坐标系错误"和"没有后端"当成同一个问题。

### 6.3 SHP 为什么特殊：它是一组文件，不是单个文件

| 文件 | 作用 | 缺失后果 |
| :- | :- | :- |
| `.shp` | 几何 | 无法读取 |
| `.shx` | 几何索引 | 部分库打不开或性能差 |
| `.dbf` | 属性 | 没有字段/属性 |
| `.prj` | 坐标系 | 不知道 CRS，无法正确转换 |
| `.cpg` | 编码 | 中文属性乱码 |

* 必须**同名、同目录**：`roads.shp` + `roads.shx` + `roads.dbf` + `roads.prj`（有 `roads.cpg` 就一起带上）。
* 上传时把这一组一起选中；网页端会尽量按基础名把 sidecar 放到一起，但改名、分开目录、只传一个文件都会断开关联。
* `.prj` 缺失时，软件可能按 4326 猜，结果是"位置全错"或"无法转换"；这时必须显式指定源 CRS。
* `.dbf` 编码用 `.cpg` 声明（`UTF-8`/`GBK`）；属性乱码不是坐标问题，不要去做坐标转换。

### 6.4 为什么 ZIP 也不行

ZIP 只是容器，不是数据格式；里面的文件仍然要满足 SHP/GeoJSON 的规则：

* **上传接口本身不会自动解压 ZIP**。当前 Web 端上传只是把文件保存到会话目录；需要 Agent/工具后续解压，或者你先在本机解压再把 `.shp` 及 sidecar 一起上传。
* `.rar`、`.7z` 改后缀成 `.zip` 不能解压；密码/加密 ZIP、损坏 ZIP、嵌套目录、`__MACOSX` 垃圾文件都会让解析器找不到 `.shp`。
* 导出 ZIP 时，必须把 `.shp/.shx/.dbf/.prj` 全部装进去；有 `.cpg` 也带上。只装 `.shp` 等于只给了几何。
* 有些解析器只认"扁平结构"的 ZIP；如果 ZIP 里套了一层文件夹，先解压再重新打包，或直接指定里面的 `.shp`。

### 6.5 为什么导出失败

导出不是"浏览器自己就能写文件"：

* **纯前端**：用 JS 库生成 Blob，再触发下载；SHP 需要 `shp-write` 之类的库，ZIP 需要 `jszip`/`fflate`。
* **服务端**：用 pyshp/GeoPandas/GDAL 生成 `.shp/.shx/.dbf/.prj`，打包 ZIP，再以 `Content-Disposition: attachment` 返回。
* **如果工具调用 `/api/...`**：页面必须是"有后端"的运行形态；静态页/`file://` 下这个请求不存在，按钮自然没反应。

GIS Agent 网页端的下载通常是把会话工作目录里的允许文件打包成 ZIP；如果目录里没有可下载文件，或文件扩展名不在允许列表，就会得到空包/错误。当前 Web 端单文件上传上限约 512MB，下载打包上限约 1000 个文件/512MB，超限会直接失败。

**打包后的 Electron 应用还有两个额外坑：**

* 渲染进程默认没有 Node 文件系统权限，导入/导出要走 preload/IPC 或本地服务，不能在页面里直接 `fs.writeFile`。
* 安装目录/`app.asar` 通常是只读的；写文件要用 `app.getPath('userData')` 或让用户选择目录，不要写 `__dirname`/resources。

### 6.6 故障对照表

| 现象 | 先看哪里 | 最可能原因 | 处理 |
| :- | :- | :- | :- |
| 选完文件没反应，Console 无报错 | Network 是否有上传请求 | 页面是静态 `file://`，没有后端 | 启动服务/Electron；不要双击 HTML |
| 上传请求 404 / CORS | Network 状态码 | 静态服务器没有 `/api`，或跨域 | 用真正的后端；同源访问 |
| 上传 200，但地图空白 | Console 是否 `Invalid LngLat` | 坐标是投影米制 | 按第三节转 4326 |
| 上传 200，但工具提示格式错误 | 上传的文件列表 | 只传了 `.shp`，缺 `.dbf/.shx/.prj` | 全部上传，同名 |
| ZIP 上传后无法识别 | 服务端是否解压 | 上传接口只保存，不自动解压 | 让 Agent 解压，或先解压再传 |
| 导出按钮无反应 | Network 是否有请求 | 前端没实现/调用不存在的 API | 实现后端导出或纯前端导出 |
| 导出请求 404 | 地址/路由 | 本地没有该接口 | 启动对应服务 |
| 导出 200 但文件 0KB/打不开 | 响应头/内容 | 生成失败/空目录/流错误 | 看服务端日志 |
| 下载的 ZIP 里只有 `.shp` | 解压查看 | 导出时没打包 sidecar | 补 `.shx/.dbf/.prj`（有 `.cpg` 也补） |
| 下载被浏览器拦截 | 地址栏/下载列表 | 弹窗/下载权限/混合内容 | 允许下载；用 `fetch`+Blob |

### 6.7 五分钟排查顺序

1. **看地址栏**：是 `file://` 还是 `http://localhost`？静态页先解决"有没有后端"。
2. **F12 → Network**：点导入/导出，有没有请求？状态码是 404/413/500？响应体是什么？
3. **F12 → Console**：有没有 `Invalid LngLat`、CORS、模块加载失败？
4. **看服务端/容器日志**：文件保存了吗？ZIP 解压了吗？结果文件生成了吗？目录权限对吗？
5. **看文件本身**：SHP 的主要组成文件齐不齐？`.prj` 在不在？ZIP 是不是扁平的？
6. **做最小测试**：先用一个 4326 的单点 GeoJSON 测导入/导出。它能成功，说明链路通，问题在 SHP/CRS；它也失败，问题在运行环境/接口。

```json theme={null}
{"type":"FeatureCollection","features":[{"type":"Feature","properties":{},"geometry":{"type":"Point","coordinates":[117.3366,38.46]}}]}
```

### 6.8 本机运行清单

* 先找下载包根目录的启动脚本：`start-windows.bat`、`start-linux.sh`、`deploy.bat`、`docker-compose.yml`；以实际包为准。运行后打开脚本提示的 `http://localhost:<端口>`，**不要双击 `index.html`**。
* 如果只有 `index.html` + `assets`，没有 `package.json`/启动脚本，它大概率是静态导出，不具备服务端导入/导出能力。
* Electron 桌面版按项目说明执行：

```bash theme={null}
cd <你的目录>/topology-tool-desktop
npm install
npm start        # 开发模式
npm run build    # 打包为 .exe/.dmg/.AppImage
```

* 如果当前环境不能安装依赖，把整个目录拷到本机再执行；Node 用 LTS 版本，先确认 `node -v`、`npm -v`。
* `python -m http.server`、`npx serve` 只提供静态文件，不是后端；用它打开页面，导入/导出仍然会失败。
* Docker/容器部署要确认容器在运行、端口映射正确、挂载目录可写；挂载目录是 root 属主时，常见 `EACCES`。
* 本地服务实在起不来：把数据上传到 GIS Agent，在对话里让 Agent 转换/导出，再下载结果——这仍然是"有后端"的场景，不是静态网页。

## 七、底图切换的工程要点

实际项目里底图经常要换（天地图 ↔ 百度 ↔ 高德 ↔ OSM），切换时四件事必须同步改，缺一就出问题：

1. **坐标转换逻辑**：与底图绑定。切到天地图/OSM 就移除 BD09/GCJ02 转换，切到百度才加回 BD09 转换。
2. **瓦片 URL 格式**：天地图要用标准 **WMTS GetTile** 接口（`https://t{0-7}.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&...&TILECOL={x}&TILEROW={y}&TILEMATRIX={z}&tk=<token>`），这是实测一次即通的格式；`tianditu.com` 域名或 `DataServer?T=vec_w&X=...` 简式接口的稳定性与权限都要打折，不要依赖。
3. **协议**：页面是 https 时瓦片也必须 https，否则浏览器按混合内容（Mixed Content）拦截，表现为"底图无声失败"。
4. **降级链与提示**：设置自动降级（如 天地图 → OSM），并在图例里显示当前实际生效的底图源，失败时控制台输出切换日志——否则用户看到的永远是"加载失败"，排查全靠猜。

## 八、常见问题

* **我的数据就是高斯坐标，为什么不能直接用？** 数据本身没错，错在消费方：高斯坐标适合在投影平面内做工程计算，而 Web 地图库只接受 4326 的经纬度。正确做法是**转换后再显示，或只在显示层转换**，不要改原始数据。
* **报 `Invalid LngLat latitude value` 最快怎么修？** 三步：看 `.prj` 确认 CRS/带号 → 确认轴序（东/北 vs 经/纬）→ 用 proj4/GDAL 转 4326 并校验范围。不要用"除以 100 万""删掉 39 前缀"这类算术 hack。
* **选择文件后没反应/导入失败？** 先看打开方式和 Network：`file://` 或静态 HTTP 没有上传接口；有请求但 4xx/5xx 看响应；上传 200 但无图看坐标。**选择文件只是第一步。**
* **SHP 为什么不能只传 `.shp`？** `.shp` 只有几何，属性在 `.dbf`，索引在 `.shx`，坐标系在 `.prj`，编码在 `.cpg`。缺 `.prj` 无法正确转换，缺 `.dbf` 没有属性。
* **上传 ZIP 为什么识别不了？** ZIP 只是容器，上传接口不会自动解压；`.rar`/`.7z` 改后缀也没用。先解压，或让 Agent/工具解压后再解析。
* **导出的 SHP 为什么打不开/没属性？** 只导出了 `.shp`。SHP 必须连同 `.shx/.dbf/.prj`（有 `.cpg` 也带上）一起打包成 ZIP；单独一个 `.shp` 不是完整数据集。
* **下载的网页工具为什么导入导出都不行？** 它大概率是静态页面，没有服务端。启动随包脚本/Electron 本地服务，或改用 GIS Agent 处理；`python -m http.server` 不能代替后端。
* **"服务端容器"是什么，必须吗？** 它是能接收文件、执行解析/转换、写结果的后端进程，不一定非 Docker。要做服务端 SHP 导入/导出就需要它；纯前端也能做，但要引入解析/写入库，且受编码、投影、大文件限制。
* **能不能一开始就把数据转成 4326 保存？** 可以，但建议**保留原始坐标，另存 4326 副本用于 Web**。工程成果继续用原高斯带，交付 Web/GIS 平台用 4326/4490；无论哪种，都在 `.prj`/README 里写清 CRS。
* **前端 proj4 精度够吗？** 展示和一般工程够用；测绘/权属/法定边界要用 PROJ/GDAL + 官方参数/网格。北京 54、西安 80、地方独立坐标不能只换椭球。
* **高斯带号怎么判断？跨带怎么办？** 看 `.prj`/`gdalinfo`，或用东坐标前缀和中央子午线反推；跨带数据先转 4326 或统一到同一个带，不要混用两个带的高斯坐标。
* **为什么转换后还是偏移？** 常见是带号/中央子午线错、轴序错、基准面缺参数、或前后端各转了一次。用已知点、往返转换和天地图叠加校验。

## 九、给 AI 的最小信息包

"导入不了""导出失败"太模糊，AI 只能猜。一次说清下面五样，通常一轮就能定位：

1. **打开方式**：`file://` 双击、`http://localhost`、还是 GIS Agent 在线页面？
2. **Console 报错原文 + 行号**（如 `Invalid LngLat ... lng_lat.ts:73`）。
3. **Network**：点导入/导出后有没有请求？状态码和响应体是什么？
4. **文件清单**：`.shp/.shx/.dbf/.prj/.cpg` 还是 ZIP？ZIP 里面是什么结构？
5. **样例坐标 + `.prj` 内容**（或 `gdalinfo`/`ogrinfo` 输出）。

可直接复制的提示词：

* "数据是 CGCS2000 3 度带 39（EPSG:4527），坐标是高斯米制；前端地图只接受 4326。请先确认 `.prj`，再在导入/显示层用 proj4 转 4326，原始数据不要覆盖。"
* "我的工具是本地双击打开的静态网页，导入/导出都失败。请先判断是不是没有后端，再给出启动本地服务/Electron 的方案；不要只改前端按钮。"
* "导入报 `Invalid LngLat latitude value: must be between -90 and 90`，样例坐标是 `[39529378.6941, 4258612.734]`；请检查带号、轴序和 `.prj`，不要直接改数值。"
* "导出 SHP 时请把 `.shp/.shx/.dbf/.prj`（有 `.cpg` 也带上）一起打包成 ZIP，并说明导出成果的 CRS。"

***

**使用提示：** 在对话里一次性说清三件事——"数据是什么坐标系""底图用哪一家""是否需要我自动做坐标转换"，例如"管网数据是 WGS84，底图用天地图矢量，不要做任何坐标偏移转换"，可显著减少来回确认。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.