实战手册

001

国内地图坐标偏移到底差多少米

用 GPS 采的点标到高德或百度地图上，整体偏出去几百米，而且不同城市偏的还不一样多。 排查思路 002

底图和数据都对，合起来却错位

底图是自己接的，数据是业务方给的，两边单看都没问题，叠在一起整体偏出去一段。 排查思路 003

同一批点位被转换两次，偏移从 555 米变成 1110 米

GPS 点位在高德底图上偏出去半公里，接口里明明已经转过坐标了，前端又转了一遍。 排查思路 004

百度坐标用固定 0.0065 反算，剩下的 481 米没消掉

从百度接口拿到的点是 BD-09，减掉 0.0065 和 0.006 之后仍然对不上 GPS 原始点，差 480 多米。 排查思路 005

把 3857 的米值当经纬度传入，标记点直接消失

接口返回 13522390, 3669872，塞进 L.marker 后地图一 zoom 就飞到北极，标记也不见了。 排查思路 006

UTM 带号差 1，西安的点位横向偏了 551 公里

数据按 49 带投影，地图却声明成 50 带，点位整体东移半个省。 排查思路 007

高斯 3 度带带号算成中央经线，图层偏了 275 公里

EPSG:4546 和 EPSG:4547 只差一个数字，位置差了近三个经度。 排查思路 008

GeoJSON 没写坐标系，3857 的数据被当成经纬度

文件能正常解析，features.length 也对，就是地图上什么都看不见。 排查思路 009

CGCS2000 与 WGS84 混着用，大比例尺下差了 0.4 米

小比例尺看不出来，一到 1:500 放样就发现控制点和实测点对不上。 排查思路 010

把 EPSG:4479 当地理坐标用，点位数值到了七位数

天地图服务目录里写着 CGCS2000，选了 4479，拿到的却是 X/Y/Z 三个米值。 排查思路 011

把 CRS 改成 EPSG:4326，中国版图被压扁了

为了「让坐标直出度」，把地图 CRS 换成 4326，结果圆变成了椭圆，省界也矮了一截。 排查思路 012

两个图层各用一套坐标系，叠上去错开半屏

底图正常显示，叠加的规划图却整体偏右上，缩放越大偏得越多。 排查思路 013

proj4 报 unknown projection: EPSG:4547

同样的转换代码，换一个 EPSG 码就抛异常，控制台只说「未知投影」。 排查思路 014

WMS 1.3.0 的 BBOX 是纬度在前，图层整个错位

从 GeoServer 取同一块范围，1.1.1 正常，1.3.0 返回空白图或上下颠倒的图。 排查思路 015

七参数尺度因子没除 1e6，20 公里外偏了 24 公里

地方坐标转 CGCS2000，近处看着还行，越往外偏得越离谱，像被整体放大了两倍多。 排查思路 016

境外坐标也被加密，深圳河两岸出现 600 米断崖

一条连续的边界线，转了坐标之后在河中间断开，两侧相差 600 米。 排查思路 017

百度墨卡托漏了 MCBAND 分段，点位偏出三公里

用 lng * 20037508.34 / 180 自己算百度瓦片坐标，结果和百度的瓦片对不上。 排查思路 018

经纬度只存两位小数，热力图整体错开 1.1 公里

数据库字段是 decimal(9,2)，存进去的点全被吸到 0.01 度的网格上。 排查思路 019

纬度 89° 传给墨卡托，Y 值变成 Infinity 后瓦片编号是 NaN

南极科考站的点一加进去，整个图层就不渲染了，控制台却一声不响。 排查思路 020

南半球 UTM 少了 1000 万假北，悉尼的 y 变成负数

同一份投影代码，北半球的点正常，南半球的点 y 全是负的，排序时全跑到最前面。 排查思路

021

地图一片空白，控制台却没报错

代码看起来没问题，库也加载了，页面就是一片白。最难查的一类问题，因为没有任何错误信息。 排查思路 022

地图在弹窗里显示错位

地图只在主页面正常，一放进弹窗、抽屉、标签页，就只画左上角一小块，或者整片空白。 排查思路 023

瓦片 404 或跨域被拦

地图框架加载正常，但底图是一格一格的灰色方块，网络面板里一片红色。 排查思路 024

20 MB 的 GeoJSON 同步解析，主线程卡了 8 秒

文件不大，但打开页面后转圈八秒，期间点击任何按钮都没反应。 排查思路 025

Shapefile 属性表中文全是乱码，几何却完全正常

边界线画得一丝不差，属性弹窗里的地名却是「鍖椾含甯傚湴鍥炬」。 排查思路 026

CSV 的经纬度列写反，点全跑到索马里外海

一批北京的点，加载后坐标显示 39.9, 116.4，落点在印度洋。 排查思路 027

MultiPolygon 少包一层数组，渲染直接报 invalid geometry

后端拼的 GeoJSON 在 QGIS 里打不开，前端有时报错、有时什么都不画。 排查思路 028

WMTS 的 TileMatrix 标识从 0 开始，瓦片整体错一层

图层能显示，但比例尺总比底图大一级，设施点位与影像对不上。 排查思路 029

GeoServer 把 4326 的数据声明成 4490，图层偏了半米

同一份数据直接读文件正常，从 GeoServer 出图就整体平移，差半米，肉眼几乎看不出。 排查思路 030

geometry 为 null 的要素，让 fitBounds 抛 null is not an object

接口里混进两条 geometry 为 null 的记录，整个地图初始化就中断了。 排查思路 031

TopoJSON 丢了 transform，坐标全变成整数 7823

文件从 20 MB 压到 3 MB，转换后却画不出任何东西，坐标是 7823、4210 这样的整数。 排查思路 032

跨 180° 经线的多边形，被画成横穿整个地球的一条带

斐济的专属经济区，在地图上变成一条横跨太平洋的细长条，中间还穿透了非洲。 排查思路 033

缺了 .prj 的 Shapefile，被当成经纬度读进西安以东 500 公里

同事只发了 .shp、.shx、.dbf 三个文件，打开后数据跑到非洲西海岸。 排查思路 034

DBF 字段名超 10 个字符被截断，前端读 properties 全是 undefined

数据表里明明有 population_total，导出的 Shapefile 里只剩 population。 排查思路 035

KML 里的图标写相对路径，加载后全是碎图

KML 在 Google Earth 里正常，放进网页地图后每个点都变成一个破碎的小图标。 排查思路

036

标记点一多就卡

三百个点还算流畅，八百个点开始掉帧，两千个点拖动像放幻灯片。这是矢量图层最常见的性能瓶颈。 排查思路 037

首屏加载十几秒

用户打开页面，先看到空白背景几秒，再看到一堆灰块慢慢变成地图，最后才是数据。 每一段都在流失人。 排查思路

038

接入国内底图要改哪些地方

从 OpenStreetMap 换成国内底图，不只是把 URL 换掉。坐标系、Key、协议、配额四处都要动。 排查思路 039

3D Tiles 加载不出来

代码没报错，tileset.json 也请求成功了，地球上就是什么都不显示。 排查思路 040

WMS 一直 502，服务其实还活着

直接访问 GeoServer 的 8080 端口一切正常，走 Nginx 就返回 502，刷新几次偶尔又成功。 排查思路 041

跨域预检被拒，GET 能过 POST 不行

查询瓦片正常，一提交分析任务就报跨域；网络面板里多出一条 OPTIONS 请求，返回 405。 排查思路 042

数据更新了，切片还是上周的样子

数据库里新增的道路已经入库，WMS 直连能看到，瓦片服务却还是旧图，局部甚至出现新旧拼接的接缝。 排查思路 043

代理转发后，WMS 的查询参数全丢了

直连 GeoServer 正常，经过公司网关后所有请求都变成“缺少 LAYERS 参数”，服务端日志里看不到 BBOX。 排查思路 044

SLD 传上去了，地图还是默认灰色

在 GeoServer 里上传了 SLD，预览页面能看到效果，自己的 WMS 请求出来还是那套默认灰填充。 排查思路 045

GetCapabilities 要等一分钟，客户端直接超时

加载图层树时转圈，最后报“服务不可用”。直接打开能力文档地址，等了 58 秒才出来。 排查思路 046

HTTPS 页面加载 HTTP 瓦片，全被浏览器拦了

站点切到 HTTPS 后，底图整片空白，控制台刷满 “Mixed Content” 警告，瓦片一个都没下下来。 排查思路 047

连接池耗尽，WMS 集体 503

早上九点业务高峰，所有图层一起变慢，随后整站返回 503，重启 GeoServer 才能恢复。 排查思路

048

移动端手势冲突与滚动穿透

手机上想拖地图，结果整页跟着滚；想双指缩放，页面被放大；地图在页面中间，永远滚不过去。 排查思路

049

Cesium 报 401，ion Token 没生效

地球能出来，底图是黑的，网络面板里所有 api.cesium.com 请求都返回 401。 排查思路 050

3D Tiles 白模糊成一片白，看不出轮廓

模型加载成功了，相机也对准了，但建筑是一片纯白，和白色底图几乎融在一起，只能靠阴影分辨。 排查思路 051

模型悬空或陷进地形，差的那几米在哪

坐标填的是地面点，模型却飘在半空十几米；换成另一个视角，又有一半埋进了山体。 排查思路 052

相机钻到地下，画面只剩一片黑

用户按住右键向上拖，视角越过地平线，屏幕突然全黑，再拖几下地球从另一侧翻出来。 排查思路 053

地形瓦片加载慢，首屏转了十几秒

影像早就铺满了，地形却一直有锯齿状的空洞，进度条停在一半，请求队列常年两百多条。 排查思路 054

Entity 上了两千个，帧率掉到 18

五百个站点时很流畅，加到两千个站点后拖动明显卡顿，性能面板里 update 阶段占了大头。 排查思路 055

CesiumWidget 尺寸为 0，地球建不出来

页面一打开就报错，容器明明写了 width: 100%; height: 100%， 浏览器算出来的却是 0×0。 排查思路 056

toDataURL 截出来是黑图，Cesium 也一样

点击“导出图片”，拿到一张纯黑或全透明的 PNG；同一段代码在别的页面又是正常的。 排查思路 057

开了泛光后整个场景发白

想让夜景灯光有一点辉光，结果整屏像蒙了一层雾，建筑边界全糊了，帧率也掉了三分之一。 排查思路

058

模型加载出来是黑的，转一圈也看不见

GLTFLoader 没有报错，进度条也走到了 100%，但屏幕上只有一个黑色剪影，完全看不出材质。 排查思路 059

贴图上下颠倒，字全是反的

同一张地面标牌贴图，用 TextureLoader 加载是正的，换成 canvas 或二进制数据生成之后就倒过来了。 排查思路 060

模型躺在地上，和地图方向对不上

模型在建模软件里是站着的，导进 three.js 后躺倒；按地图点位摆放后，楼的朝向又整体偏了 90 度。 排查思路 061

两个面贴在一起就闪，越远越明显

地面模型上叠了一层道路面，近处还好，相机拉远之后整片道路像被噪声覆盖，来回闪烁。 排查思路 062

半透明玻璃叠在一起，看不见背面

给玻璃幕墙设了 opacity: 0.4，结果每一层玻璃都像实心板，后面的楼完全被挡住。 排查思路 063

两千万点点云，打开就卡死

PLY 文件 1.8 GB，加载后浏览器内存涨到 3 GB，帧率 3 fps，动一下鼠标要等两秒。 排查思路 064

模型加载后只有指甲盖大小

一栋 60 米高的楼，导入后和 1 米的地面网格差不多大；换一个模型，又大得把相机包在里面。 排查思路 065

InstancedMesh 摆了五千棵树，全歪了

用实例化渲染种树，位置大致对，但每棵树的旋转和缩放完全不受控制，还有一半根本不出现。 排查思路

066

setProps 改了数据，图层却纹丝不动

点了筛选按钮，控制台里的数组确实变了，地图上的点一个没少，颜色也没变。 排查思路 067

点了地图，拾取永远是 null

鼠标明明停在点上，onClick 里的 info.object 一直是空值， 只有 info.index 有时是 -1。 排查思路 068

一百万条轨迹，页面直接崩了

CSV 解析完内存就到 2.4 GB，浏览器标签页变白，标题变成“页面无响应”。 排查思路 069

地图一动，deck.gl 图层就漂走

底图拖动很顺，数据层慢半拍；缩放时点阵先变大再回弹，边界始终差一截。 排查思路 070

坐标数组维度不对，点全跑到南极

数据是北京的点，图层却画在南极附近；换成另一个图层，控制台直接报顶点长度错误。 排查思路 071

两个图层 id 撞了，删一个另一个也没了

图例里关掉“基站”层，结果“告警”层也一起消失；再打开，两个层都回来了。 排查思路

072

样式加载失败，地图一直是灰底

地图能出现，也能拖动，但只有一个灰色背景，道路、水系、标注全都没有。 排查思路 073

addLayer 成功，地图上什么都没有

没有报错，getLayer 也能查到，但屏幕上就是看不到任何新增的图形。 排查思路 074

自定义图标全部 404，标记变成空白

符号图层加好了，样式里也写了 icon-image，地图上却一个图标都没有， 网络面板里一片红色 404。 排查思路 075

setTerrain 之后地面还是平的

按照文档加了地形源，倾斜视角后山脉毫无起伏，建筑也没有跟着贴到坡面上。 排查思路 076

样式里的 sprite 拿不到，图标全是方块

换成自建样式后，道路编号、机场、地铁站图标全变成空白方块，地图其余部分完全正常。 排查思路

077

flex 布局里地图高度为 0，只剩一条灰边

页面顶部是标题栏，下面留一格放地图，结果地图只有几个像素高，瓦片挤成一条线。 排查思路 078

标记图标全变破图，打包后路径丢了

本地开发时标记是正常的定位针，打包上线后全部变成浏览器默认的破图图标。 排查思路 079

搜索一次加一层，点越叠越多还删不掉

同一个站点搜索五次，图标边缘越来越毛，点击一次弹出五个相同的气泡。 排查思路 080

fitBounds 没反应，视野停在原地

查到一个站点后调用 map.fitBounds，地图纹丝不动； 换成一堆点，又缩到了世界地图级别。 排查思路 081

Canvas 渲染后，拖动地图留下残影

为了提升性能打开了 preferCanvas，结果平移时老的圆形没擦掉，缩小时整片线网糊成一团。 排查思路

082

两个图层共用一个 source，改一个另一个也变

主图上的“已选站点”清空了，对比窗口里的同一批点也消失了，两个地图明明互不相关。 排查思路 083

给矢量图层写 renderer: 'webgl'，图层直接没了

听说 WebGL 渲染更快，在 ol.layer.Vector 上加了 renderer: 'webgl'， 结果控制台报错，点一个都不显示… 排查思路 084

WMS 图层一片空白，服务端回了段 XML

图层加进去了，瓦片请求全是 200，但图片是透明的；点开一张请求，返回的是一段 XML 报错。 排查思路 085

样式函数漏了 return，一半要素不画

按属性给不同颜色的点，结果只有一类点显示，其余全部消失，控制台还报了一个读属性失败的错误。 排查思路 086

拖动地图时，整层要素白闪一下

为了拖动时也能看到数据，打开了实时重绘，结果每次平移画布都先清空，再一块块补回来。 排查思路

087

打包上线后，JS 和 CSS 全 404

本地 npm run build 一切正常，传到服务器后页面白屏，HTML 里的资源地址全部 404。 排查思路 088

部署到子目录后，路由和图片全错位

项目挂到 /gis/ 下，首页能打开，但图标、瓦片、接口全部请求到了根路径。 排查思路 089

主站和子系统各引一份 Leaflet，地图对象认不出来

子系统单独跑正常，嵌进主站后地图能显示，调用 map.remove() 却报“不是函数”。 排查思路 090

逻辑挪进 Worker，一加载就报 document 未定义

把两万个点的聚合计算放进 Worker，想解放主线程，结果 Worker 刚启动就挂掉。 排查思路 091

import 一个 CommonJS 包，构建直接报错

引入 proj4 做坐标换算，开发环境正常，构建时提示模块没有默认导出，打包中断。 排查思路 092

控制台警告有三份 three.js，拾取全失效

模型能显示，但点击拾取永远不命中；控制台第一条就是“Multiple instances of Three.js being importe… 排查思路 093

发布后部分用户白屏，报 ChunkLoadError

新版本上线十分钟，客服收到反馈：一部分用户打开是白屏，清缓存后又正常。 排查思路

094

成果坐标系没转换，验收被退回

数据看着没错，点位也落在正确的位置，质检报告却写着“坐标系与要求不符，平面位置超限”。 排查思路 095

敏感数据被打进前端包，公网可下载

例行安全检查发现，构建产物里能直接搜到设施名称与坐标，对象存储的瓦片目录不需要登录就能访问。 排查思路

096

TMS 的 Y 轴反着数，底图南北颠倒

瓦片全部能加载出来，拼接也严丝合缝，就是整张图上下翻转。 排查思路 097

瓦片目录从 1 级开始，地图整体放大了一倍

离线包只有 1~19 级目录，前端按 0 级起算，画面始终比实际大一号，19 级还缺图。 排查思路 098

天地图瓦片 403，Key 是对的但 Referer 不在白名单

把瓦片地址贴到浏览器地址栏能打开，放进地图里就全部 403。 排查思路 099

导出地图为图片时报 canvas tainted，前后排查了两小时

截图按钮一点就抛 SecurityError，地图本身显示得好好的。 排查思路 100

瓦片返回 204 而不是 404，地图上是一片透明白块

网络面板里全是 204，看着像「没有错误」，可地图上缺了一大片。 排查思路 101

瓦片之间出现 1 像素白线，缩放后像蛛网

每张瓦片都完整加载了，但拼起来满屏细白线，缩放级别越小越明显。 排查思路 102

缩放到 17 级直接跳到 19 级，缺的两级全是灰块

滚轮滚一下，级别跳过 18 直接到 19，中间两级的地图从来没出现过。 排查思路 103

七个瓦片子域全配了，浏览器还是只开 6 个连接

子域配了 0 到 7，网络面板里同时进行的请求依然是 6 个，其余全部排队。 排查思路 104

512 像素的瓦片被按 256 排版，底图模糊又错位

换了一份高清瓦片，地图反而变糊，还跟矢量数据差了半个屏幕。 排查思路 105

百度的瓦片原点在原点偏移处，按 XYZ 算整层偏移

按 Google 的公式算百度瓦片编号，每个级别都差几十张瓦片，拼出来的图像条带错位。 排查思路 106

瓦片缓存 30 天不清，改了配色用户看到的还是旧图

服务端已经重新切片，本地开发清缓存也没用，用户那边照样是两周前的底图。 排查思路 107

缩小到 3 级时地图重复了三次，noWrap 没开

缩到最小级别，屏幕上并排出现三个中国，左右两边还是镜像拼接的。 排查思路

108

样式表达式少了一个 dimension，整层要素都不显示

图层加上去了，图例也有，地图上却一个要素都没有，控制台只给了一条警告。 排查思路 109

多边形的洞方向反了，中间的湖被填满

一个带湖的行政区面，渲染后湖面也被涂成了行政区的颜色，卫星底图看不见了。 排查思路 110

标注挤成一坨，text-allow-overlap 一开就全乱了

城市名互相压住，打开允许重叠后，八百个名字同时糊在屏幕上。 排查思路 111

长地名的后两个字被裁掉，text-max-width 太小

「乌鲁木齐高新技术产业开发区」只显示成「乌鲁木齐高新」，后面的字全没了。 排查思路 112

面图层盖住了线图层，调 zIndex 反而更糟

道路线被行政区面压在下面，设了 zIndex: 999 依旧没变，甚至整条线消失了。 排查思路 113

两层半透明叠在一起，颜色比预期深了一倍

两个 50% 透明的图层叠上去，重叠区看起来像 75% 不透明，设计稿完全对不上。 排查思路 114

线宽不随缩放变化，放大后像一根头发丝

12 级时道路像主干道，17 级时同样的道路细得几乎看不见。 排查思路 115

图钉的针尖没对准坐标，偏了 12 像素

点位落在路口，图钉的针尖却指在马路中间，放大到 18 级差出十几米。 排查思路 116

颜色写成 #1a6fd4cc，老版本浏览器直接忽略

同一份样式，Chrome 最新版正常，客户的内嵌浏览器里整个图层透明。 排查思路 117

filter 里数字和字符串比较，条件永远是 false

明明有 40 个区县人口超过一万，图层上一个都没画出来，也没有报错。 排查思路 118

标注字体没加载，glyphs 404 导致文字全不显示

图标正常、面正常，只有文字一个都出不来，网络面板里一排 glyphs 请求全是 404。 排查思路 119

sprite 里没有这个图标名，符号层直接不画

icon-image 写了一个名字，地图上什么都不出现，也没有任何报错。 排查思路 120

打印出的图比屏幕小一圈，96 与 72 DPI 混用了

屏幕上刚好铺满 A4 的地图，打印出来只占左上角四分之三，比例尺也对不上。 排查思路