React 项目集成 Cesium 完整教程

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

在 React 项目里集成 Cesium，最稳妥的做法是安装 cesium 与 Resium，用 Vite 搭配 vite-plugin-cesium 自动复制静态资源并设置 CESIUM_BASE_URL，再用声明式 <Viewer> 挂载三维地球；也可以不用 Resium，直接在 useEffect 里 new Viewer 并在卸载时 destroy。截至 2026 年 11 月，CesiumJS 最新为 1.147.0，Resium 为 1.27.0（peer 要求 React ≥18.2、Node ≥20.19）。核心步骤就三件事：装包、配资产与 Token、正确管理 Viewer 生命周期，按下面做完就能在浏览器看到可交互地球。

集成方式怎么选：Resium 还是纯 React？

先明确要解决的问题：Cesium 是命令式 WebGL 库，而 React 是声明式 UI。直接混用容易出现重复创建 Viewer、内存泄漏或热更新失效。Resium 把 Viewer、Entity 等封装成 React 组件，通过 Context 传递实例，并处理好属性更新与销毁，适合大多数业务组件开发。纯 React 写法更灵活，适合需要深度定制或极致控制渲染时机的场景，但必须自己管生命周期。

如果后续还要和 Three.js 场景融合，纯 React 方式通常更好控；可参考本站Three.js 与 Cesium 融合实现教程。新手优先选 Resium + Vite。

环境准备与依赖安装

目标环境：Node ≥20.19（Resium 近期要求）、Vite 项目（Create React App 已不推荐，兼容问题多）。浏览器需支持 WebGL。

1. 创建或进入已有 Vite React 项目：npm create vite@latest my-cesium-app — –template react-ts，进入目录。
2. 安装核心依赖：npm install cesium resium。TypeScript 用户无需额外 @types/cesium。
3. 安装 Vite 插件（强烈推荐）：npm install vite-plugin-cesium -D。它会自动复制 Workers、Assets、Widgets 等静态资源并注入 CESIUM_BASE_URL。
4. 到 Cesium 官方下载页 注册免费 Cesium ion 账号，创建 Access Token（建议限制 assets:read 与 geocode 范围）。

验收标准：package.json 里能看到 cesium、resium、vite-plugin-cesium；Token 已复制备用。官方 Quickstart 也强调必须在创建 Viewer 前设置 Token 与 BASE_URL，详见 CesiumJS 官方快速入门。

Vite + Resium 完整集成步骤（推荐）

这是目前最省心的路径，官方也提供了 Vite 示例仓库可对照。

1. 修改 vite.config.ts（或 .js），加入插件：
   import { defineConfig } from ‘vite’;
   import react from ‘@vitejs/plugin-react’;
   import cesium from ‘vite-plugin-cesium’;
   export default defineConfig({
   plugins: [react(), cesium()],
   });
   插件会处理资产复制，一般无需再手写 copy。
2. 在入口或组件顶部导入样式与 Token：
   import “cesium/Build/Cesium/Widgets/widgets.css”;
   import { Ion } from “cesium”;
   Ion.defaultAccessToken = “你的_token”;
   必须在任何 Viewer 创建之前执行。
3. 写一个最简组件（例如 CesiumMap.tsx）：
   import { Viewer } from “resium”;
   export default function CesiumMap() {
   return <Viewer full />;
   }
   full 会让容器占满父元素，父级记得设高度（如 100vh）。
4. 在 App 中挂载该组件，启动 npm run dev。打开浏览器应看到默认三维地球与控件。
5. 需要 Entity、ImageryLayer 时直接作为 <Viewer> 子组件书写即可，Resium 通过 Context 自动关联。注意：只读属性（如 imageryProvider）变更会导致组件销毁重建，尽量用可变属性或浅层挂载。

构建时资产体积较大，可在 vite 配置里把 assetsInlineLimit 设为 0，避免小文件被内联导致路径错乱。若坚持手动复制，可参考官方 cesium-vite-example 用 vite-plugin-static-copy，并显式设置 window.CESIUM_BASE_URL = “/cesium/”（建议带尾斜杠）。

纯 React 写法与生命周期管理

不想引入 Resium 时，用容器 ref + useEffect 即可，重点是“创建一次、销毁一次”。

1. 准备一个带高度的 div，并用 useRef 拿到 DOM。
2. 在 useEffect 中：先确认 CESIUM_BASE_URL 与 Token 已设；然后 const viewer = new Viewer(containerRef.current, { …options });；返回清理函数 () => { viewer.destroy(); }。
3. 依赖数组保持空或仅放必要不变值，避免反复销毁重建。StrictMode 下开发模式会双调，注意观察是否泄漏。
4. 需要响应 props 变化时，用 viewer.entities 或 dataSources 增量更新，而不是重建整个 Viewer。

• 必须在导入 cesium 之前或同步设置 window.CESIUM_BASE_URL。
• 组件卸载一定调用 destroy，否则 WebWorker 与 WebGL 上下文会残留。
• 与其他三维库共存时，注意 canvas 与事件冲突，可参考本站 Three.js 融合文章。

验收：刷新页面只创建一次 Viewer；切换路由离开再回来无报错、无多余 canvas；控制台无 “Unable to determine Cesium base URL” 或 404 静态资源。

静态资源、Token 与性能注意点

Cesium 运行依赖 Workers、ThirdParty、Assets、Widgets 四类静态文件。未复制或路径错误时，最常见报错就是 base URL 无法确定或 worker 加载失败。Vite 插件已帮你处理；Webpack 则需 copy-webpack-plugin + DefinePlugin 定义 CESIUM_BASE_URL。Next.js 必须用动态导入并关闭 SSR，并把资产拷到 public/cesium，再设 window.CESIUM_BASE_URL = “/cesium”。

Token 建议每个应用独立创建并限制 URL/Scopes。默认地球能出来后，再叠加自己的倾斜摄影、3D Tiles 或大模型。若出现卡顿，优先检查瓦片级数、内存与 requestRenderMode，具体优化手段见本站Cesium 加载大模型卡顿与性能优化技巧；倾斜摄影贴地与高度偏移可看Cesium 倾斜摄影加载与贴地教程。

常见问题

为什么必须设置 CESIUM_BASE_URL？不设会怎样？

Cesium 运行时要动态加载 Worker 脚本和资源文件，它通过这个全局变量定位根路径。未设置或设错时，控制台会出现 “Unable to determine Cesium base URL” 或大量 404，地球无法初始化。用 vite-plugin-cesium 会自动注入；手动时务必在导入 cesium 前赋值并带尾斜杠。

Resium 能直接用在 Next.js App Router 吗？

不能直接 SSR。必须把 Viewer 包在客户端组件里，并用 next/dynamic 设置 ssr: false，同时把 Cesium 静态资源复制到 public 目录并设置 BASE_URL。否则服务端没有 DOM/WebGL 会直接报错。

升级 Cesium 到 1.147 后 Resium 1.27 还能用吗？

Resium 1.27.0 官方声明支持到 Cesium 1.146，但 Cesium 1.x 一般向后兼容。升级后先跑通基础 Viewer，再验证 Entity、Primitive 等组件。若遇破坏性变更，可暂时锁定 cesium@1.146 或以官网与 Resium changelog 为准。

集成后地球出来了，但加载倾斜摄影或大模型很卡怎么办？

这是性能问题而非集成失败。先开 requestRenderMode、降低最大屏幕空间误差、合理设置 maximumScreenSpaceError，并检查网络与瓦片缓存。详细排查与优化清单见本站性能优化文章。

总结：优先用 Vite + vite-plugin-cesium + Resium，三步走——装包、配 Token 与插件、挂 <Viewer>——就能稳定跑通；纯 React 则务必在 useEffect 清理里 destroy。建议先按本文最小示例验收地球正常显示，再叠加业务图层；遇到卡顿或融合需求时，直接查阅本站已有的性能优化与 Three.js 融合教程，按步骤验证即可。