Vue 项目集成 Cesium 完整教程

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

在 Vue 项目中集成 Cesium，推荐使用 Vue 3 + Vite，通过 npm install cesium 安装，再用 vite-plugin-cesium 或手动复制 Workers/Assets 等静态资源并设置 CESIUM_BASE_URL，最后在组件的 onMounted 里创建 Viewer、onBeforeUnmount 里销毁即可。截至 2026 年 11 月，CesiumJS 最新版本为 1.147.0（npm 包 cesium@1.147.0），支持按需导入与 tree-shaking，许可证为 Apache 2.0。正确配置后几分钟就能在浏览器跑起可交互的 3D 地球，后续加载 3D Tiles 或做性能优化可直接衔接本站其他章节。

环境准备与依赖安装

目标环境是支持 WebGL 的现代浏览器（最新 Chrome、Edge、Firefox 115+ 或 ESR、Safari），Node.js 建议 18 及以上。Cesium 本身无严格最低硬件门槛，但复杂场景建议集成显卡。项目优先选 Vite 创建的 Vue 3 工程（Composition API），Webpack/Vue CLI 也能跑，只是配置稍繁琐。

1. 进入项目根目录，执行 npm install cesium（或 pnpm/yarn 等价命令）。需要更轻量时可考虑拆分包 @cesium/engine + @cesium/widgets，但从 1.146 起官方还提供了 @cesium/core。
2. 开发依赖可选安装 vite-plugin-cesium（简化静态资源处理），命令为 npm i vite-plugin-cesium -D。
3. 准备一个 Cesium Ion Access Token：到官网注册后创建应用专属 token（最小权限原则），后续用环境变量 VITE_CESIUM_ION_TOKEN 管理，避免写死在代码里。
4. 确认容器 DOM 有明确宽高（例如 100% 高度），否则 Viewer 会黑屏或尺寸异常。

官方预构建包也可从 Cesium 官方下载页 获取，但 Vue 项目更推荐 npm 模块方式，方便打包与 tree-shaking。

Vite 配置：静态资源与 CESIUM_BASE_URL

Cesium 运行时必须能访问 Workers、ThirdParty、Assets、Widgets 四类静态文件，否则会报 base URL 或 404。从 CesiumJS 1.114 起配置已大幅简化，但仍需显式处理。两种主流做法对比如下：

插件用法最简单：在 vite.config.js 的 plugins 数组里加入 cesium()，开发与生产都会自动把 node_modules/cesium/Build/Cesium 下的必要目录拷到输出。手动方式则使用 vite-plugin-static-copy，把 Workers、ThirdParty、Assets、Widgets 复制到例如 cesiumStatic 目录，同时在 define 里写 CESIUM_BASE_URL: JSON.stringify(‘/cesiumStatic’)。详细步骤与官方 Vite 示例可参考 Cesium 官方 Vite/Webpack 配置指南。

Webpack/Vue CLI 项目则用 copy-webpack-plugin 做同样复制，再用 DefinePlugin 注入 CESIUM_BASE_URL。无论哪种构建工具，生产构建时务必验证 dist 里静态文件路径与 CESIUM_BASE_URL 一致，否则线上必现 404。

在 Vue 组件里创建并销毁 Viewer

核心原则：Viewer 是重资源对象，必须在客户端挂载后创建、在卸载前销毁，避免内存泄漏。容器用 ref 绑定，并给父级或自身设置明确宽高。

1. 在组件 script 中导入：import { Viewer, Ion } from ‘cesium’，以及 CSS：import ‘cesium/Build/Cesium/Widgets/widgets.css’（放 main.js 或组件都行）。
2. 模板里放一个 <div ref=”cesiumContainer”></div>，样式写 height: 100vh 或固定像素。
3. onMounted 钩子里：先设置 Ion.defaultAccessToken（从 import.meta.env.VITE_CESIUM_ION_TOKEN 读取），再 new Viewer(cesiumContainer.value, {可选地形、影像等初始选项})。
4. onBeforeUnmount 里调用 viewer.destroy()，并把引用置空。若用 Composition API，可用 let viewer = null 保存实例。
5. 验收标准：页面出现带默认控件的 3D 地球，缩放旋转流畅，控制台无 Workers/Assets 404，无 “Unable to determine Cesium base URL” 报错。

基础地球跑通后，若要加载本地或在线 3D Tiles、做内存优化，可直接看本站 Cesium加载3DTiles：Vue3集成、本地3D Tiles和内存优化。大场景卡顿时再参考 Cesium加载大模型卡顿怎么办?性能优化技巧?。

Ion Token、可选封装与打包体积

未设置或 token 失效时，默认影像/地形可能加载失败（内置默认 token 配额有限）。推荐每个应用单独创建 token，只开 assets:read 等必要权限，详见官方说明。开发阶段把 token 放 .env，生产用 CI 注入。

• 可选封装库 vue-cesium（Vue 3 + Composition API + TS）能进一步简化 Viewer 创建与声明式图层，支持自定义 viewerCreator，兼容部分第三方扩展；若不需要组件化，直接用原生 Viewer 更轻。
• 打包体积：Cesium 本身较大（完整包约百兆级），可用 manualChunks 拆分、开启 tree-shaking，或只引入 @cesium/engine；同时适当提高 chunkSizeWarningLimit。
• 与 Three.js 混用时注意渲染循环与相机同步，具体实现见本站 Three.js与Cesium如何融合?具体怎么实现?。

开发与生产路径差异是常见坑：开发期可能直接指向 node_modules，生产必须复制到 dist。统一用插件或构建脚本处理即可。

常见问题

报错 “Unable to determine Cesium base URL automatically” 怎么办？

未正确设置全局 CESIUM_BASE_URL 或路径与复制目录不匹配。用 vite-plugin-cesium 时检查插件版本与 Vite 的 base 配置；手动方式则在 define 或 window.CESIUM_BASE_URL 里写成以 / 开头的相对路径（如 /cesiumStatic/），生产构建后打开 Network 面板确认 Workers 请求成功。

黑屏、影像或地形不加载？

多数是 Ion token 未设置、无效或配额不足，其次是容器没有宽高。先在 onMounted 开头打印并赋值 Ion.defaultAccessToken，再检查网络与 CORS；默认 token 仅供测试，正式项目务必换成自己的。

控件没有样式或 Workers/Assets 404？

漏导入 widgets.css，或静态文件没复制到构建输出。补上 CSS 导入，确认 vite 配置里的复制目标与 CESIUM_BASE_URL 完全一致；开发服务器重启后再试。

页面切换后内存持续上涨？

Viewer 没有在卸载时销毁。务必在 onBeforeUnmount（或 beforeUnmount）调用 viewer.destroy()，并清空所有实体、数据源引用。长时间运行的 GIS 页面尤其要注意。

总结：Vue 集成 Cesium 的关键是“静态资源可访问 + CESIUM_BASE_URL 正确 + 生命周期里创建/销毁 Viewer + 有效 Ion token”。优先用 Vite + vite-plugin-cesium 快速落地，锁定 cesium 版本避免升级惊喜；跑通基础地球后，立刻用本站 3D Tiles 与性能优化文章继续深化。建议把 token 和 base 路径都放进环境变量，方便多环境切换。