TerriaMap 开发实战01：从零搭建一个可定制的三维地理信息平台

发布时间：2026/11/5 6:53:01
TerriaMap 开发实战01：从零搭建一个可定制的三维地理信息平台

文章目录

  • 一、写在前面：为什么是 TerriaJS
  • 二、Terria系列：体系里的五个角色
  • 三、TerriaMap介绍
  • 四、TerriaMap Start教程
  • 五、TerriaMap 目录结构
  • 六、总结

一、写在前面：为什么是 TerriaJS

如果你做过三维 GIS 项目，大概率经历过这样的过程：

  1. 先用 Cesium 把地球转起来；

  2. 然后自己写图层管理、目录树、图例、时间轴、底图切换；

  3. 再补上 GeoJSON、WMS、WMTS、3D Tiles、地形、影像……

  4. 最后发现 60% 的代码都在重复造轮子，而且每个项目都要再造一遍。

那么有没有一个成熟的开源目录树框架，可以直接开箱即用呢？

TerriaJS 解决的正是这个问题。

TerriaJS 是一个开源的地理信息系统（GIS）平台，提供了丰富的 API 和组件，主要用于创建基于 Web的交互式地图和可视化地理数据应用程序。它是在 Cesium 之上构建的一套地理数据目录 + 地图应用框架：

支持地图渲染、场景管理、数据可视化等功能，集成了 Cesium（用于 3D WebGL 渲染）和 Leaflet（用于 2D 地图），可以处理广泛的地理空间数据格式，如 GeoJSON、KML 和 WMS等。

  • 底层渲染：Cesium（3D）/ Leaflet（2D）；

  • 上层能力：数据目录（Catalog）、Workbench 图层管理、时间轴、图例、分享、搜索、量测、绘图等；

  • 扩展方式：JSON 配置 + React 插件 + 自定义 CatalogItem 模型；

  • 应用形态：TerriaMap 是官方提供的应用壳，terriajs是核心库。

一句话概括：

Cesium 负责"把地球画出来"，TerriaJS 负责"把数据管起来、把交互做完整"。

本专栏按照我自己使用TerriaMap的项目经历出发，把我在实际项目过程中遇到的二次开发的问题和踩过的坑给大家进行总结，按真实项目的落地方案，把TerriaMap的配置体系、数据接入、插件开发、模型定制和部署上线串成一条完整的工程链路。给大家分享学习。

仓库地址：https://github.com/TerriaJS/terriajs

二、Terria系列：体系里的五个角色

打开官网你会发现 “Terria”“TerriaJS”“TerriaMap”“terriajs-server” 混着出现，很容易懵。官方在 TerriaJS README 的 Components and naming 里给过定义，我把它翻译成一张表：

开始使用 TerriaJS 的最简单方法是使用TerriaMap。TerriaMap是基于TerriaJS的具体实现，它利用TerriaJS的功能和API，提供用户友好的地图界面。

TerriaMap 提供了一个完整的用户界面和功能集，可以作为一个独立的应用程序使用，也可以作为定制 TerriaJS 应用程序的起点简单来说：TerriaJS 是构建 TerriaMap 的基础框架，而 TerriaMap 是基于 TerriaJS 构建的一个具体的应用程序。

而TerriaJS Server是一个用于托管TerriaJS应用的后端服务。它可以提供数据访问、处理和安全控制等功能，以支持TerriaJS应用的运行。

三、TerriaMap介绍

官方 Getting Started 第一句：

“The easiest way to get started with TerriaJS is to useTerriaMap. TerriaMap is a full-featured application built on TerriaJS, ready to be customized with your own branding and catalog.”

翻译过来：TerriaMap它不是地图引擎，也不是低代码平台，而是一个"数据目录驱动的 GIS 站点"成品骨架——你换掉品牌、换掉目录、换掉底图，它就是一个新的行业平台。

TerriaMap天生自带的能力（官方 README 归纳）：

  • 不是 GIS 服务端：不做数据发布、不做切片、不做空间分析。WMS/瓦片/地形都要你另外准备（GeoServer、自建切片、ArcGIS Server、对象存储）。

  • 不是可视化大屏：它的 UI 是"资源管理器"风格，不是炫酷驾驶舱。要大屏得自己写面板。

  • 不是开箱即用的业务系统：登录、权限、前后端交互等二次开发功能都要自己加。

  • 不保证国内底图/坐标系开箱可用：天地图、内网瓦片都要手工配置。

  • 支持插件和个性化设置：自定义数据结构、自定义符号化，需要开发者按照需求自定义扩展、开发插件等。

四、TerriaMap Start教程

安装教程：

  1. 下载源码：
git clone [https://github.com/TerriaJS/TerriaMap.git](https://github.com/TerriaJS/TerriaMap.git)

clone 下来之后，第一眼该看的 5 个文件：

  1. 安装构建：
cd TerriaMap export NODE_OPTIONS=--max_old_space_size=4096 # Windows PowerShell 设置；Linux/macOS 用 export npm install -g yarn yarn install yarn gulp yarn start

注意：官方文档写的是yarn install && yarn gulp && yarn start，但第一次构建内存不够是最高频的失败点，务必先设NODE_OPTIONS。

打开http://localhost:3001，主页面如下：

通过自带的目录数结构，可以管理不同格式的数据，实现数据的浏览、加载、符号化显示：


还有自带的数据对比功能：可以直观对比不同时序下特征要素的差异：

五、TerriaMap 目录结构

项目成功构建后，目录结构如下：

TerriaMap/ ├─ entry.js # webpack 入口 ├─ index.js # 应用主入口：new Terria → ViewState → start → render ├─ plugins.ts # 插件清单，loadPlugins 按这里加载 ├─ gulpfile.js # 构建任务定义（lint / copy-assets / render-index / write-version / webpack） ├─ package.json # 依赖与 npm scripts（start / gulp / hot / docker-build-*） ├─ tsconfig.json # TypeScript 配置 ├─ serverconfig.json # terriajs-server 配置：端口、代理白名单、CORS ├─ Dockerfile # 仓库自带的多阶段镜像（build: node:16 → deploy: node:16-slim） ├─ version.js # gulp write-version 生成，供模板注入 ├─ terria-logo.png # 默认 Logo ├─ yarn.lock / .yarnrc # 依赖锁定与 yarn 配置 ├─ .eslintrc / .prettierrc / .editorconfig / .husky # 代码规范与 git hooks ├─ .devcontainer/ # VS Code 容器化开发环境 │ ├─ lib/ # 【应用层代码】TerriaMap 自己的 React 代码 │ ├─ Core/loadPlugins.ts # 插件加载逻辑（读 plugins.ts，逐个注册） │ ├─ ViewModels/PreviewLinkViewModel.js │ ├─ Views/ # 应用级视图：UserInterface、render、About 按钮、免责声明 │ │ ├─ UserInterface.jsx # 页面骨架（菜单、侧栏、地图容器） │ │ ├─ render.jsx # ReactDOM 挂载 │ │ ├─ AboutButton.jsx │ │ └─ global.scss │ └─ Styles/ # 全局样式变量与加载动画 │ ├─ wwwroot/ # 【静态资源 + 运行时配置 + 构建产物】 │ ├─ index.ejs # HTML 模板（gulp render-index 编译成 index.html） │ ├─ index.html # 生成物，不要手改 │ ├─ config.json # 主配置：品牌名、初始视角、底图、地形、工作台… │ ├─ version.json # 生成物：版本 / commit，线上排查用 │ ├─ init/ # 目录初始化文件（Catalog 树、图层清单） │ │ └─ simple.json │ ├─ build/ # webpack 产物：TerriaMap.js、TerriaJS/（gulp copy 而来） │ ├─ data/ # 演示数据、图标、样式 JSON │ ├─ images/ favicons/ # 图片与站点图标 │ ├─ languages/ # 多语言文案包 │ ├─ help/ # 帮助文档页面 │ ├─ public/ # 额外静态站点内容 │ ├─ test/ # 前端测试页 │ └─ 404.html / 500.html / about.html / privacy.html │ ├─ packages/ # 【插件工作区】每个 plugin-* 都是独立包，只有 src/ │ ├─ plugin-sample/ # 官方示例模板（写新插件从这 copy） │ └─ store/ # 插件间共享状态 │ ├─ buildprocess/ # 【构建配置】 │ ├─ webpack.config.js # 主构建配置（含 terriajs 路径解析、插件别名） │ ├─ webpack.config.hot.js # 热更新开发配置 │ └─ configureWebpackForPlugins.js │ ├─ patches/ # patch-package 补丁（如 protomaps+1.19.0.patch） ├─ deploy/ # 部署资产 │ ├─ docker/ # create-docker-context.js + 官方 10 行 Dockerfile │ ├─ helm/ # Helm chart │ ├─ kubernetes/ # RBAC 配置 │ └─ varnish/ # 缓存层配置 ├─ doc/deploying/ # 部署文档 └─ architecture/ # 架构决策记录（ADR）

1.wwwroot/：配置项

  • 应该改：config.json、init/*.json、index.ejs、images/、languages/、help/；

  • 不该改：index.html、version.json、build/——这三个都是 gulp 生成的，改了下次构建就没了。

2.lib/：TerriaMap 自己的代码
只有 8 个文件左右，是“应用壳”级别的 UI：页面骨架、About 按钮、免责声明、预览链接、全局样式。它和node_modules/terriajs/lib是两个完全不同的东西：

3.packages/：插件工作区
每个插件只有src/，通过plugins.ts注册。写新插件最省事的做法是复制plugin-sample再改名。store/是插件之间共享的状态模块。

4.buildprocess/：构建配置
webpack.config.js里最关键的一句是通过require.resolve("terriajs/package.json")找到node_modules/terriajs并把它加进resolve.alias

5.deploy/、doc/、architecture/、patches/

  • deploy/docker/：官方 Docker 方案（create-docker-context.js重新生成一个精简的构建上下文）；

  • deploy/helm、kubernetes、varnish：集群部署与缓存；

  • patches/：patch-package补丁，yarn install的 postinstall 会自动打上；

  • architecture/：ADR，记录“为什么这么选”。

六、总结

本篇文章介绍了什么是TerriaMap以及如何快速clone一个可执行的项目。

下一篇技术文章将介绍：如何基于官方提供的Demo，在不修改核心底层源码的前提下，仅通过调整配置项的方式，完成自定义数据集的接入、适配与项目改造，构建符合自身业务需求的专属项目。