最近在调一个老项目前端要整体迁到 Vue CLI 3但核心的三维地球模块还被锁死在 Cesium 1.7。刚拿到这个组合时我第一反应就是import Cesium from cesium结果项目一跑起来各种怪问题一个接一个。折腾了两天之后我老老实实把 Cesium 1.7 当成“目录级静态资源”来处理环境总算稳定了。这篇把完整的配置思路、踩坑点和排查顺序记录下来给正在维护老版本三维 GIS 项目的朋友做个参考。如果你也是类似处境项目里已经有一套基于 Cesium 1.7 写好的 API、数据服务和 shader 改动不能随便升级引擎但又想把前端工程化切到 Vue CLI 3那么这篇文章很适合你。我会尽量把“为什么这么做”讲清楚而不是只给一段能跑的配置。1. 为什么是这套组合而不是直接升级到新版 Cesium1.1 业务约束比技术选择更现实这个三维模块不是新写的而是从很早以前就在生产环境稳定运行的一套系统。底层的地形切片、影像服务、Entity 数据接口、还有二次封装的那一层工具函数全部是围着 Cesium 1.7 写的。换新版本意味着所有涉及 WebGL 渲染、Entity 属性解析、相机控制、图层管理的代码都要重新过一遍回归清单。Cesium 新版本这些年变化不小尤其是内部模块化方案和部分 API 行为升级之后很可能出现“页面不报错但效果不对”的隐性 bug。对一套长期运行的项目来说这种成本不是随便就能接受的。所以前端脚手架升级到 Vue CLI 3只是为了把工程化构建、本地调试、部署流程统一起来并不是要顺手换地图引擎。1.2 Cesium 1.7 和 Vue CLI 3 之间存在明显的“代差”Cesium 1.7 大概是 2016 年左右发布的版本。那个时期的前端生态里主流做法还是直接用script标签引入一个全局 JS 文件再配合 AMD 加载器处理内部依赖。Vue CLI 3 是 2018 年之后才普及的脚手架底层是 webpack 4。Cesium 1.7 在设计之初并没有把“被现代打包器 import”作为主要使用场景。这不是说 webpack 4 完全不能加载 AMD 模块而是说这个老版本带了它自己的一套模块加载运行时。一旦项目里出现多入口、懒加载、代码分割就很容易碰到define is not defined、Cesium is not defined这类模棱两可的报错。折腾到最后你会发现最简单、最稳定的路线反而最朴素把它当成传统 JS 库用 script 标签全局引入然后用window.Cesium访问。2. 环境准备老版本项目不能盲目上新工具2.1 版本核对清单老项目配新脚手架第一步不是急着写代码而是先把本机的 Node、npm、Vue CLI 版本对齐。Vue CLI 3 对 Node 的要求是 8.9 以上但真正运行到 webpack 4 时Node 版本太高反而会有兼容问题。我这里用的组合比较保守软件推荐版本说明Node.js10.24.x对 Vue CLI 3 和 webpack 4 最友好避免高版本 Node 带来的算法兼容问题npm6.14.xNode 10 自带版本处理旧 lockfile 不容易出幺蛾子Vue CLI 33.12.x3.x 的最后一个稳定线底层基于 webpack 4Cesium1.7.0固定版本避免 npm 安装时被自动升级Node 14 以上跑 webpack 4 时经常会出现error:0308010C:digital envelope routines::unsupported这类问题本质是 OpenSSL 算法变了。用 Node 10 能绕开大部分坑如果团队规定必须用高版本 Node那就得额外配 NODE_OPTIONS 处理多一事不如少一事。2.2 创建项目并安装固定版本安装命令本身很简单vue create vue-cesium-demo cd vue-cesium-demo npm install cesium1.7.0 --save这里有几个容易忽略的细节。第一cesium1.7.0必须写死版本号不能直接npm install cesium否则拉下来的是几十个版本之后的新包整个目录结构和加载方式都不一样了。第二如果你们公司用的是私有 npm 镜像而这个镜像早就把老版本清理掉了那npm install可能直接失败。这时候不要纠结直接从旧项目里拷贝一份Build/Cesium目录过来后面所有步骤依然成立因为本质上我们就是要这个目录。安装完成后可以到node_modules/cesium/下看一眼目录结构。重点确认是否存在Build/Cesium这个子目录。如果只有Source或别的结构说明这个 npm 包不是标准的 Cesium 1.7 发布包。3. 把 Cesium 1.7 当作“目录级静态资源”来搬3.1 不要只拷一个 Cesium.jsCesium 这个库很有特点它不是单个 JS 文件就能跑起来的。构建发布之后真正的运行时是一个完整的目录里面除了主入口Cesium.js还跟着一堆 Worker 脚本、默认图标、控件样式、第三方基础库。以 1.7 为例Build/Cesium目录至少会包含这些内容目录/文件作用Cesium.js主入口暴露全局window.CesiumCesium.css控件和默认样式Assets/默认纹理、图标、图片等资源Widgets/时间轴、动画控制、图层选择等控件的 HTML/CSSWorkers/Web Worker 脚本地形计算、几何处理会动态加载ThirdParty/内部依赖的第三方库按 AMD 方式加载很多人第一次配置时只把Cesium.js复制到了静态目录结果运行时发现地图控件出来了但地球是黑的或者控制台报一堆Assets/xxx 404、Workers/xxx 404。原因就是其他目录没跟着搬。记住一个原则整个 Build/Cesium 目录必须原样保留目录层级也不要随意改写。Cesium 内部计算资源路径时默认是假设 Cesium.js 和旁边的 Assets、Workers、Widgets 在同级目录下的。3.2 手动拷贝与自动拷贝怎么选两种方式都可以用。第一种手动拷贝到 Vue CLI 3 的public/cesium/目录。这种方式很直观适合演示或快速验证public/ cesium/ Cesium.js Cesium.css Assets/ Widgets/ Workers/ ThirdParty/第二种用copy-webpack-plugin在构建时自动从node_modules/cesium/Build/Cesium拷到输出目录。这种方式能保证目录完整不容易漏文件也方便以后通过 package.json 精确锁版本。搬运方式优势缺点手动拷贝到 public/cesium思路简单不依赖额外插件版本升级时容易忘且容易只拷一部分文件CopyWebpackPlugin 自动拷贝目录完整版本可控适合真实项目配置有学习成本插件版本不同写法有差异我在正式项目里用的是自动拷贝。但对于只想先跑通 Demo 的人来说手动拷贝public/cesium一步到位后续配置也更少。4. vue.config.js 和 index.html 要联动配置不能只配一个4.1 publicPath 决定浏览器以什么路径找资源Vue CLI 3 里publicPath会影响 index.html 中静态资源的引用前缀。默认值是/也就是根路径。如果项目部署在服务器根目录下这没问题。但如果部署在子目录下或者用相对路径方式打开那就要把 publicPath 改成./。一个更稳妥的写法是区分开发环境和生产环境// vue.config.js module.exports { publicPath: process.env.NODE_ENV production ? ./ : / }开发环境用/避免 Vue Router history 模式在子路由刷新时 404生产环境用./让 index.html 里的资源引用变成相对路径不管丢到哪个子目录都能找到。4.2 index.html 里用原生 script 标签引入在 Vue CLI 3 中public/index.html会经过 EJS 模板编译% BASE_URL %会被替换成publicPath的值。加入 Cesium 对应的样式和脚本!DOCTYPE html html langzh-CN head meta charsetutf-8 meta http-equivX-UA-Compatible contentIEedge title三维地图管理平台/title link relstylesheet href% BASE_URL %cesium/Cesium.css script src% BASE_URL %cesium/Cesium.js/script /head body noscript请先开启 JavaScript 再访问本系统。/noscript div idapp/div /body /html这里我把script标签放在了head里而不是 body 底部。这样做的好处是Vue 应用挂载之前window.Cesium一定已经存在组件里不需要考虑加载时序。Cesium.css也必须在业务代码之前加载否则时间轴、图层选择器这些控件会出现“有功能但样式全乱”的效果。如果采用手动拷贝方案配置文件可以非常干净vue.config.js只需要处理 publicPath 即可。如果采用自动拷贝方案则需要在configureWebpack.plugins里加 CopyWebpackPlugin。4.3 CopyWebpackPlugin 的完整配置先安装合适版本的插件。Vue CLI 3 自带的 webpack 是 4copy-webpack-plugin 用 5.x 最稳npm install copy-webpack-plugin5.1.2 --save-dev然后配置// vue.config.js const path require(path) const CopyWebpackPlugin require(copy-webpack-plugin) module.exports { publicPath: process.env.NODE_ENV production ? ./ : /, configureWebpack: { plugins: [ new CopyWebpackPlugin([ { from: path.join(__dirname, node_modules/cesium/Build/Cesium), to: cesium, toType: dir } ]) ] } }注意这里 from 的路径是node_modules/cesium/Build/Cesiumto 是cesium。构建之后的效果是 dist 目录下生成cesium/里面是完整目录。如果你在某个项目里看到的是这种写法new CopyWebpackPlugin({ patterns: [ { from: ..., to: ... } ] })那是 copy-webpack-plugin 6.x 以后的语法。Vue CLI 3 默认情况下不一定兼容使用前先确认插件版本。vue.config.js修改之后必须重启 dev server配置才会生效。5. 在 Vue 单文件组件里创建并销毁 Viewer5.1 基础封装代码引入 Cesium 之后最常见的使用方式是在一个独立组件里渲染三维地球。组件模板很简单就是放一个容器 divtemplate div refcesiumContainer classcesium-container/div /template script export default { name: CesiumViewer, viewer: null, mounted () { // 全局 Cesium 来自 index.html 中的 script 标签 this.viewer new window.Cesium.Viewer(this.$refs.cesiumContainer, { animation: false, // 左下角动画控件 timeline: false, // 底部时间轴 baseLayerPicker: false, // 图层选择器 geocoder: false, // 搜索框 homeButton: false, // 回到默认视角 sceneModePicker: false, // 2D/3D 切换 navigationHelpButton: false, // 帮助按钮 infoBox: false, // 信息弹窗 selectionIndicator: false // 选中标记 }) // 设置一个初始视角 this.viewer.camera.setView({ destination: window.Cesium.Cartesian3.fromDegrees(120.15, 30.28, 10000.0) }) }, beforeDestroy () { if (this.viewer) { this.viewer.destroy() this.viewer null } } } /script style scoped .cesium-container { width: 100%; height: 100%; min-height: 400px; } /style这里有几个点值得展开讲。第一1.7 版本的控件参数就是上面这些。新版本 Cesium 文档里的一些选项比如baseLayer: false、baseMap在 1.7 里不一定生效配置时以 1.7 的 API 文档为准。第二this.viewer null这种写法在 Vue 2 里不是响应式数据这是刻意为之。Viewer 实例内部有大量 WebGL 对象和方法放进 Vue 的响应式系统里既没必要也可能带来性能损耗。直接把它挂在实例上当成普通属性管理即可。第三容器的高度很关键。Cesium 的 canvas 默认继承父容器尺寸如果父容器没有高度画布会变成 0 高。所以.cesium-container要显式设置height: 100%或者固定高度。注意如果放在 Vue Router 的嵌套路由里通常还要让路由视图、父容器也都有高度这个链条缺一个都不行。5.2 SPA 路由切换和 keep-alive 的处理单页应用里最容易被忽略的是 Viewer 的销毁。beforeDestroy里调用了viewer.destroy()但如果你的路由组件被keep-alive包裹组件不会真正卸载beforeDestroy不会按时触发。结果就是一个页面来回切了几次之后WebGL 上下文越来越多内存一路往上走最终页面越来越卡甚至白屏。我的做法是根据是否使用 keep-alive决定在哪个生命周期里创建和销毁 Viewer。如果页面需要缓存就改用activated和deactivatedscript export default { name: CesiumViewer, activated () { if (!this.viewer) { this.createViewer() } }, deactivated () { if (this.viewer) { this.viewer.destroy() this.viewer null } } } /script创建逻辑可以抽成一个方法在 mounted 和 activated 里都调用。这样既能保证首次进入创建也能在离开缓存页面后释放 WebGL 资源再次进入时重新创建。另外Cesium 的 canvas 默认需要很多浏览器资源开发调试时如果启动了很久的 dev server偶尔出现“切了几次页面就黑屏”优先怀疑不是配置问题而是 WebGL 上下文达到浏览器上限刷新页面即可恢复。6. 高频报错与我的完整排查链路6.1 报错Cesium is not defined这是最常见、也最容易误导人的一个报错。看到这个错误很多人第一反应是 npm 包没装好实际上更像是脚本没加载成功或者加载顺序不对。我的排查顺序是固定的打开浏览器 DevTools 的 Network 面板刷新页面直接搜Cesium.js看请求状态是不是 200。如果状态是 404说明路径不对。检查 index.html 里的引用路径和实际静态文件位置是否一致。比如把 Cesium 放到了public/cesium/但引用写成了% BASE_URL %Cesium.js就一定会 404。如果状态是 200但控制台还是报Cesium is not defined检查页面实际执行的打包代码是否引用了window.Cesium之外的名字。Cesium 1.7 挂载到全局时正常应该可以直接用window.Cesium。确认浏览器加载的是不是被插件拦截或缓存过的旧文件。老版本项目的调试现场经常会出现“代码改了资源没刷新”的情况DevTools 里勾选 Disable cache 再试一次。我实际遇到的一次问题是 copy 插件配置错了to写成了cesium/cesium。构建产物里出现了两层同名目录浏览器请求cesium/Cesium.js时当然找不到。排查时直接在 dist 目录里看一眼文件路径比反复猜配置高效得多。6.2 报错控件有地球黑或者 Assets/Widgets 404如果页面能正常显示 Cesium 的旋转图标、时间轴这些控件但地图区域一片黑或者控制台刷出一堆Assets/xxx 404、Widgets/xxx 404问题大概率不是主 JS 文件而是 Cesium 的静态资源基础路径不对。Cesium 运行时需要动态加载 Workers 和 Assets。它判断资源路径的方式依赖 Cesium.js 所在的 URL 位置。所以配置时一定要注意不要把 Cesium.js 单独复制到别的地方也不要让浏览器通过一个重定向后的 URL 加载它。最理想的情况是浏览器地址栏里Cesium.js的完整路径就是某个目录/Cesium.js且这个目录下同级存在 Assets、Workers、Widgets。我的排查步骤通常是看 Elements 面板里script标签实际加载的 URL。在浏览器直接访问这个 URL 的上级目录确认 Assets 是否能列出来。如果项目部署在子目录检查生产环境的 publicPath 是否设成了./不能一边用绝对路径部署一边期望相对路径资源能自动对上。有些资料会提到设置window.CESIUM_BASE_URL。老版本对资源路径的推断相对脆弱如果你确实需要强制指定可以在 index.html 的 Cesium.js 之前加一行window.CESIUM_BASE_URL cesium/但前提是你要能确认这个全局变量在 1.7 版本里会生效。我的建议是优先保持目录结构干净让 Cesium 自己推断。6.3 报错切换路由几次后页面白屏控制台提示 WebGL context lost这类问题通常不是第一次进页面时报的而是“用着用着就崩了”所以很多人不会往开发环境配置方向想。在 Vue 单页应用里如果路由切走时没有销毁 ViewerCesium 创建的 WebGL 上下文和 canvas 会继续挂在 DOM 上。再次进入路由时又会 new 一个 Viewer等于一个页面里同时存着多个 WebGL 上下文。浏览器对 WebGL 上下文数量有严格限制超了之后要么报Context Lost要么整个页面白屏。我的排查链路很简单页面切走之后先看 DOM 里是不是还残留着之前创建的 canvas。在beforeDestroy里打一个日志确认组件是否真的卸载。如果组件被 keep-alive 缓存立刻改用activated/deactivated方案。这个问题处理完之后内存曲线会明显平稳下来连续切换十几遍页面都不会再白屏。还有一个细节Cesium 1.7 的 Viewer 销毁之后某些已注册的定时器和事件监听不一定能立即回收干净。如果项目里对内存要求很严格可以在viewer.destroy()之后再手动把容器里的 DOM 清空const container this.$refs.cesiumContainer if (container) { container.innerHTML }这一步不做也不至于马上出问题但在长时间运行的监控大屏项目里能少一点是一点。这套环境配下来真正复杂的地方不在于写了多少配置而在于搞清楚 Cesium 1.7 的历史加载方式。它天生是一个“目录级”依赖不是单纯的 npm 模块。只要心里有这个概念遇到 404、is not defined、WebGL context lost 这些问题时都能沿着“资源路径对不对、全局对象有没有、生命周期有没有泄露”这条线快速定位。老版本项目维护就是这样没有太多惊喜但每一步都值得记录。