1. 从截个图而已说起为什么Cesium截图值得单独写一篇很多人第一次听到给三维地图截图这个需求第一反应都是调个浏览器截图 API 不就完了我当初也是这么想的直到真正在项目里动手才发现事情远没有这么简单。Cesium 渲染出来的三维场景底层用的是 WebGL 画布而 WebGL 有一个非常关键的默认行为——绘图缓冲区在每一帧渲染完成后会被清空。这意味着你如果在渲染循环之外去读取画布像素大概率拿到的是一张全黑或者全透明的图。这个坑我在早期项目里踩过不止一次。当时的需求很朴素用户在地图上摆好视角点一下按钮把当前画面存成图片方便贴到报告里或者分享给同事。听起来简单但真正落地时会牵扯出一连串问题怎么保证截到的是当前这一帧而不是上一帧地图上的标注、图层、地形是不是都能一起截进去截图分辨率能不能比屏幕更高做出高清大图的效果如果地图容器被其他 DOM 元素遮挡截图会不会把遮挡物也带进去这一篇是Cesium Vue 实现地图截图系列的第四篇前面几篇分别聊了基础截图、高清截图、以及带标注的合成截图。到了这一篇我想把重点放在屏幕截图与地图截图的区别、Vue 组件化封装、以及实际项目里那些让人抓狂的边界情况上。如果你正在用 Vue 做三维可视化项目需要给用户提供一个稳定可靠的截图功能那这篇内容应该能帮你少走不少弯路。我会尽量把每一步的为什么讲清楚而不是只丢一段代码让你抄。需要提前说明的是Cesium 的版本迭代比较快不同版本在渲染管线、API 命名上会有差异。我下面提到的方案基于较新的 Cesium 版本1.100 以上和 Vue 3 的组合式 API 来写如果你用的是 Vue 2 或者更老的 Cesium思路是一样的只是写法要相应调整。这一点在动手前一定要先确认清楚否则很容易出现代码看着没错但就是跑不通的情况。2. 屏幕截图和地图截图到底差在哪2.1 两种截图的本质区别在动手写代码之前有必要先把概念理清楚。很多人把屏幕截图和地图截图混为一谈实际上它们解决的是两个不同的问题。屏幕截图顾名思义截取的是用户当前屏幕上看到的内容包括地图画布、地图上的 UI 控件、你自己叠加的按钮和面板等等。它的特点是所见即所得用户看到什么就截什么。实现上通常依赖浏览器的canvas.toDataURL()或者html2canvas这类库。地图截图截取的则仅仅是 Cesium 渲染出来的三维场景本身不包含任何 DOM 层面的 UI。它的特点是纯净适合用来生成报告配图、导出成果图。实现上需要直接操作 Cesium 的渲染器通过scene.render()配合preserveDrawingBuffer或者离屏渲染来拿到像素数据。我见过不少项目在这两者之间反复横跳最后做出来的功能既不像屏幕截图也不像地图截图用户体验很割裂。所以在设计功能之前先问自己一句用户拿到这张图是要干什么如果是发朋友圈、贴聊天记录那屏幕截图更合适如果是做汇报材料、存档留证那地图截图更专业。2.2 为什么不能直接用浏览器截图 API有同学会问现在浏览器不是有navigator.mediaDevices.getDisplayMedia()吗直接调系统级的屏幕捕获不就行了这个方案确实存在但它有几个硬伤。第一它会弹出系统级的授权对话框用户必须手动选择要共享的屏幕或窗口这个交互在网页应用里非常突兀体验很差。第二它捕获的是整个屏幕或窗口你没法精确控制只截地图区域后期还得裁剪。第三不同浏览器、不同操作系统对这个 API 的支持程度参差不齐兼容性是个大问题。所以对于截取地图区域这种明确的需求最靠谱的做法还是回到 Canvas 层面直接读取 Cesium 渲染出来的像素。这也是本系列一直采用的技术路线。2.3 Cesium 渲染管线的关键约束要理解截图为什么难得先理解 Cesium 的渲染管线。Cesium 每一帧的渲染流程大致是这样的先清空绘图缓冲区然后依次渲染地形、影像、模型、标注等图层最后把结果呈现到屏幕上。关键在于默认情况下渲染完成后绘图缓冲区的内容就不再保留了这是 WebGL 为了性能做的优化。这就导致一个直接后果如果你在requestAnimationFrame回调之外去调canvas.toDataURL()浏览器会告诉你当前缓冲区没有有效数据返回的要么是空白要么是上一次的残留。解决办法有两个一是开启contextOptions.webgl.preserveDrawingBuffer让缓冲区内容保留下来二是在scene.postRender事件里趁着这一帧刚渲染完、缓冲区还有数据的时候立刻读取。这两种方案各有取舍后面我会详细对比。这里先记住一个结论截图时机的选择比截图代码本身更重要。3. Vue 组件化封装把截图逻辑收进一个可复用的盒子3.1 为什么要在 Vue 里做组件化封装在 Vue 项目里截图功能往往散落在各个业务组件里今天这个页面写一遍明天那个页面又抄一遍代码重复不说一旦 Cesium 升级或者发现 bug改起来就是灾难。我的做法是把它封装成一个独立的组合式函数Composition API 的useMapScreenshot或者一个无渲染组件让业务层只需要调用一个方法就能拿到图片。这样做的好处有三个一是逻辑集中所有截图相关的坑都在一个文件里处理二是便于测试可以单独针对这个函数写单元测试三是接口清晰业务层不需要关心 Cesium 内部怎么渲染只需要传参数、拿结果。3.2 组合式函数的基本骨架先看一个最简化的骨架把核心流程串起来// useMapScreenshot.js import { ref, onUnmounted } from vue export function useMapScreenshot(viewerRef) { const isCapturing ref(false) async function capture(options {}) { const viewer viewerRef.value if (!viewer || viewer.isDestroyed()) { throw new Error(Viewer 尚未初始化或已销毁) } isCapturing.value true try { const canvas await renderToCanvas(viewer, options) return canvas } finally { isCapturing.value false } } return { isCapturing, capture } }这个骨架里viewerRef是业务层传进来的 Cesium Viewer 引用capture是暴露给业务层的方法。注意我在开头做了isDestroyed()检查这个检查非常必要——Vue 组件销毁和 Cesium Viewer 销毁的时机不一定同步如果用户在组件卸载的瞬间点了截图很容易触发空指针异常。3.3 渲染到离屏 Canvas 的核心实现接下来是核心的renderToCanvas函数。它的思路是创建一个离屏 Canvas把 Cesium 当前场景渲染到这个 Canvas 上然后返回。这样做的好处是不依赖preserveDrawingBuffer也不需要担心缓冲区被清空的问题。async function renderToCanvas(viewer, options) { const { width, height, scale 1 } options const scene viewer.scene const canvas scene.canvas const targetWidth width || canvas.width * scale const targetHeight height || canvas.height * scale const offscreen document.createElement(canvas) offscreen.width targetWidth offscreen.height targetHeight // 保存当前渲染状态 const originalWidth canvas.width const originalHeight canvas.height const originalRatio scene.pixelRatio try { // 调整渲染尺寸 canvas.width targetWidth canvas.height targetHeight scene.pixelRatio 1 // 强制重新渲染一帧 scene.render() // 把渲染结果绘制到离屏 Canvas const ctx offscreen.getContext(2d) ctx.drawImage(canvas, 0, 0, targetWidth, targetHeight) return offscreen } finally { // 恢复原始状态 canvas.width originalWidth canvas.height originalHeight scene.pixelRatio originalRatio scene.render() } }这段代码里有几个细节值得展开说。第一我临时修改了canvas.width和canvas.height这是为了支持高清截图——把画布尺寸调大Cesium 就会以更高的分辨率渲染截出来的图自然更清晰。第二scene.pixelRatio设为 1 是为了避免设备像素比带来的二次缩放否则在高 DPI 屏幕上尺寸会翻倍。第三finally块里一定要恢复原始状态并重新渲染否则地图会停留在截图时的尺寸用户会看到画面跳一下。注意修改canvas.width会触发 WebGL 上下文重建这个过程在部分浏览器上会有明显的卡顿。如果截图频率很高建议改用scene.render()配合preserveDrawingBuffer的方案避免频繁重建上下文。3.4 在业务组件里怎么用封装好之后业务层的代码就非常清爽了template div classmap-wrapper div refmapContainer classmap-container/div button :disabledisCapturing clickhandleCapture {{ isCapturing ? 截图中... : 截图 }} /button /div /template script setup import { ref, onMounted } from vue import { useMapScreenshot } from ./useMapScreenshot const mapContainer ref(null) const viewerRef ref(null) const { isCapturing, capture } useMapScreenshot(viewerRef) onMounted(() { // 初始化 Cesium Viewer赋值给 viewerRef }) async function handleCapture() { const canvas await capture({ scale: 2 }) const dataUrl canvas.toDataURL(image/png) // 触发下载或上传 } /script这种写法把怎么截和截了干什么彻底解耦业务层只关心结果不关心过程。后面如果要换截图方案只改useMapScreenshot一个文件就行。4. 高清截图的参数计算与性能权衡4.1 分辨率到底该设多大高清截图是很多项目的刚需尤其是做汇报材料的时候屏幕分辨率的图放大就糊。但分辨率不是越大越好这里有个平衡点。假设你的地图容器在屏幕上是 1200×800 像素如果scale设为 2那截图就是 2400×1600设为 4 就是 4800×3200。看起来很美但你要考虑两个限制一是 WebGL 的纹理尺寸上限不同设备不一样常见的是 4096 或 8192超过这个值渲染会失败二是显存占用分辨率翻倍显存占用是四倍增长低端设备很容易崩。我的经验是桌面端 scale 设 2 比较稳妥移动端设 1.5 就够了。如果确实需要超大图可以分块渲染再拼接但这个复杂度就上去了一般项目用不上。4.2 一个容易忽略的坑标注和文字会变模糊高清截图有个反直觉的现象地图底图清晰了但上面的标注文字反而变糊了。原因是 Cesium 的标注Billboard、Label默认是按屏幕像素渲染的你把画布尺寸调大标注的尺寸没跟着变相对就显得小了放大后自然模糊。解决办法是在截图前临时调整标注的缩放比例。Cesium 的BillboardCollection和LabelCollection都支持scale属性你可以在截图前遍历所有标注把 scale 乘以截图倍率截完再改回来。这个操作有点繁琐但效果立竿见影。function adjustBillboardScale(scene, factor) { const collections scene.primitives._primitives.filter( p p instanceof Cesium.BillboardCollection ) collections.forEach(collection { for (let i 0; i collection.length; i) { const billboard collection.get(i) billboard.scale * factor } }) }4.3 性能实测数据参考我在一台中等配置的笔记本上做过测试地图容器 1200×800场景里有约 500 个标注和一片地形。结果如下截图倍率输出尺寸单次耗时显存峰值1x1200×800约 80ms正常2x2400×1600约 220ms略升4x4800×3200约 900ms明显升高8x9600×6400渲染失败超限可以看到4x 开始耗时就有明显上升8x 直接失败。所以如果你的场景比较复杂建议把倍率控制在 2x 以内并且给用户一个截图中的 loading 提示避免他们以为卡死了反复点击。5. 那些让人抓狂的边界情况5.1 截图全黑最常见也最容易被误判的问题截图全黑是新手遇到最多的现象但它的成因有好几种不能一概而论。我整理了一个排查表现象可能原因排查方法完全黑屏缓冲区已清空检查是否在 postRender 外读取部分黑块地形瓦片未加载完监听 tileLoadProgress透明背景alpha 通道未处理检查 toDataURL 的格式参数只有底图无标注标注在独立图层检查标注是否在同一 scene排查的时候建议按顺序来先确认时机对不对再确认数据加载完没有最后确认格式参数。我见过有同学折腾了一下午最后发现是toDataURL(image/jpeg)把透明背景压成了黑色换成 PNG 就好了。5.2 跨域图片污染画布这个坑非常隐蔽。如果你的地图上叠加了来自其他域名的图片比如自定义的图标、贴图调用toDataURL()时会抛出安全异常提示画布已被污染。原因是浏览器的同源策略不允许读取跨域资源的像素数据。解决办法是给这些图片设置crossOrigin anonymous并且确保服务端返回了正确的 CORS 响应头。如果资源不在你控制范围内那就只能走服务端代理把图片先下载到同源再使用。这个问题在开发环境往往不会暴露因为本地都是同源一上线就炸所以一定要提前测。5.3 组件销毁时的竞态问题Vue 的组件生命周期和 Cesium 的渲染循环是两套独立的机制如果处理不好会出现组件已销毁但截图回调还在执行的情况。表现就是控制台报错或者截图返回一张空白图。我的做法是在组合式函数里维护一个isDestroyed标志在onUnmounted里置为 true所有异步操作在关键节点检查这个标志let destroyed false onUnmounted(() { destroyed true }) async function capture() { // ... await someAsyncStep() if (destroyed) return null // ... }这个模式看起来有点啰嗦但在复杂的单页应用里能省掉很多莫名其妙的 bug。5.4 移动端的特殊处理移动端浏览器对 Canvas 尺寸的限制比桌面端严格得多。iOS Safari 有个著名的限制单个 Canvas 的总像素数不能超过约 1670 万具体数值随设备变化超过就会渲染失败或者返回空白。这意味着在 iPhone 上你的截图尺寸上限大概是 4096×4096 左右。所以移动端一定要做尺寸检查超限就自动降级const MAX_PIXELS 16 * 1024 * 1024 if (targetWidth * targetHeight MAX_PIXELS) { const ratio Math.sqrt(MAX_PIXELS / (targetWidth * targetHeight)) targetWidth Math.floor(targetWidth * ratio) targetHeight Math.floor(targetHeight * ratio) }另外移动端的截图触发最好绑定在用户明确的操作上比如点击按钮不要放在滚动或者手势回调里否则很容易触发浏览器的性能保护机制。6. 从截图到导出完整链路的收尾工作6.1 图片格式的选择拿到 Canvas 之后导出格式的选择也有讲究。PNG 无损、支持透明但体积大JPEG 体积小但不支持透明而且有压缩损失。对于地图截图我一般推荐 PNG因为地图上往往有大量文字和线条JPEG 的压缩会让文字边缘出现噪点。如果确实需要控制体积可以用toDataURL(image/jpeg, 0.92)质量参数设在 0.9 以上肉眼基本看不出差别。低于 0.8 就会出现明显的块状伪影尤其是地图这种细节丰富的图。6.2 触发下载的正确姿势导出图片时不要用window.open(dataUrl)这个方式在部分浏览器上会被拦截而且大图会卡死。正确做法是创建一个隐藏的a标签设置download属性然后模拟点击function downloadImage(dataUrl, filename) { const link document.createElement(a) link.href dataUrl link.download filename || map-${Date.now()}.png document.body.appendChild(link) link.click() document.body.removeChild(link) }记得用完把标签移除否则会在 DOM 里堆积一堆无用的节点。6.3 上传场景的注意事项如果截图是要上传到服务端的注意dataURL转Blob的过程。直接传dataURL字符串会浪费约 33% 的带宽Base64 编码的开销转成Blob用FormData上传更高效function dataURLToBlob(dataUrl) { const [header, data] dataUrl.split(,) const mime header.match(/:(.*?);/)[1] const binary atob(data) const array new Uint8Array(binary.length) for (let i 0; i binary.length; i) { array[i] binary.charCodeAt(i) } return new Blob([array], { type: mime }) }这个转换在大图上会有一定的耗时建议放在 Web Worker 里做避免阻塞主线程导致页面卡顿。7. 我在实际项目里踩过的几个坑第一个坑是关于preserveDrawingBuffer的。早期我图省事直接在 Viewer 初始化时开了这个选项结果发现地图整体帧率下降了不少。后来查资料才知道开启这个选项会让浏览器每帧都保留缓冲区牺牲了性能。正确的做法是默认关闭只在截图时临时开启截完立刻关闭。但这里有个细节preserveDrawingBuffer是 WebGL 上下文创建时的参数运行中改不了所以要么在初始化时就决定要么用离屏渲染方案绕开。我最后选了离屏渲染虽然代码复杂点但性能可控。第二个坑是关于标注闪烁的。截图时我临时调整了标注的 scale结果截完恢复的时候因为浮点数精度问题scale 值和原来差了那么一点点导致标注看起来抖了一下。解决办法是先把原始 scale 存下来恢复时直接赋原值不要用乘除法反推。第三个坑是关于异步加载的。有一次截图总是缺一块地形排查半天发现是地形瓦片还在加载中。后来我在截图前加了一个等待逻辑监听scene.globe.tileLoadProgressEvent等remaining降到 0 再截。但这个等待不能无限等得设个超时否则网络不好时用户会一直卡着。function waitForTilesLoaded(scene, timeout 5000) { return new Promise((resolve) { const start Date.now() const check () { if (scene.globe.tileLoadProgressEvent.numberOfPendingRequests 0) { resolve(true) } else if (Date.now() - start timeout) { resolve(false) } else { requestAnimationFrame(check) } } check() }) }这个函数返回一个布尔值告诉调用方是正常加载完还是超时了。超时的情况下你可以选择继续截图接受不完整或者提示用户重试具体看业务需求。第四个坑是关于内存的。频繁截图会产生大量 Canvas 对象如果不及时释放内存会持续增长。我的做法是每次截图完如果不再需要这个 Canvas就手动把它的宽高设为 0触发浏览器回收function releaseCanvas(canvas) { canvas.width 0 canvas.height 0 }这个技巧看起来有点土但在长时间运行的可视化大屏项目里非常管用。8. 写在最后的一点个人体会做三维可视化这几年我越来越觉得像截图这种看起来边缘的功能其实最能体现一个项目的完成度。用户不会因为你地图渲染得多炫酷就夸你但一定会因为截图截不出来、截出来是黑的而骂你。所以别小看这些细节把它们做扎实项目的口碑自然就上来了。另外Cesium 的社区虽然活跃但中文资料相对零散很多问题得靠翻源码和英文论坛解决。我的建议是遇到问题先别急着搜先把 Cesium 的官方文档和 API 注释过一遍很多时候答案就在那里只是你没注意到。比如Scene类里关于render和postRender的说明就藏着截图时机的关键信息。如果你在实现过程中遇到了这篇没覆盖到的情况欢迎一起交流。三维可视化的坑是踩不完的但每填一个就离好用近一步。
1. 从截个图而已说起为什么Cesium截图值得单独写一篇很多人第一次听到给三维地图截图这个需求第一反应都是调个浏览器截图 API 不就完了我当初也是这么想的直到真正在项目里动手才发现事情远没有这么简单。Cesium 渲染出来的三维场景底层用的是 WebGL 画布而 WebGL 有一个非常关键的默认行为——绘图缓冲区在每一帧渲染完成后会被清空。这意味着你如果在渲染循环之外去读取画布像素大概率拿到的是一张全黑或者全透明的图。这个坑我在早期项目里踩过不止一次。当时的需求很朴素用户在地图上摆好视角点一下按钮把当前画面存成图片方便贴到报告里或者分享给同事。听起来简单但真正落地时会牵扯出一连串问题怎么保证截到的是当前这一帧而不是上一帧地图上的标注、图层、地形是不是都能一起截进去截图分辨率能不能比屏幕更高做出高清大图的效果如果地图容器被其他 DOM 元素遮挡截图会不会把遮挡物也带进去这一篇是Cesium Vue 实现地图截图系列的第四篇前面几篇分别聊了基础截图、高清截图、以及带标注的合成截图。到了这一篇我想把重点放在屏幕截图与地图截图的区别、Vue 组件化封装、以及实际项目里那些让人抓狂的边界情况上。如果你正在用 Vue 做三维可视化项目需要给用户提供一个稳定可靠的截图功能那这篇内容应该能帮你少走不少弯路。我会尽量把每一步的为什么讲清楚而不是只丢一段代码让你抄。需要提前说明的是Cesium 的版本迭代比较快不同版本在渲染管线、API 命名上会有差异。我下面提到的方案基于较新的 Cesium 版本1.100 以上和 Vue 3 的组合式 API 来写如果你用的是 Vue 2 或者更老的 Cesium思路是一样的只是写法要相应调整。这一点在动手前一定要先确认清楚否则很容易出现代码看着没错但就是跑不通的情况。2. 屏幕截图和地图截图到底差在哪2.1 两种截图的本质区别在动手写代码之前有必要先把概念理清楚。很多人把屏幕截图和地图截图混为一谈实际上它们解决的是两个不同的问题。屏幕截图顾名思义截取的是用户当前屏幕上看到的内容包括地图画布、地图上的 UI 控件、你自己叠加的按钮和面板等等。它的特点是所见即所得用户看到什么就截什么。实现上通常依赖浏览器的canvas.toDataURL()或者html2canvas这类库。地图截图截取的则仅仅是 Cesium 渲染出来的三维场景本身不包含任何 DOM 层面的 UI。它的特点是纯净适合用来生成报告配图、导出成果图。实现上需要直接操作 Cesium 的渲染器通过scene.render()配合preserveDrawingBuffer或者离屏渲染来拿到像素数据。我见过不少项目在这两者之间反复横跳最后做出来的功能既不像屏幕截图也不像地图截图用户体验很割裂。所以在设计功能之前先问自己一句用户拿到这张图是要干什么如果是发朋友圈、贴聊天记录那屏幕截图更合适如果是做汇报材料、存档留证那地图截图更专业。2.2 为什么不能直接用浏览器截图 API有同学会问现在浏览器不是有navigator.mediaDevices.getDisplayMedia()吗直接调系统级的屏幕捕获不就行了这个方案确实存在但它有几个硬伤。第一它会弹出系统级的授权对话框用户必须手动选择要共享的屏幕或窗口这个交互在网页应用里非常突兀体验很差。第二它捕获的是整个屏幕或窗口你没法精确控制只截地图区域后期还得裁剪。第三不同浏览器、不同操作系统对这个 API 的支持程度参差不齐兼容性是个大问题。所以对于截取地图区域这种明确的需求最靠谱的做法还是回到 Canvas 层面直接读取 Cesium 渲染出来的像素。这也是本系列一直采用的技术路线。2.3 Cesium 渲染管线的关键约束要理解截图为什么难得先理解 Cesium 的渲染管线。Cesium 每一帧的渲染流程大致是这样的先清空绘图缓冲区然后依次渲染地形、影像、模型、标注等图层最后把结果呈现到屏幕上。关键在于默认情况下渲染完成后绘图缓冲区的内容就不再保留了这是 WebGL 为了性能做的优化。这就导致一个直接后果如果你在requestAnimationFrame回调之外去调canvas.toDataURL()浏览器会告诉你当前缓冲区没有有效数据返回的要么是空白要么是上一次的残留。解决办法有两个一是开启contextOptions.webgl.preserveDrawingBuffer让缓冲区内容保留下来二是在scene.postRender事件里趁着这一帧刚渲染完、缓冲区还有数据的时候立刻读取。这两种方案各有取舍后面我会详细对比。这里先记住一个结论截图时机的选择比截图代码本身更重要。3. Vue 组件化封装把截图逻辑收进一个可复用的盒子3.1 为什么要在 Vue 里做组件化封装在 Vue 项目里截图功能往往散落在各个业务组件里今天这个页面写一遍明天那个页面又抄一遍代码重复不说一旦 Cesium 升级或者发现 bug改起来就是灾难。我的做法是把它封装成一个独立的组合式函数Composition API 的useMapScreenshot或者一个无渲染组件让业务层只需要调用一个方法就能拿到图片。这样做的好处有三个一是逻辑集中所有截图相关的坑都在一个文件里处理二是便于测试可以单独针对这个函数写单元测试三是接口清晰业务层不需要关心 Cesium 内部怎么渲染只需要传参数、拿结果。3.2 组合式函数的基本骨架先看一个最简化的骨架把核心流程串起来// useMapScreenshot.js import { ref, onUnmounted } from vue export function useMapScreenshot(viewerRef) { const isCapturing ref(false) async function capture(options {}) { const viewer viewerRef.value if (!viewer || viewer.isDestroyed()) { throw new Error(Viewer 尚未初始化或已销毁) } isCapturing.value true try { const canvas await renderToCanvas(viewer, options) return canvas } finally { isCapturing.value false } } return { isCapturing, capture } }这个骨架里viewerRef是业务层传进来的 Cesium Viewer 引用capture是暴露给业务层的方法。注意我在开头做了isDestroyed()检查这个检查非常必要——Vue 组件销毁和 Cesium Viewer 销毁的时机不一定同步如果用户在组件卸载的瞬间点了截图很容易触发空指针异常。3.3 渲染到离屏 Canvas 的核心实现接下来是核心的renderToCanvas函数。它的思路是创建一个离屏 Canvas把 Cesium 当前场景渲染到这个 Canvas 上然后返回。这样做的好处是不依赖preserveDrawingBuffer也不需要担心缓冲区被清空的问题。async function renderToCanvas(viewer, options) { const { width, height, scale 1 } options const scene viewer.scene const canvas scene.canvas const targetWidth width || canvas.width * scale const targetHeight height || canvas.height * scale const offscreen document.createElement(canvas) offscreen.width targetWidth offscreen.height targetHeight // 保存当前渲染状态 const originalWidth canvas.width const originalHeight canvas.height const originalRatio scene.pixelRatio try { // 调整渲染尺寸 canvas.width targetWidth canvas.height targetHeight scene.pixelRatio 1 // 强制重新渲染一帧 scene.render() // 把渲染结果绘制到离屏 Canvas const ctx offscreen.getContext(2d) ctx.drawImage(canvas, 0, 0, targetWidth, targetHeight) return offscreen } finally { // 恢复原始状态 canvas.width originalWidth canvas.height originalHeight scene.pixelRatio originalRatio scene.render() } }这段代码里有几个细节值得展开说。第一我临时修改了canvas.width和canvas.height这是为了支持高清截图——把画布尺寸调大Cesium 就会以更高的分辨率渲染截出来的图自然更清晰。第二scene.pixelRatio设为 1 是为了避免设备像素比带来的二次缩放否则在高 DPI 屏幕上尺寸会翻倍。第三finally块里一定要恢复原始状态并重新渲染否则地图会停留在截图时的尺寸用户会看到画面跳一下。注意修改canvas.width会触发 WebGL 上下文重建这个过程在部分浏览器上会有明显的卡顿。如果截图频率很高建议改用scene.render()配合preserveDrawingBuffer的方案避免频繁重建上下文。3.4 在业务组件里怎么用封装好之后业务层的代码就非常清爽了template div classmap-wrapper div refmapContainer classmap-container/div button :disabledisCapturing clickhandleCapture {{ isCapturing ? 截图中... : 截图 }} /button /div /template script setup import { ref, onMounted } from vue import { useMapScreenshot } from ./useMapScreenshot const mapContainer ref(null) const viewerRef ref(null) const { isCapturing, capture } useMapScreenshot(viewerRef) onMounted(() { // 初始化 Cesium Viewer赋值给 viewerRef }) async function handleCapture() { const canvas await capture({ scale: 2 }) const dataUrl canvas.toDataURL(image/png) // 触发下载或上传 } /script这种写法把怎么截和截了干什么彻底解耦业务层只关心结果不关心过程。后面如果要换截图方案只改useMapScreenshot一个文件就行。4. 高清截图的参数计算与性能权衡4.1 分辨率到底该设多大高清截图是很多项目的刚需尤其是做汇报材料的时候屏幕分辨率的图放大就糊。但分辨率不是越大越好这里有个平衡点。假设你的地图容器在屏幕上是 1200×800 像素如果scale设为 2那截图就是 2400×1600设为 4 就是 4800×3200。看起来很美但你要考虑两个限制一是 WebGL 的纹理尺寸上限不同设备不一样常见的是 4096 或 8192超过这个值渲染会失败二是显存占用分辨率翻倍显存占用是四倍增长低端设备很容易崩。我的经验是桌面端 scale 设 2 比较稳妥移动端设 1.5 就够了。如果确实需要超大图可以分块渲染再拼接但这个复杂度就上去了一般项目用不上。4.2 一个容易忽略的坑标注和文字会变模糊高清截图有个反直觉的现象地图底图清晰了但上面的标注文字反而变糊了。原因是 Cesium 的标注Billboard、Label默认是按屏幕像素渲染的你把画布尺寸调大标注的尺寸没跟着变相对就显得小了放大后自然模糊。解决办法是在截图前临时调整标注的缩放比例。Cesium 的BillboardCollection和LabelCollection都支持scale属性你可以在截图前遍历所有标注把 scale 乘以截图倍率截完再改回来。这个操作有点繁琐但效果立竿见影。function adjustBillboardScale(scene, factor) { const collections scene.primitives._primitives.filter( p p instanceof Cesium.BillboardCollection ) collections.forEach(collection { for (let i 0; i collection.length; i) { const billboard collection.get(i) billboard.scale * factor } }) }4.3 性能实测数据参考我在一台中等配置的笔记本上做过测试地图容器 1200×800场景里有约 500 个标注和一片地形。结果如下截图倍率输出尺寸单次耗时显存峰值1x1200×800约 80ms正常2x2400×1600约 220ms略升4x4800×3200约 900ms明显升高8x9600×6400渲染失败超限可以看到4x 开始耗时就有明显上升8x 直接失败。所以如果你的场景比较复杂建议把倍率控制在 2x 以内并且给用户一个截图中的 loading 提示避免他们以为卡死了反复点击。5. 那些让人抓狂的边界情况5.1 截图全黑最常见也最容易被误判的问题截图全黑是新手遇到最多的现象但它的成因有好几种不能一概而论。我整理了一个排查表现象可能原因排查方法完全黑屏缓冲区已清空检查是否在 postRender 外读取部分黑块地形瓦片未加载完监听 tileLoadProgress透明背景alpha 通道未处理检查 toDataURL 的格式参数只有底图无标注标注在独立图层检查标注是否在同一 scene排查的时候建议按顺序来先确认时机对不对再确认数据加载完没有最后确认格式参数。我见过有同学折腾了一下午最后发现是toDataURL(image/jpeg)把透明背景压成了黑色换成 PNG 就好了。5.2 跨域图片污染画布这个坑非常隐蔽。如果你的地图上叠加了来自其他域名的图片比如自定义的图标、贴图调用toDataURL()时会抛出安全异常提示画布已被污染。原因是浏览器的同源策略不允许读取跨域资源的像素数据。解决办法是给这些图片设置crossOrigin anonymous并且确保服务端返回了正确的 CORS 响应头。如果资源不在你控制范围内那就只能走服务端代理把图片先下载到同源再使用。这个问题在开发环境往往不会暴露因为本地都是同源一上线就炸所以一定要提前测。5.3 组件销毁时的竞态问题Vue 的组件生命周期和 Cesium 的渲染循环是两套独立的机制如果处理不好会出现组件已销毁但截图回调还在执行的情况。表现就是控制台报错或者截图返回一张空白图。我的做法是在组合式函数里维护一个isDestroyed标志在onUnmounted里置为 true所有异步操作在关键节点检查这个标志let destroyed false onUnmounted(() { destroyed true }) async function capture() { // ... await someAsyncStep() if (destroyed) return null // ... }这个模式看起来有点啰嗦但在复杂的单页应用里能省掉很多莫名其妙的 bug。5.4 移动端的特殊处理移动端浏览器对 Canvas 尺寸的限制比桌面端严格得多。iOS Safari 有个著名的限制单个 Canvas 的总像素数不能超过约 1670 万具体数值随设备变化超过就会渲染失败或者返回空白。这意味着在 iPhone 上你的截图尺寸上限大概是 4096×4096 左右。所以移动端一定要做尺寸检查超限就自动降级const MAX_PIXELS 16 * 1024 * 1024 if (targetWidth * targetHeight MAX_PIXELS) { const ratio Math.sqrt(MAX_PIXELS / (targetWidth * targetHeight)) targetWidth Math.floor(targetWidth * ratio) targetHeight Math.floor(targetHeight * ratio) }另外移动端的截图触发最好绑定在用户明确的操作上比如点击按钮不要放在滚动或者手势回调里否则很容易触发浏览器的性能保护机制。6. 从截图到导出完整链路的收尾工作6.1 图片格式的选择拿到 Canvas 之后导出格式的选择也有讲究。PNG 无损、支持透明但体积大JPEG 体积小但不支持透明而且有压缩损失。对于地图截图我一般推荐 PNG因为地图上往往有大量文字和线条JPEG 的压缩会让文字边缘出现噪点。如果确实需要控制体积可以用toDataURL(image/jpeg, 0.92)质量参数设在 0.9 以上肉眼基本看不出差别。低于 0.8 就会出现明显的块状伪影尤其是地图这种细节丰富的图。6.2 触发下载的正确姿势导出图片时不要用window.open(dataUrl)这个方式在部分浏览器上会被拦截而且大图会卡死。正确做法是创建一个隐藏的a标签设置download属性然后模拟点击function downloadImage(dataUrl, filename) { const link document.createElement(a) link.href dataUrl link.download filename || map-${Date.now()}.png document.body.appendChild(link) link.click() document.body.removeChild(link) }记得用完把标签移除否则会在 DOM 里堆积一堆无用的节点。6.3 上传场景的注意事项如果截图是要上传到服务端的注意dataURL转Blob的过程。直接传dataURL字符串会浪费约 33% 的带宽Base64 编码的开销转成Blob用FormData上传更高效function dataURLToBlob(dataUrl) { const [header, data] dataUrl.split(,) const mime header.match(/:(.*?);/)[1] const binary atob(data) const array new Uint8Array(binary.length) for (let i 0; i binary.length; i) { array[i] binary.charCodeAt(i) } return new Blob([array], { type: mime }) }这个转换在大图上会有一定的耗时建议放在 Web Worker 里做避免阻塞主线程导致页面卡顿。7. 我在实际项目里踩过的几个坑第一个坑是关于preserveDrawingBuffer的。早期我图省事直接在 Viewer 初始化时开了这个选项结果发现地图整体帧率下降了不少。后来查资料才知道开启这个选项会让浏览器每帧都保留缓冲区牺牲了性能。正确的做法是默认关闭只在截图时临时开启截完立刻关闭。但这里有个细节preserveDrawingBuffer是 WebGL 上下文创建时的参数运行中改不了所以要么在初始化时就决定要么用离屏渲染方案绕开。我最后选了离屏渲染虽然代码复杂点但性能可控。第二个坑是关于标注闪烁的。截图时我临时调整了标注的 scale结果截完恢复的时候因为浮点数精度问题scale 值和原来差了那么一点点导致标注看起来抖了一下。解决办法是先把原始 scale 存下来恢复时直接赋原值不要用乘除法反推。第三个坑是关于异步加载的。有一次截图总是缺一块地形排查半天发现是地形瓦片还在加载中。后来我在截图前加了一个等待逻辑监听scene.globe.tileLoadProgressEvent等remaining降到 0 再截。但这个等待不能无限等得设个超时否则网络不好时用户会一直卡着。function waitForTilesLoaded(scene, timeout 5000) { return new Promise((resolve) { const start Date.now() const check () { if (scene.globe.tileLoadProgressEvent.numberOfPendingRequests 0) { resolve(true) } else if (Date.now() - start timeout) { resolve(false) } else { requestAnimationFrame(check) } } check() }) }这个函数返回一个布尔值告诉调用方是正常加载完还是超时了。超时的情况下你可以选择继续截图接受不完整或者提示用户重试具体看业务需求。第四个坑是关于内存的。频繁截图会产生大量 Canvas 对象如果不及时释放内存会持续增长。我的做法是每次截图完如果不再需要这个 Canvas就手动把它的宽高设为 0触发浏览器回收function releaseCanvas(canvas) { canvas.width 0 canvas.height 0 }这个技巧看起来有点土但在长时间运行的可视化大屏项目里非常管用。8. 写在最后的一点个人体会做三维可视化这几年我越来越觉得像截图这种看起来边缘的功能其实最能体现一个项目的完成度。用户不会因为你地图渲染得多炫酷就夸你但一定会因为截图截不出来、截出来是黑的而骂你。所以别小看这些细节把它们做扎实项目的口碑自然就上来了。另外Cesium 的社区虽然活跃但中文资料相对零散很多问题得靠翻源码和英文论坛解决。我的建议是遇到问题先别急着搜先把 Cesium 的官方文档和 API 注释过一遍很多时候答案就在那里只是你没注意到。比如Scene类里关于render和postRender的说明就藏着截图时机的关键信息。如果你在实现过程中遇到了这篇没覆盖到的情况欢迎一起交流。三维可视化的坑是踩不完的但每填一个就离好用近一步。
