Three.js怎么读？WebGIS开发入门教程（附：GIS研习社源码）

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

很多刚接触三维 WebGIS 的同学都会先问一个很小但很真实的问题：Three.js怎么读？WebGIS开发入门教程（附：GIS研习社源码）到底应该从哪里开始学？这篇文章用 GIS 开发者的视角，把 Three.js 的读法、它和 WebGIS 的关系、一个最小三维地图场景的搭建步骤，以及学习源码时应该关注的关键点讲清楚。

引言：Three.js怎么读，为什么 WebGIS 开发会用到它

Three.js一般读作“three J S”，也可以理解为“three dot J S”。在中文技术交流里，大家通常直接说“Three JS”或“Three.js”。它不是 GIS 软件，而是一个基于 WebGL 的 JavaScript 三维渲染库。

对 WebGIS 开发者来说，Three.js 的价值在于：当二维地图无法表达高度、体量、倾斜摄影、三维建筑、飞线、三维管线、地形和空间关系时，可以用 Three.js 在浏览器中构建三维场景。

如果你已经会一点 JavaScript、HTML 和地图基础，那么学习 Three.js 并不是为了“做炫酷效果”，而是为了在 WebGIS 项目中解决这些实际问题：

• 把建筑物、管线、设备点位做成三维可视化。
• 在地图上叠加三维模型，例如 GLTF、GLB、OBJ。
• 表达高度、遮挡、视角、光照和空间距离。
• 做三维热力、飞线、轨迹、地形剖面等效果。
• 和 Cesium、Mapbox GL、OpenLayers 等 WebGIS 技术栈配合使用。

背景：WebGIS开发入门为什么不只学 Leaflet 或 OpenLayers

传统 WebGIS 入门通常从 Leaflet、OpenLayers、GeoJSON、WMS、WMTS、XYZ 瓦片开始。这些技术非常重要，适合做二维地图浏览、查询、空间叠加和专题制图。

但现在很多项目已经不满足于二维地图。比如智慧园区、自然资源、城市更新、水利管网、矿山管理、应急指挥、数字孪生等场景，都会涉及三维表达。

这时常见的技术选择有三类：

• Cesium：适合全球尺度三维地球、地形、3D Tiles、倾斜摄影和大范围三维 GIS。
• Mapbox GL / MapLibre GL：适合矢量瓦片、二维到伪三维建筑、地图样式控制。
• Three.js：适合自定义三维场景、模型渲染、动画、特效和业务三维组件。

因此，Three.js 在 WebGIS 开发入门中的定位不是替代所有 GIS 框架，而是补足“浏览器三维渲染能力”。当你需要自己控制相机、灯光、材质、模型、动画和拾取交互时，Three.js 就非常有用。

原理：Three.js 在 WebGIS 中到底负责什么

Three.js 的核心任务是把三维对象渲染到浏览器画布中。它封装了底层 WebGL，让开发者不用直接写大量着色器代码，也能创建三维场景。

一个最小 Three.js 场景通常包含 5 个核心对象：

• Scene：场景，可以理解为三维世界的容器。
• Camera：相机，决定用户从哪里看、怎么看。
• Renderer：渲染器，把三维场景绘制到浏览器中。
• Geometry：几何体，决定对象的形状。
• Material：材质，决定对象的颜色、纹理、透明度和光照效果。

在 WebGIS 项目里，还需要额外理解一个关键问题：三维渲染坐标和 GIS 坐标不是一回事。

GIS 数据常见坐标是经纬度坐标，例如 WGS84 的经度、纬度；也可能是投影坐标，例如 Web Mercator、CGCS2000 高斯投影等。而 Three.js 使用的是三维笛卡尔坐标系，也就是 x、y、z。

所以，把 GIS 数据放进 Three.js 之前，通常要做坐标转换：

• 经纬度坐标需要转换为平面坐标或局部坐标。
• 高度值需要映射到 Three.js 的 z 轴或 y 轴，具体取决于项目约定。
• 大范围坐标要做原点偏移，避免浮点精度问题。
• 地图底图、模型和业务点位必须使用同一套坐标基准。

WebGIS 初学 Three.js 最容易犯的错误，不是代码写不出来，而是没有先搞清楚坐标系、单位和原点。

步骤：用 Three.js 搭建一个 WebGIS 入门三维场景

步骤 1：准备项目环境

入门阶段可以先用普通前端项目，不必一开始就上复杂工程。你至少需要：

• 一个现代浏览器，例如 Chrome、Edge 或 Firefox。
• Node.js 环境，用于安装依赖和启动本地服务。
• 一个代码编辑器，例如 VS Code。
• 基础 JavaScript 知识，包括变量、函数、模块导入。

如果使用 Vite 创建项目，可以这样开始：

npm create vite@latest three-webgis-demo
cd three-webgis-demo
npm install
npm install three
npm run dev

这一步的目标不是做完整 GIS 平台，而是先确保 Three.js 能在浏览器里正常渲染。

步骤 2：创建 Scene、Camera 和 Renderer

下面是一个最小 Three.js 示例。它会在页面中显示一个可旋转观察的立方体。虽然它还不是地图，但这是理解 WebGIS 三维场景的基础。

import * as THREE from 'three'

const scene = new THREE.Scene()
scene.background = new THREE.Color(0xf5f7fa)

const camera = new THREE.PerspectiveCamera(
  60,
  window.innerWidth / window.innerHeight,
  0.1,
  10000
)
camera.position.set(100, 100, 100)
camera.lookAt(0, 0, 0)

const renderer = new THREE.WebGLRenderer({ antialias: true })
renderer.setSize(window.innerWidth, window.innerHeight)
document.body.appendChild(renderer.domElement)

const geometry = new THREE.BoxGeometry(30, 30, 30)
const material = new THREE.MeshStandardMaterial({ color: 0x2f80ed })
const cube = new THREE.Mesh(geometry, material)
scene.add(cube)

const light = new THREE.DirectionalLight(0xffffff, 1)
light.position.set(100, 100, 200)
scene.add(light)

const ambientLight = new THREE.AmbientLight(0xffffff, 0.4)
scene.add(ambientLight)

function animate() {
  requestAnimationFrame(animate)
  cube.rotation.z += 0.01
  renderer.render(scene, camera)
}

animate()

从 GIS 角度看，这个立方体可以理解为一个“建筑物体块”。后续只要把真实建筑轮廓、高度和属性接入，就可以逐步变成三维建筑可视化。

步骤 3：把二维 GIS 要素变成三维对象

WebGIS 中常见的二维要素包括点、线、面。放到 Three.js 中后，可以按下面方式处理：

GIS 要素类型	Three.js 表达方式	典型应用
点	SphereGeometry、Sprite、InstancedMesh	监测站、摄像头、设备点位
线	Line、TubeGeometry、MeshLine 思路	道路、轨迹、管线、飞线
面	ShapeGeometry、ExtrudeGeometry	地块、建筑轮廓、行政区面
栅格	纹理贴图、地形网格	影像底图、DEM 地形、热力图

例如，建筑物面数据可以通过轮廓点生成 Shape，再用 ExtrudeGeometry 挤出高度。这就是很多三维白模建筑的基本思路。

const shape = new THREE.Shape()
shape.moveTo(0, 0)
shape.lineTo(40, 0)
shape.lineTo(40, 30)
shape.lineTo(0, 30)
shape.lineTo(0, 0)

const extrudeSettings = {
  depth: 50,
  bevelEnabled: false
}

const buildingGeometry = new THREE.ExtrudeGeometry(shape, extrudeSettings)
const buildingMaterial = new THREE.MeshStandardMaterial({
  color: 0x9bbcff,
  transparent: true,
  opacity: 0.85
})

const building = new THREE.Mesh(buildingGeometry, buildingMaterial)
scene.add(building)

实际项目中，建筑轮廓可能来自 GeoJSON、Shapefile 转换结果、PostGIS 查询结果或接口返回数据。重点是先统一坐标，再生成几何。

步骤 4：加入地图语义，而不是只做三维动画

WebGIS 开发入门不能只停留在“能显示三维对象”。真正的 GIS 项目还需要属性、查询、定位和空间关系。

建议你在 Three.js 场景中保留每个对象的业务属性：

building.userData = {
  id: 'B001',
  name: '1号教学楼',
  height: 50,
  type: 'building'
}

这样后续做鼠标拾取时，就可以根据对象属性弹出信息面板、联动表格或高亮地图对象。

Three.js 中常用 Raycaster 做拾取。它的作用类似从相机向鼠标位置发出一条射线，判断射线击中了哪些三维对象。

const raycaster = new THREE.Raycaster()
const mouse = new THREE.Vector2()

window.addEventListener('click', function (event) {
  mouse.x = (event.clientX / window.innerWidth) * 2 - 1
  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1

  raycaster.setFromCamera(mouse, camera)
  const intersects = raycaster.intersectObjects(scene.children, true)

  if (intersects.length > 0) {
    const object = intersects[0].object
    console.log(object.userData)
  }
})

这一步是 Three.js 从“三维展示”进入“WebGIS 交互”的关键。

常见坑：Three.js WebGIS 入门最容易卡住的地方

坑 1：经纬度直接当 Three.js 坐标使用

经纬度单位是度，Three.js 坐标通常按线性单位处理。如果直接把经纬度作为 x、y 坐标，距离、形状和比例都会出问题。

正确做法是先把经纬度转换成合适的投影坐标，或者转换到局部平面坐标。小范围项目可以选一个局部原点，把所有坐标减去原点坐标，减少数值过大带来的精度问题。

坑 2：模型看不见，以为是加载失败

Three.js 中对象看不见，常见原因不一定是模型坏了。你应该按顺序检查：

• 相机是否看向模型所在位置。
• 模型尺寸是否太大或太小。
• near 和 far 裁剪面是否设置合理。
• 灯光是否存在，材质是否需要光照。
• 模型是否被放在相机背后。
• 坐标轴方向是否和预期一致。

坑 3：地图底图和三维对象对不上

这是 WebGIS 中非常典型的问题。原因通常包括：

• 底图使用 Web Mercator，而业务数据是 CGCS2000 或 WGS84。
• 三维对象做了原点偏移，但底图没有同步偏移。
• 高度单位和水平单位不一致。
• 模型本身带有局部坐标，没有正确放置到地图坐标中。

排查时不要一上来调代码效果，先确认数据坐标系、单位、范围和原点。

坑 4：三维场景卡顿，只会盲目减少对象

Three.js 性能问题不只是对象数量问题，还和材质、纹理、灯光、阴影、几何复杂度、透明物体和渲染频率有关。

入门阶段可以先做这些优化：

• 重复点位使用 InstancedMesh。
• 减少高精度曲面和复杂模型。
• 尽量合并静态几何体。
• 控制纹理尺寸，不要无脑使用超大图片。
• 非必要不要开启实时阴影。
• 按视距或范围加载数据。

方法比较：Three.js、Cesium、OpenLayers 在 WebGIS 中怎么选

工具	适合场景	优势	限制
Three.js	自定义三维场景、模型、动画、三维业务组件	渲染自由度高，适合定制效果	GIS 能力需要自己补充，坐标和数据管理要手动处理
Cesium	三维地球、倾斜摄影、3D Tiles、地形、大范围场景	GIS 三维能力完整，适合真实地理空间	自定义底层渲染效果相对复杂
OpenLayers	二维地图、OGC 服务、矢量编辑、坐标转换	二维 WebGIS 能力强，工程稳定	三维表达能力不是重点
Leaflet	轻量二维地图、业务点线面展示	简单易学，生态丰富	复杂三维和重型 GIS 能力有限

如果你的目标是 WebGIS 开发入门，建议先掌握二维地图基础，再学习 Three.js。这样你不会把三维渲染误认为 GIS 的全部，也不会忽略坐标系、数据格式、空间查询这些核心能力。

一个比较稳妥的学习路径是：

1. 先学 HTML、CSS、JavaScript 和浏览器调试。
2. 再学 GeoJSON、坐标系、瓦片地图和基本空间数据结构。
3. 使用 Leaflet 或 OpenLayers 做二维 WebGIS 项目。
4. 学习 Three.js 的场景、相机、渲染器、几何体、材质和拾取。
5. 把 GIS 点线面数据转换成 Three.js 对象。
6. 再根据项目需要学习 Cesium、3D Tiles、地形和倾斜摄影。

检查清单：学习 GIS研习社源码时重点看什么

如果你拿到 GIS研习社源码，不要只看页面效果。建议按下面清单阅读源码，这样更容易从“能运行”变成“能改、能用、能扩展”。

• 入口文件：看 Three.js 场景从哪里初始化。
• 相机设置：看 camera 的位置、视角、near、far 和 lookAt。
• 渲染循环：看 requestAnimationFrame 中更新了哪些对象。
• 数据来源：看点、线、面、模型数据来自本地文件还是接口。
• 坐标处理：看是否做了投影转换、原点偏移或比例缩放。
• 对象组织：看是否用 Group、Layer 或 userData 管理业务对象。
• 交互逻辑：看点击、悬停、选中、高亮是怎么实现的。
• 性能处理：看是否做了合批、实例化、按需加载或资源释放。
• 样式和材质：看不同业务类型是否有统一的颜色和材质规则。
• 异常处理：看模型加载失败、接口失败、空数据时是否有提示。

读源码时可以先给自己设一个小目标：不要急着重写项目，先能把一个点位换成自己的数据，把一个模型换成自己的 GLB，把一个弹窗字段改成自己的属性。

FAQ：Three.js怎么读与 WebGIS开发入门常见问题

Three.js到底怎么读？

Three.js 通常读作“three J S”。在中文交流中说“Three JS”大家都能理解。它的重点不在读音，而在于它是浏览器端三维渲染库，适合 WebGIS 三维场景开发。

Three.js 是不是 GIS 框架？

严格来说不是。Three.js 主要解决三维渲染问题，不直接提供完整 GIS 数据管理、投影转换、空间分析、地图服务加载等能力。WebGIS 项目中通常需要把 Three.js 和 GIS 数据处理、地图框架或后端服务结合起来。

WebGIS 入门应该先学 Three.js 还是 Cesium？

如果目标是三维地球、倾斜摄影、3D Tiles 和真实地理场景，优先学 Cesium 更直接。如果目标是自定义三维模型、业务三维组件和前端三维渲染基础，可以先学 Three.js。更推荐的路径是先掌握二维 WebGIS，再根据项目需求选择 Three.js 或 Cesium。

GeoJSON 能直接加载到 Three.js 吗？

可以读取 GeoJSON，但不能像在 Leaflet 或 OpenLayers 中那样直接作为地图图层显示。你需要解析 GeoJSON 的点、线、面坐标，把它们转换成 Three.js 的几何体，并处理坐标投影和原点偏移。

Three.js 做 WebGIS 为什么经常出现坐标偏移？

最常见原因是坐标系不一致。例如底图是 Web Mercator，业务数据是经纬度，模型又是局部坐标。另一个常见原因是没有做原点偏移，导致大坐标在 WebGL 中产生精度问题。解决时应先统一坐标系，再统一单位和原点。

GIS研习社源码适合初学者怎么用？

建议先运行源码，再按模块阅读。不要一开始就改复杂功能。先从场景初始化、相机、灯光、模型加载、鼠标拾取和数据绑定这些基础模块入手，然后逐步替换为自己的 GIS 数据。

结论：把 Three.js 当作 WebGIS 三维能力的一块拼图

回到最开始的问题，Three.js 可以读作“three J S”。但对 GIS 学习者来说，更重要的是理解它在 WebGIS 开发入门中的位置：它负责三维渲染，不等于完整 GIS 平台。

学习 Three.js 做 WebGIS，建议始终围绕三个关键词：坐标、数据、交互。先把 GIS 数据放到正确的位置，再用 Three.js 表达三维形态，最后加入拾取、查询、弹窗和业务联动。

如果你正在看 GIS研习社源码，可以先从最小场景开始复现，再逐步替换自己的点线面、建筑模型和业务属性。这样学习 Three.js 不会停留在动画演示，而能真正服务于 WebGIS 项目开发。