Three.js下载哪个版本最稳定？WebGIS开发必备资源清单（附：官方地址）

wowwwai GIS研习社 · 工具流程与项目排障

《Three.js下载哪个版本最稳定？WebGIS开发必备资源清单（附：官方地址）》这个问题，很多 WebGIS 开发者都会遇到：项目要做三维地图、倾斜摄影、点云、轨迹飞线或 Cesium 外的轻量三维场景，但打开 Three.js 官网和 GitHub 后，发现版本很多、示例很多、CDN 地址也很多，不知道到底该下载哪一个。

本文按 WebGIS 项目落地的角度，说明 Three.js 稳定版本怎么选、官方资源从哪里下载、哪些文件必须配套使用，以及在 GIS 场景中最容易踩的版本坑。

引言：Three.js 下载哪个版本最稳定

如果你只是想要一个直接结论：WebGIS 项目不要随意下载 master/main 分支源码，也不要长期使用非常旧的教程版本；优先选择 Three.js 官方发布的稳定 Release，并在项目中锁定版本号。

对大多数 WebGIS 项目来说，推荐使用以下策略：

• 新项目：使用 npm 安装 three，并锁定一个明确版本。
• 传统静态页面项目：使用官方 CDN 或下载对应 Release 包。
• 生产项目：不要使用 latest 作为线上依赖，必须固定版本。
• 跟教程学习：优先使用教程对应的 Three.js 版本，否则示例代码可能跑不起来。
• 需要 OrbitControls、GLTFLoader、CSS2DRenderer 等扩展：必须保证 examples 目录下的扩展文件和 three 核心库来自同一个版本。

Three.js 更新频率较高，不同版本之间会出现 API 调整。对 WebGIS 开发来说，稳定不是指“版本越老越好”，而是指核心库、扩展模块、构建工具和业务代码之间版本一致，并且可重复部署。

背景：为什么 WebGIS 开发容易选错 Three.js 版本

Three.js 是一个基于 WebGL 的三维渲染库，常用于浏览器端三维可视化。WebGIS 开发中常见用途包括：

• 三维建筑白模展示。
• 点云、管线、轨迹、飞线可视化。
• 与 Leaflet、OpenLayers 叠加三维图层。
• 与地理坐标转换结果结合，渲染局部三维场景。
• 加载 glTF、GLB、OBJ、FBX 等三维模型。
• 制作自定义三维地图效果，而不是完整使用 Cesium。

问题在于，Three.js 的生态资源比较分散。你可能会同时看到这些入口：

• 官网文档。
• GitHub 仓库。
• GitHub Releases。
• npm 包。
• unpkg、jsDelivr 等 CDN。
• examples 目录中的加载器和控制器。
• 各种旧教程里的 three.min.js、OrbitControls.js。

很多 WebGIS 初学者遇到的报错，并不是 GIS 算法错了，而是 Three.js 版本没有对齐。例如：

• THREE.OrbitControls is not a constructor
• THREE.GLTFLoader is not a constructor
• Cannot use import statement outside a module
• BufferGeometry.addAttribute is not a function
• Geometry is not a constructor
• Unexpected token export

这些错误通常和 Three.js 版本、模块格式、扩展文件来源有关。

原理：Three.js 稳定版本到底看什么

判断 Three.js 下载哪个版本最稳定，不能只看“最新”或“下载量”。在 WebGIS 项目中，应该看四个维度。

1. 是否来自官方发布渠道

推荐优先使用官方渠道：

• 官网：https://threejs.org/
• 官方文档：https://threejs.org/docs/
• 官方示例：https://threejs.org/examples/
• GitHub 仓库：https://github.com/mrdoob/three.js
• GitHub Releases：https://github.com/mrdoob/three.js/releases
• npm 包：https://www.npmjs.com/package/three

不要从来源不明的网盘、博客附件或复制来的压缩包中下载 Three.js。尤其是 WebGIS 项目常涉及内网部署、政企数据和安全审查，依赖来源必须可追溯。

2. 是否固定版本号

稳定的关键是固定版本。例如 npm 项目中推荐明确安装：

npm install three@0.xxx.x

这里的 0.xxx.x 应替换为你决定使用的官方稳定版本。不要在生产环境中依赖不固定的 latest，否则同一套代码在不同时间安装，可能得到不同 Three.js 版本。

3. 核心库和 examples 扩展是否同版本

Three.js 的很多常用功能不在核心库里，而在 examples 模块中，例如：

• OrbitControls：鼠标旋转、缩放、平移控制。
• MapControls：更接近地图交互习惯的控制器。
• GLTFLoader：加载 glTF、GLB 模型。
• DRACOLoader：加载 Draco 压缩模型。
• CSS2DRenderer：用于标签标注。
• EffectComposer：后处理效果。

这些扩展必须和 three 核心库使用同一个版本。不要用新版 three.module.js 搭配旧版 OrbitControls.js。

4. 是否符合你的项目构建方式

Three.js 现在更推荐模块化导入。WebGIS 项目常见两种方式：

• Vite、Webpack、Vue、React 项目：使用 npm 和 ES Module。
• 传统 HTML 页面：使用 CDN 的模块地址，或使用下载后的构建文件。

如果你的项目已经使用 Vite 或 Webpack，建议走 npm；如果只是一个教学演示页面，可以使用 CDN，但也要固定版本号。

步骤：WebGIS 项目如何正确下载和使用 Three.js

步骤 1：先判断你的 WebGIS 项目类型

下载 Three.js 前，先判断项目属于哪一类：

项目类型	推荐方式	适用场景
Vite / Vue / React WebGIS 项目	npm 安装 three	正式开发、组件化项目、工程化构建
原生 HTML 教学 Demo	CDN 固定版本	快速验证三维效果、课程实验
内网离线部署项目	下载官方 Release 或 npm 包后本地托管	政企内网、无外网服务器
旧项目维护	保留旧版本并记录版本号	避免升级引发 API 兼容问题

步骤 2：npm 项目推荐安装方式

如果你做的是现代 WebGIS 前端项目，例如 Vue3 加 OpenLayers 再叠加 Three.js 三维图层，推荐使用 npm。

npm install three@0.xxx.x

在代码中导入：

import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';

如果你更偏地图交互，可以考虑 MapControls：

import { MapControls } from 'three/examples/jsm/controls/MapControls.js';

这种方式的优点是依赖清晰，构建工具会处理模块路径，后期也方便做代码分包和性能优化。

步骤 3：CDN 项目推荐写法

如果你只是写一个静态 HTML 示例，不想配置 npm，可以使用 CDN。但要注意：CDN 也要固定版本。

import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.xxx.x/build/three.module.js';
import { OrbitControls } from 'https://cdn.jsdelivr.net/npm/three@0.xxx.x/examples/jsm/controls/OrbitControls.js';
import { GLTFLoader } from 'https://cdn.jsdelivr.net/npm/three@0.xxx.x/examples/jsm/loaders/GLTFLoader.js';

这里的核心要点是：three.module.js、OrbitControls.js、GLTFLoader.js 的版本号必须一致。

步骤 4：离线部署项目怎么准备资源

很多 GIS 项目部署在内网，不能直接访问 CDN。这时建议按以下方式处理：

1. 在联网开发机上通过 npm 安装固定版本的 three。
2. 确认业务代码可以正常运行。
3. 将需要的资源复制到项目静态目录，例如 /libs/three/。
4. 同时复制 build 和 examples/jsm 中实际用到的模块。
5. 记录版本号、下载时间和来源地址。
6. 在内网环境中使用本地路径加载。

离线项目不要只拷贝 three.module.js，因为加载 glTF、控制器、后处理、标签等功能时，还需要 examples 中的模块文件。

步骤 5：WebGIS 常用 Three.js 资源清单

下面是 WebGIS 开发中比较常用的 Three.js 官方资源清单。

资源	用途	官方地址
Three.js 官网	查看入口、示例和文档	https://threejs.org/
Three.js 文档	查询类、方法、参数	https://threejs.org/docs/
Three.js Examples	查找官方示例代码	https://threejs.org/examples/
GitHub 仓库	查看源码、Issue、历史变更	https://github.com/mrdoob/three.js
GitHub Releases	下载指定发布版本	https://github.com/mrdoob/three.js/releases
npm 包	工程化项目安装依赖	https://www.npmjs.com/package/three
jsDelivr CDN	静态页面快速引用	https://cdn.jsdelivr.net/npm/three@版本号/
unpkg CDN	静态页面快速引用	https://unpkg.com/three@版本号/

常见坑：Three.js 版本不稳定通常不是下载错，而是用法错

坑 1：使用 latest 导致项目突然报错

很多示例会写：

https://cdn.jsdelivr.net/npm/three/build/three.module.js

这种写法没有固定版本。今天能运行，不代表以后还能运行。WebGIS 项目上线后，地图组件、三维模型、坐标转换逻辑都依赖前端渲染稳定性，因此不要这样写。

应改成：

https://cdn.jsdelivr.net/npm/three@0.xxx.x/build/three.module.js

坑 2：核心库和扩展文件版本不一致

这是最常见的 Three.js 下载版本问题。比如核心库来自新版 CDN，但 OrbitControls.js 是从旧博客复制来的。结果就是构造函数不存在、模块导入失败或交互异常。

解决办法很简单：同一个项目中，所有 Three.js 相关文件都来自同一版本、同一渠道。

坑 3：照搬旧教程里的 Geometry 写法

不少早期 Three.js 教程使用 Geometry，但现代版本中已经转向 BufferGeometry。如果你照搬旧教程生成点、线、面，很容易报错。

WebGIS 中绘制轨迹线、行政边界、格网、点云时，应优先使用 BufferGeometry，因为它更适合大规模数据渲染。

坑 4：把地理坐标直接当 Three.js 坐标

Three.js 本身不理解经纬度。经纬度是地理坐标，Three.js 渲染使用的是笛卡尔坐标。WebGIS 中如果直接把经纬度作为 x 和 z，小范围看似可用，大范围会出现比例、方向、精度问题。

一般做法是：

• 先把经纬度转换到合适的投影坐标。
• 选择一个局部原点，减去原点坐标。
• 再把相对坐标传给 Three.js。
• 必要时统一单位，例如米。

坑 5：模型加载器缺少配套资源

使用 GLTFLoader 加载三维模型时，如果模型用了 Draco 压缩，还需要 DRACOLoader 和解码器文件。只下载 GLTFLoader.js 不够。

如果加载的是 KTX2 纹理，还需要对应纹理加载器和转码资源。WebGIS 三维模型数据量通常较大，模型压缩和纹理资源路径要一起检查。

方法比较：npm、CDN、GitHub Release 该选哪个

方式	优点	缺点	推荐程度
npm 安装	版本可控，适合工程化，方便打包	需要 Node.js 和构建工具	正式 WebGIS 项目优先推荐
CDN 固定版本	上手快，适合教学和 Demo	依赖外网，生产环境可控性较弱	适合快速验证
GitHub Release 下载	来源清晰，可离线保存	需要手动管理文件关系	适合内网和归档
复制博客附件	看似方便	版本不可追溯，安全和兼容风险高	不推荐

如果你是 GIS 学生或刚入门的 WebGIS 开发者，建议先用 CDN 固定版本完成 Demo，再切换到 npm 项目。如果你在做正式项目，直接使用 npm，并把版本写入 package.json 和项目文档。

检查清单：下载 Three.js 前后必须确认这些项

• 是否从官网、GitHub、npm 或可信 CDN 获取 Three.js。
• 是否固定了明确版本号。
• three 核心库与 examples/jsm 扩展是否同版本。
• 是否确认教程代码与当前 Three.js 版本兼容。
• 是否避免使用未固定版本的 latest 地址。
• 是否记录了版本号和下载来源。
• 离线部署时，是否把加载器、控制器、解码器一起复制。
• 是否确认浏览器支持 WebGL。
• 是否把经纬度转换为适合 Three.js 的局部坐标。
• 是否对大规模 GIS 数据做了抽稀、切片、分层或实例化优化。

FAQ：Three.js 下载和 WebGIS 使用常见问题

Q1：Three.js 下载哪个版本最稳定？

对 WebGIS 项目来说，最稳定的不是某一个永久固定的版本号，而是官方 Release、固定版本、依赖一致、经过项目测试的版本。新项目可以选择官方当前稳定发布版，但上线后要锁定版本，不要自动追随 latest。

Q2：能不能直接下载 GitHub main 分支使用？

不建议。main 分支是持续开发中的代码，可能包含未发布或正在调整的内容。正式项目应使用 GitHub Releases、npm 指定版本或固定版本 CDN。

Q3：为什么 Three.js 示例能运行，我的项目不能运行？

常见原因是模块路径、版本号或构建方式不同。官方示例通常使用同一套版本和相对路径，你的项目如果混用了 CDN、npm、旧版扩展文件，就容易失败。

Q4：WebGIS 项目中用 OrbitControls 还是 MapControls？

如果你做普通三维模型查看，OrbitControls 足够。如果你希望交互更接近地图浏览，例如平移、缩放和俯视操作，MapControls 更适合。两者都要从同版本的 three/examples/jsm/controls/ 中导入。

Q5：Three.js 可以替代 Cesium 做三维 GIS 吗？

不能简单替代。Three.js 是通用三维渲染库，适合自定义三维场景、局部模型、可视化特效和轻量三维图层。Cesium 更偏全球地形、3D Tiles、地球坐标和三维 GIS 平台。如果需要全球尺度地形和倾斜摄影，Cesium 通常更合适；如果是局部场景和自定义渲染，Three.js 更灵活。

Q6：Three.js 加载 GIS 数据很卡怎么办？

先检查数据量和渲染方式。大规模点、线、面不要逐个创建 Mesh。可考虑 BufferGeometry、合并几何、实例化渲染、数据抽稀、瓦片化加载和按视野动态加载。WebGIS 性能问题通常不是 Three.js 版本本身导致，而是数据组织方式不适合浏览器渲染。

Q7：旧项目要不要升级 Three.js？

如果旧项目运行稳定，不建议为了“版本新”而盲目升级。升级前应先查看 Release 说明，重点检查 Geometry、材质、加载器、控制器、模块路径和渲染器参数是否有变化。建议在测试分支中升级，并准备回退方案。

结论：WebGIS 项目选择 Three.js 版本的推荐方案

Three.js 下载哪个版本最稳定，核心答案是：选择官方稳定发布版，并在项目中固定版本；核心库、examples 扩展、模型加载器和 CDN/npm 来源必须保持一致。

如果你正在做 WebGIS 开发，可以按这个优先级选择：

1. 正式工程项目：使用 npm 安装固定版本的 three。
2. 教学或快速 Demo：使用固定版本号的 CDN。
3. 内网项目：从官方 Release 或 npm 包整理本地依赖。
4. 旧项目维护：保留可运行版本，谨慎升级。

最后记住一句话：Three.js 的稳定性不只取决于下载哪个版本，更取决于你是否把版本、模块、加载器、坐标处理和部署环境统一管理好。对于 WebGIS 项目，这比追求“最新版本”更重要。