企业官网建设流程全解析

接到一个EarthSDK3项目时，客户扔过来一堆KML数据，说“这些都要在系统里显示”。等我把数据拖进去一看，项目里其它的图层服务、后端接口、统计模块，全都只认GeoJSON。找在线转换工具转了几个文件，确实能出结果，但数据一更新、文件一多，这条路彻底走死。最后还是自己在代码里做了一套KML转GeoJSON，顺手把EarthSDK3的接入也打通了。这篇文章就把整个思路、实现细节和踩过的坑完整写出来，给同样被格式问题卡住的朋友一个参考。

这里先说明一点：KML转GeoJSON本身是一个数据处理问题，不是EarthSDK3独有的功能，但放在EarthSDK3这个三维地球引擎里做转换，涉及加载方式、坐标维度和样式处理等特殊细节，所以本文的重点会放在“如何在EarthSDK3项目的实际开发中完成这件事”。

1. 为什么偏偏要做“KML转GeoJSON”

1.1 两种格式的“出身”完全不同

KML是XML格式的地理数据标准，早期是为了做地图标注和地理可视化设计的，所以它的结构更像“文档”，有Document、Folder、Placemark这种层层嵌套的节点。GeoJSON则是JSON格式，本质是“数据交换格式”，以FeatureCollection和Feature为核心，更适合后端存储、数据库查询和前端渲染框架直接消费。

从数据结构看，KML里一个典型要素长这样：

<Placemark> <name>某栋楼</name> <Polygon> <outerBoundaryIs> <LinearRing> <coordinates> 116.39,39.91,0 116.40,39.92,0 116.41,39.91,0 116.39,39.91,0 </coordinates> </LinearRing> </outerBoundaryIs> </Polygon> </Placemark>

同样的地理对象转成GeoJSON后：

{ "type": "Feature", "properties": { "name": "某栋楼" }, "geometry": { "type": "Polygon", "coordinates": [[[116.39, 39.91], [116.40, 39.92], [116.41, 39.91], [116.39, 39.91]]] } }

单看这个例子，转换并不复杂。但实际工作中的KML远没有这么干净，坐标串里混着换行和空格、多边形内外环顺序混乱、几何类型缺失、样式嵌套在Document级共享……这些才是真正的难点。

1.2 EarthSDK3加载两者的真实体验

EarthSDK3本身对KML和GeoJSON都提供了加载能力。KML有对应的KML类，GeoJSON也有对应的GeoJSON类。但在实际项目中，两者的体验天差地别。

KML在EarthSDK3里的加载逻辑相对固定，样式、属性这类信息的控制粒度不够细，而且不同版本的SDK解析KML的行为有差异，尤其是标签带命名空间前缀的情况，容易出现“文件能加载但要素属性取不到”的尴尬。GeoJSON则更友好，几何对象和属性数据都结构清晰，方便在前端直接遍历、过滤、绑定交互事件，也方便和后端接口衔接。

换句话说，KML适合“打开就看”，GeoJSON适合“拿来做业务”。项目一旦涉及属性查询、图层联动、数据导出、统计聚合，GeoJSON几乎是必然选择。

1.3 业务里哪些场景必须走转换这条路

我这次项目里遇到的需求比较典型：客户的历史数据是从GIS工具批量导出为KML的，但业务系统的数据中台只提供GeoJSON接口；同时项目里已有几百个GeoJSON图层，临时修改整体数据链路不现实。类似的情况还有几种：

• 需要把多个KML文件合并成一个可检索的数据集，统一走GeoJSON的加载和筛选流程。
• 需要在前端修改几何对象（比如画一个新的范围替换原有边界），KML的XML结构改起来很麻烦，转成GeoJSON后直接用JavaScript对象操作就行。
• 需要对坐标做投影转换、精度压缩、抽稀等处理，GeoJSON数组化的结构让这类算法处理简单得多。

如果你的项目也碰到了类似的场景，基本可以确定：转换这一步绕不开，而且最好放在代码里做，不要靠人工工具。

2. 动手前先搞清楚KML的数据结构

2.1 一个典型KML文件长什么样

多数的KML文件顶层结构是这样的：一个kml根节点，下面有一个Document，Document里包含若干Folder和Placemark。Folder可以无限嵌套，用来做数据分组。Placemark是真正的“要素”，里面可以放Point、LineString、Polygon，也可以是MultiGeometry组合多个几何。

还有一类不能忽略的节点是ExtendedData，业务字段都在这里：

<Placemark> <name>A-001</name> <ExtendedData> <Data name="floor"> <value>12</value> </Data> <Data name="area"> <value>3800.5</value> </Data> </ExtendedData> <Point> <coordinates>116.39,39.91,0</coordinates> </Point> </Placemark>

如果不处理ExtendedData，转换后这些业务属性全部丢掉，后续查询就成了空壳。

2.2 坐标解析是转换成败的分水岭

KML里所有坐标都是“经纬度、高度”的三元组，经纬度之间用逗号分隔，多个坐标点之间用空白字符（空格、换行或制表符）分隔。注意顺序：经度在前，纬度在后，这跟GeoJSON的坐标顺序一致，所以很多人想当然以为转换很简单。

真实文件里的坐标串经常写成这样：

116.39,39.91,0 116.40,39.92,0 116.41,39.91,0 116.39,39.91,0

有时会用多个空格、有时是逗号后有空格、有时一行一个坐标。如果用简单的逗号split，出来的数组维度就对不上。我在项目里统一用text.trim().split(/\s+/)先按空白切分，再对每个token用逗号切分，这样能兼容绝大多数情况。

2.3 命名空间这个隐形坑必须提前排掉

KML标准有XML命名空间，大部分文件里根节点长这样：

<kml xmlns="http://www.opengis.net/kml/2.2">

这意味着所有子元素的命名空间都是http://www.opengis.net/kml/2.2。很多人在浏览器控制台里测试用doc.querySelector('Placemark')没问题，但放到项目里某些KML文件带了xmlns:gx前缀或者根节点声明位置变了，querySelector直接匹配不到元素。

更稳妥的方式是用getElementsByTagNameNS，先拿到XML文档根节点的命名空间，再按命名空间查找：

const kmlNS = xmlDoc.documentElement.namespaceURI; const placemarks = xmlDoc.getElementsByTagNameNS(kmlNS, 'Placemark');

只有命名空间为null或空时才退回getElementsByTagName。这个细节能避免转换结果忽而正常忽而空数组的诡异问题。

3. 三条转换路线，怎么选

3.1 成熟库方案：先用togeojson跑一遍

npm上有现成的KML转GeoJSON库，最常用的是@tmcw/togeojson，这个库做了很多年，对KML的各种边角情况处理得比较完善，支持Point、LineString、Polygon、MultiGeometry、ExtendedData，甚至能处理gx:Track这种扩展标签。

基本用法：

import { DOMParser } from '@xmldom/xmldom'; import { kml } from '@tmcw/togeojson'; const parser = new DOMParser(); const doc = parser.parseFromString(kmlText, 'application/xml'); const geojson = kml(doc);

注意kml()函数接收的是XML DOM文档对象，不是字符串，所以必须先parse。这个库的优势是省时省力，处理标准KML的正确率很高，如果项目里数据量大、格式相对规范，直接用它是最划算的选择。

3.2 手写解析方案：按需可控

库虽成熟，但有两个问题：一是转换结果的properties字段命名不一定符合业务约定，比如KML里的Data属性可能被展平为name，你必须再写一层map；二是如果KML里混入了自定义扩展标签，库默认会忽略，业务场景需要保留这些数据时就只能手写解析。

手写的核心优势是可控：哪些字段保留、坐标是否保留高度、Folder分组如何映射、样式如何回填，都由自己决定。缺点是代码量不小，而且要处理各种边缘情况。我的建议是：如果转换逻辑以后会扩展，或者数据来源五花八门，手写一套反而比“库+补丁”更干净。

3.3 用EarthSDK3原生能力能行吗

EarthSDK3的KML类加载KML文件后，SDK内部确实会解析数据，但公开API层面能不能直接导出GeoJSON对象，要看具体SDK版本。如果你用的版本提供了类似dataSource或getFeatureCollection之类的接口，直接拿内部解析结果最省事。

不过就我接触过的版本来看，原生能力更多是面向“加载展示”，而不是“数据交换”，想把解析后的对象拿出来做二次处理，接口往往不够直接。所以除非你的需求只是把KML加载到地球上看一眼，否则还是建议在外部完成转换再交给GeoJSON类加载。

3.4 选型对比与最终建议

三条路的优缺点比较如下：

我这边的最终选择是“库起步 + 手写补丁”：先用togeojson处理标准部分，再写一个增强函数，把ExtendedData和Folder层级信息合并进properties。这样既不用从零造轮子，也不用面对库的扩展性瓶颈。

4. 手写一个KML转GeoJSON的完整实现

4.1 从XML到GeoJSON的骨架代码

既然上文提到“手写可控”，这一步直接给出一个能跑的完整实现。整体思路：DOMParser解析XML，按命名空间取所有Placemark，逐个解析属性和几何，最后组装成FeatureCollection。

function kmlToGeoJSON(kmlText) { const parser = new DOMParser(); const xmlDoc = parser.parseFromString(kmlText, 'application/xml'); const kmlNS = xmlDoc.documentElement.namespaceURI || null; const placemarkList = kmlNS ? xmlDoc.getElementsByTagNameNS(kmlNS, 'Placemark') : xmlDoc.getElementsByTagName('Placemark'); const features = []; for (let i = 0; i < placemarkList.length; i++) { const placemark = placemarkList[i]; const feature = parsePlacemark(placemark, kmlNS); if (feature) features.push(feature); } return { type: 'FeatureCollection', features: features }; } function parsePlacemark(placemark, kmlNS) { const properties = parseProperties(placemark, kmlNS); const geometry = parseGeometry(placemark, kmlNS); if (!geometry) return null; return { type: 'Feature', properties: properties, geometry: geometry }; }

这里有个容易被忽略的细节：getElementsByTagNameNS对无命名空间文档会返回空集合，所以要在参数里做null判断，兜底到getElementsByTagName。两种API返回的都是类似数组的集合，但注意它不是真正的Array，直接用forEach会报错，建议用for循环或Array.from转换。

4.2 坐标解析与几何类型映射

坐标解析是整个转换核心。先写一个专门处理KML坐标串的函数：

function parseKMLCoordinates(text) { if (!text) return []; return text .trim() .split(/\s+/) .filter((token) => token.includes(',')) .map((token) => { const parts = token.split(','); const lon = parseFloat(parts[0]); const lat = parseFloat(parts[1]); const alt = parts.length > 2 && parts[2] !== '' ? parseFloat(parts[2]) : null; return alt === null ? [lon, lat] : [lon, lat, alt]; }); }

这个函数做了三件事：去除首尾空白、按空白切分单个坐标串、把“经度，纬度，高度”映射为数组。高度不存在时返回二维坐标，存在时保留三维。做三维地球可视化时，高度往往是必须的。

几何映射要处理Point、LineString、Polygon和MultiGeometry四种情况：

function parseGeometry(placemark, kmlNS) { const types = ['Point', 'LineString', 'Polygon', 'MultiGeometry']; for (const type of types) { const found = placemark.getElementsByTagNameNS(kmlNS, type)[0]; if (found) return parseSingleGeometry(found, kmlNS); } return null; } function parseSingleGeometry(el, kmlNS) { const tagName = el.tagName.replace(/^.*:/, ''); const coords = el.getElementsByTagNameNS(kmlNS, 'coordinates')[0]; if (tagName === 'Point') { return { type: 'Point', coordinates: parseKMLCoordinates(coords.textContent)[0] }; } if (tagName === 'LineString') { return { type: 'LineString', coordinates: parseKMLCoordinates(coords.textContent) }; } if (tagName === 'Polygon') { const outer = el.getElementsByTagNameNS(kmlNS, 'outerBoundaryIs')[0]; const innerList = el.getElementsByTagNameNS(kmlNS, 'innerBoundaryIs'); const rings = []; if (outer) { const outerCoords = outer.getElementsByTagNameNS(kmlNS, 'coordinates')[0]; rings.push(parseKMLCoordinates(outerCoords ? outerCoords.textContent : '')); } for (let i = 0; i < innerList.length; i++) { const innerCoords = innerList[i].getElementsByTagNameNS(kmlNS, 'coordinates')[0]; rings.push(parseKMLCoordinates(innerCoords ? innerCoords.textContent : '')); } return { type: 'Polygon', coordinates: rings }; } if (tagName === 'MultiGeometry') { const children = []; const childrenList = el.childNodes; for (let i = 0; i < childrenList.length; i++) { const child = childrenList[i]; if (child.nodeType !== 1) continue; const childGeom = parseSingleGeometry(child, kmlNS); if (childGeom) children.push(childGeom); } return { type: 'GeometryCollection', geometries: children }; } return null; }

这里有一个关键点：tagName可能因为命名空间前缀而变成gx:Track这类带冒号的值，所以做了replace(/^.*:/, '')来剥离前缀。MultiGeometry里的子节点类型同样可能是Point、LineString等标准类型，递归调用即可。

4.3 属性信息与Folder层级的保留

属性解析分为三部分：name、description和ExtendedData里的Data节点。代码如下：

function parseProperties(placemark, kmlNS) { const props = {}; const nameEl = placemark.getElementsByTagNameNS(kmlNS, 'name')[0]; const descEl = placemark.getElementsByTagNameNS(kmlNS, 'description')[0]; if (nameEl) props.name = nameEl.textContent; if (descEl) props.description = descEl.textContent; const extData = placemark.getElementsByTagNameNS(kmlNS, 'ExtendedData')[0]; if (extData) { const dataList = extData.getElementsByTagNameNS(kmlNS, 'Data'); for (let i = 0; i < dataList.length; i++) { const key = dataList[i].getAttribute('name'); const valueEl = dataList[i].getElementsByTagNameNS(kmlNS, 'value')[0]; if (key && valueEl) props[key] = valueEl.textContent; } } const folderName = findFolderName(placemark, kmlNS); if (folderName) props.folder = folderName; return props; } function findFolderName(placemark, kmlNS) { let node = placemark.parentNode; while (node && node.nodeType === 1) { const tag = node.tagName.replace(/^.*:/, ''); if (tag === 'Folder' || tag === 'Document') { const nameEl = node.getElementsByTagNameNS(kmlNS, 'name')[0]; if (nameEl) return nameEl.textContent; } node = node.parentNode; } return null; }

Folder层级对应业务分组，比如客户数据里文件夹叫“城东片区”，转换后每个Feature的properties.folder就是“城东片区”，前端按这个字段做图层分类很方便。这个逻辑用togeojson默认拿不到，手写的好处就在这里。

4.4 在EarthSDK3中加载转换结果

转换得到GeoJSON对象后，交给EarthSDK3加载。不同版本的SDK接口名可能不完全一致，但整体思路相同：

const geojson = kmlToGeoJSON(kmlText); // EarthSDK3 GeoJSON加载的常见写法 const layer = new earth.GeoJSON(); layer.addData(geojson); // 或 layer.open(geojson)，具体看你的SDK版本 earth.addLayer(layer);

如果SDK的GeoJSON类不支持直接传对象，可以先把GeoJSON字符串化后传给对应接口。注意一点：如果KML坐标带有高度值，而你的场景只做二维显示，建议在parseKMLCoordinates里把第三个值去掉，否则某些SDK会把高度解释成贴地值，导致图形错位。

我实际遇到过一个很隐蔽的问题：部分KML坐标高度是绝对海拔，比如“116.39,39.91,128.5”，但业务里这个值本意是楼层相对高度，直接转成GeoJSON后EarthSDK3把它当成了海拔128.5米，图形飘到空中。解决方式是在转换时加一个高度处理参数，由业务方明确是保留、清零还是按字段映射。

5. 实战踩坑与问题排查实录

5.1 转换结果在EarthSDK3中不显示，先查这4处

如果转换后GeoJSON文件在浏览器里打开是好的，但加载到EarthSDK3里不显示，优先检查四处：第一，坐标数组是否为数字类型，字符串类型的经度纬度会导致部分SDK静默失败；第二，Polygon的坐标环是否闭合，不闭合的环在渲染时可能出现图形不完整或直接不画；第三，GeoJSON的type字段是否写成了featureCollection这种大小写错误；第四，FeatureCollection是否被包裹了一层多余的对象导致SDK取不到features数组。

这类问题用调试函数快速定位：

function inspectGeoJSON(geojson) { console.log('type:', geojson.type); console.log('feature count:', geojson.features ? geojson.features.length : 0); geojson.features.forEach((f, i) => { if (!f.geometry) console.warn(`第${i}个Feature缺少geometry`); if (!f.properties) console.warn(`第${i}个Feature缺少properties`); }); }

转换工具的输出大概率类型是齐全的，但如果你自己在代码中做了二次过滤或属性合并，很容易在某一步把geometry误删，这个函数能快速定位问题索引。

5.2 多边形内外环搞反了怎么办

GeoJSON的Polygon规定：coordinates数组的第一个环必须是外环，后面的是内环（洞）。KML的标准同样是outerBoundaryIs表示外环，innerBoundaryIs表示内环。大多数情况下直接映射没毛病。

但有一种情况要特别留意：部分GIS工具导出的KML把外环写在了innerBoundaryIs里，或者一个多边形同时有多个outerBoundaryIs（严格来说这是非法的，但我就遇到过）。如果转换结果在普通地图上看着正常，在EarthSDK3里渲染时镂空或反色，大概率是环的顺序出了问题。

排查方法很简单：取出第一个环，计算其面积符号。GeoJSON标准要求外环按逆时针顺序（面积值为正），内环按顺时针（面积值为负）。用turf.js的area或手写一个鞋带公式判断：

function ringArea(ring) { let area = 0; for (let i = 0, len = ring.length; i < len; i++) { const [x1, y1] = ring[i]; const [x2, y2] = ring[(i + 1) % len]; area += x1 * y2 - x2 * y1; } return area / 2; }

如果第一个环面积为负，说明方向反了，ring.reverse()一下即可。

5.3 大数据量KML的性能优化

一次性转换包含上万要素、几百万坐标点的KML，主线程会明显卡顿，甚至浏览器崩溃。踩过这个坑之后，我的处理策略是分批转换加视野裁剪。

如果你的KML是按Folder分组的，可以先按Folder拆成多个小任务，逐个转成GeoJSON后合并到目标数组。如果数据量实在太大，建议使用Web Worker做转换，主线程只负责接收结果和加载图层。还要注意转换后的GeoJSON如果包含大量冗余属性，会增加序列化开销，业务不需要的ExtendedData字段可以在parseProperties里直接过滤掉。

另一个容易被忽视的点：坐标精度。原始KML坐标可能保留了6位以上小数，对大多数业务显示来说5位小数（约1米精度）已经足够。转完之后统一做一次精度截断，文件体积能缩小一半以上：

function roundCoords(coords, precision = 5) { return coords.map((coord) => { if (typeof coord[0] === 'number') { return coord.map((v) => (typeof v === 'number' ? Number(v.toFixed(precision)) : v)); } return roundCoords(coord, precision); }); }

5.4 坐标精度与投影“暗雷”

KML标准规定坐标基于WGS84地理坐标系，GeoJSON标准同样要求WGS84，理论上两者可以直接转。但现实中有两类暗雷：

一是部分国内GIS工具导出的KML实际使用了其他地理坐标系，但仍按经纬度方式存储。这种情况下直接转GeoJSON，数据会整体偏移几百米到几公里。处理方式是用proj4js做坐标转换，把原始坐标系先转到WGS84再输出。

二是经纬度坐标经过投影后变成平面坐标（比如UTM），有些KML存的是这类坐标，带了投影坐标相关标签但没明确标注。这时候不能盲目按经纬度解析，需要读取KML的<Model>或元数据中的坐标参考信息。判断方法是看坐标数值范围：经度应该落在[-180,180]，纬度落在[-90,90]，如果出现几百到几千的数值，基本可以确定是投影坐标，必须做逆转换。

5.5 常见问题速查表

5.6 一个容易忽略的Style处理问题

KML的样式不是简单丢不丢的问题。很多KML里的样式写在Document级别的<Style>节点中，Placemark通过<styleUrl>#xxx</styleUrl>引用。转成GeoJSON后，样式信息默认不会带入，前端如果不做任何处理，所有要素都变成默认样式，视觉层次感完全丢失。

我的做法是：转换时把styleUrl记录到properties.styleUrl，再维护一张样式映射表，在EarthSDK3中加载GeoJSON后根据styleUrl字段重新绑定SDK的样式方案。这样做比直接丢弃样式更务实，也保留了业务侧对样式做动态调整的能力。

这趟做下来，最大的体会是：格式转换本身不难，难在细节兜底。命名空间、坐标维度、环的顺序、属性保留、投影转换，每一个环节都可能让最终数据在EarthSDK3里出问题。如果你只是偶尔转几个小文件，在线工具够用；但如果要做项目级的数据流转，务必把转换逻辑写进代码里，并且把上面这些边界情况都处理掉。完成后至少用一段真实业务KML数据做回归测试，再交给下游使用，能省掉大量现场排错的时间。