three.js KMZLoader 实战详解：在 Web 端加载并渲染 KML 压缩包中的 3D 模型-开发者社区

three.js KMZLoader 实战详解：在 Web 端加载并渲染 KML 压缩包中的 3D 模型

【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js

KMZ 是由 Google Earth 生态衍生的一种压缩归档格式，常被用于承载地理标注与三维模型。本文以 three.js 官方示例库中的 KMZLoader 为主线索，讲解它的继承体系、加载/解析流程、底层实现与完整可运行示例，帮助你掌握在浏览器中把.kmz归档内的 COLLADA（.dae）模型及其贴图还原为 three.js 场景对象的完整方法。

KMZ 是什么，为什么需要专门的加载器

KMZ（Keyhole Markup Language Zip）本质上是以 ZIP 方式打包的 KML 压缩档案。一个典型的 KMZ 归档内会包含：

doc.kml：KML 主文档，负责声明Placemark及模型引用关系；
被引用的模型文件（本项目对应的模型体是 COLLADA.dae格式）；
模型使用的贴图等附属资源。

在 three.js 中，由于 KML 中常见的模型载体是 COLLADA 格式，因此KMZLoader并非从零实现几何解析，而是遵循“解压 → 找到doc.kml→ 定位<Model><Link><href>指向的.dae→ 交给ColladaLoader解析”的职责链来完成工作。仓库中的示例模型 Box.kmz 及其说明 Readme.txt 明确记录了“Box.dae in Box.kmz”这一格式来源。

从源码结构看，该加载器以**插件（addon）**形式提供，位于 examples/jsm/loaders/KMZLoader.js，并统一收录在 examples/jsm/Addons.js 的加载器导出列表中，需要像其他附加组件一样显式导入后才能使用。

快速上手：最简加载示例

官方文档给出了最精简的用法——利用继承自Loader基类的loadAsync()以 Promise 方式加载，然后直接取kmz.scene加入场景：

const loader = new KMZLoader(); const kmz = await loader.loadAsync( './models/kmz/Box.kmz' ); scene.add( kmz.scene );

其中kmz是解析结果对象，其.scene属性是一个可直接挂载到场景树的组（由内部ColladaLoader产出）。仓库内完整的演示页面位于 examples/webgl_loader_kmz.html，它搭建了摄像机、方向光、网格辅助线与轨道控制器，并在回调中把加载结果放置到场景：

import * as THREE from 'three'; import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; import { KMZLoader } from 'three/addons/loaders/KMZLoader.js'; const loader = new KMZLoader(); loader.load( './models/kmz/Box.kmz', function ( kmz ) { kmz.scene.position.y = 0.5; scene.add( kmz.scene ); render(); } );

上面这份代码是完整可运行的范式：模型加载完成后调用一次render()触发首次绘制，此后由OrbitControls的change事件继续驱动重绘。

导入方式与模块定位

KMZLoader属于 three.js 的 addon 模块，不会被打包进核心构建，必须显式导入（对应文档中的 “Addons 安装说明”）：

import { KMZLoader } from 'three/addons/loaders/KMZLoader.js';

在仓库源码中它导出自 examples/jsm/loaders/KMZLoader.js，并在 examples/jsm/Addons.js 中以export * from './loaders/KMZLoader.js';对外汇总。依赖关系上，它运行时还需要同目录下的ColladaLoader（examples/jsm/loaders/ColladaLoader.js）与内置解压库fflate（examples/jsm/libs/fflate.module.js）。

继承关系

类定义声明为class KMZLoader extends Loader，即完整的继承链为：

Loader（抽象基类） └── KMZLoader

因此它自动继承了基类 Loader 提供的全部能力，包括：loadAsync()（Promise 包装）、setPath()、setCrossOrigin()、setRequestHeader()、setWithCredentials()以及默认使用全局DefaultLoadingManager的manager属性等。这些配置项会在load()内部被逐一应用到实际承担网络请求的FileLoader上。

构造器

`new KMZLoader( manager : LoadingManager )`

构造一个新的 KMZ 加载器实例，参数与基类约定一致：

manager：加载管理器实例，用于协调/追踪该加载器发起的全部资源请求。省略时会回落到Loader基类默认的DefaultLoadingManager。

从源码看，构造器内部仅做了一件事——调用super( manager )把管理器交给基类持有，并无额外的成员初始化。

方法详解

`.load( url, onLoad, onProgress, onError )`

从给定的 URL 开始加载，并把加载完成的 KMZ 资源对象传给onLoad()回调。对应源码实现于 KMZLoader.js，其内部执行逻辑为：

新建一个FileLoader，并继承当前 loader 的path、requestHeader、withCredentials等配置；
调用loader.setResponseType( 'arraybuffer' )，强制以二进制 ArrayBuffer 形式请求数据——这是后续 ZIP 解压的前提；
在成功回调里执行scope.parse( text )，并用try/catch包裹：
- 解析成功 → 调用onLoad( 解析结果 )；
- 解析失败 → 若提供了onError则回调它，否则打印console.error，最后调用scope.manager.itemError( url )通知加载管理器该条目失败。

参数：

url：待加载文件的路径或 URL，也支持 data URI；
onLoad：加载与解析全部完成后执行，收到形如{ scene: Group }的解析结果；
onProgress：加载过程中持续触发（ProgressEvent回调）；
onError：发生错误时执行。

该方法在基类之上覆写了 Loader#load（文档标注为Overrides）。实际网络请求并非由KMZLoader自己发起，而是委托给FileLoader完成，这与仓库中其他大多数加载器（如 ColladaLoader.js 的load）的设计一致。

`.parse( data : ArrayBuffer ) : Object`

解析给定的 KMZ 二进制数据，返回承载着场景的对象。这是整个加载器最核心、最有技术含量的部分（源码），完整的内部流程可以拆解为以下五步：

第一步：ZIP 解压

const zip = unzipSync( new Uint8Array( data ) );

data是ArrayBuffer，先包装为Uint8Array，再交给从fflate导入的unzipSync()同步解压，得到一个“归档内路径 → 二进制数据”的映射对象zip。

第二步：解析doc.kml并寻找模型引用

const xml = new DOMParser().parseFromString( new TextDecoder().decode( zip[ 'doc.kml' ] ), 'application/xml' ); const model = xml.querySelector( 'Placemark Model Link href' );

若归档内存在doc.kml，先用TextDecoder把它从二进制解码为 UTF-8 文本，再用浏览器内置DOMParser解析成 XML 文档，最后通过选择器'Placemark Model Link href'定位到 KML 中<Placemark><Model><Link><href>指向的相对路径文本。

第三步：把.dae模型体交给ColladaLoader

const loader = new ColladaLoader( manager ); return loader.parse( new TextDecoder().decode( zip[ model.textContent ] ) );

以model.textContent（例如models/Box.dae）作为zip的键取出对应的.dae文件内容，解码为字符串后直接调用ColladaLoader.parse()完成 COLLADA 的几何、材质、动画组装。这一步意味着 KMZLoader 的最终渲染质量与ColladaLoader支持的特性子集绑定。

第四步（兜底路径）：没有doc.kml时直接扫描.dae

console.warn( 'KMZLoader: Missing doc.kml file.' ); for ( const path in zip ) { const extension = path.split( '.' ).pop().toLowerCase(); if ( extension === 'dae' ) { const loader = new ColladaLoader( manager ); return loader.parse( new TextDecoder().decode( zip[ path ] ) ); } }

如果归档中缺失doc.kml，加载器打印console.warn警告，然后遍历zip的全部条目，按扩展名（取最后一个.后的小写片段）找出第一个.dae文件并解析。这提高了对“仅打包模型、不含 KML 主文档”这类非标准 KMZ 的容错性。

第五步：彻底失败的兜底返回值

console.error( 'KMZLoader: Couldn\'t find .dae file.' ); return { scene: new Group() };

若前两步都找不到可用的.dae，则打印console.error并返回一个空的Group作为scene。从源码结构可以推断：这样设计是为了保证load回调总能拿到结构合法的结果对象，避免因返回值为空导致上层应用解构崩溃；但调用方应留意这种“静默空场景”的失败形态。

参数与返回值：

data：KMZ 原始二进制数据（ArrayBuffer）；
返回：解析后的资源对象{ scene: Group }（来自ColladaLoader，实际还附带animations、kinematics、library等字段，见 ColladaLoader.js）。

`.loadAsync( url, onProgress )`

该接口并非在KMZLoader中重新实现，而是继承自Loader基类的 Promise 版加载方法，内部对load()做了 Promise 封装。适合现代async/await写法，也是官方文档首个代码示例所用的方式。

关键实现细节：贴图如何在 KMZ 内部解析

ColladaLoader在解析.dae时会根据文档引用的相对路径去请求贴图资源。为了让这些贴图也能从 KMZ 归档内部解出来而不是向服务器发出无效请求，KMZLoader.parse()做了精巧的旁路处理：

const manager = new LoadingManager(); manager.setURLModifier( function ( url ) { const image = findFile( url ); if ( image ) { console.log( 'Loading', url ); const blob = new Blob( [ image.buffer ], { type: 'application/octet-stream' } ); return URL.createObjectURL( blob ); } return url; } );

其工作原理是：

parse()内部新建一个独立的LoadingManager，并通过setURLModifier注册 URL 改写钩子；
内部定义的findFile( url )遍历zip的所有键，用“路径后缀匹配”（path.slice( - url.length ) === url）来匹配.dae中引用的贴图路径；
命中后把归档内的二进制数据包装成Blob，再用URL.createObjectURL()生成一个临时对象 URL 交给后续的贴图加载器使用；
未命中的 URL（如外部绝对地址）原样返回，保持默认加载行为。

这个新建的manager在创建ColladaLoader时被注入（new ColladaLoader( manager )），从而让 COLLADA 解析链路中的纹理加载也走同一套 URL 改写逻辑。这正是 KMZ 模型“连同贴图一起离线打包、一次性加载”得以成立的关键机制。

坐标系统与单位换算

KMZ 中承载的.dae最终交由ColladaLoader解析，因此 COLLADA 侧的通用约定也适用于此：

若资产的upAxis声明为Z_UP，ColladaLoader会打印警告并通过scene.rotation.set( - Math.PI / 2, 0, 0 )将整个模型旋转为 three.js 的 Y-UP 约定（仅旋转不转换顶点数据）；
若资产声明了unit单位，会通过scene.scale.multiplyScalar( asset.unit )对场景进行整体缩放。

这些行为定义在 ColladaLoader.js，在通过 KMZLoader 加载经 Google Earth 工具导出的模型时同样生效，是保证模型在地球坐标与本地坐标间正确呈现的重要前提。

实际应用注意事项

加载纹理的 CORS 与临时 URL 生命周期：parse()通过URL.createObjectURL生成临时贴图 URL，浏览器会为每个场景维持其存活；频繁重复加载同一 KMZ 会产生多个临时对象，内存敏感场景下需关注对象生命周期管理。
缺失/损坏归档的行为差异：缺少doc.kml会触发console.warn并回退到扫描.dae；既无doc.kml也无任何.dae时返回空Group。排查问题时请结合控制台信息区分这两种失败路径。
parse与网络层分离：parse( data )不关心数据来源，因此既可以用在load()内部，也可以对自行 fetch 到的 ArrayBuffer 直接调用，方便做离线缓存或自定义传输。
跨域与请求头：所有Loader基类配置（setPath、setCrossOrigin、setRequestHeader、setWithCredentials）都会被透传到内部的FileLoader；从其他域名加载 KMZ 时需保证目标服务器允许跨域访问。
data URI 支持：url参数同样接受 data URI 形式的二进制数据，文档中已明确标注这一能力。