做数据大屏的人多半都被问过这么一句这个饼图能不能做成有厚度、能转、看起来立体一点的那种。然后你兴冲冲打开 ECharts 官网翻配置项把所有 series type 过了一遍发现根本没有 3D 饼图这个东西——ECharts 原生的饼图只有一个平面圆靠 itemStyle 加点阴影最多算个浮雕。真正的 ECharts 3D 饼图核心靠的是echarts-gl这个扩展包里的pie3D系列。它把平面饼图的每个扇区拉伸成一个有厚度的实体块再套一层 3D 场景的透视和光照最终渲染到 WebGL 画布上。这篇东西解决的就是从知道有 pie3D到能交付一个上大屏不翻车之间的全部问题依赖怎么装、参数怎么调、标签为什么糊、移动端 rem 为什么对它失效、性能怎么压。适合两类人看——一类是刚接手可视化大屏、还没碰过 WebGL 的前端另一类是做过 2D 饼图、但被 3D 版本的玄学问题折腾过一轮的人。我把三条实现路线、两套可跑的完整代码、一张排查速查表都放进来了你可以直接抄。1. ECharts 3D饼图的本质与三条实现路线1.1 原生 ECharts 为什么死活不做3D饼图先把一个常见误解掰正ECharts 和 echarts-gl 是两个包。ECharts 本体负责 2D 的坐标系、Canvas/SVG 渲染器、交互事件体系echarts-gl 是社区维护的扩展挂了一个基于 WebGL 的渲染层专门做bar3D、scatter3D、surface、globe、pie3D这些三维图表。你 npm 装了 echarts 却没装 echarts-gl控制台会直接告诉你series.type: pie3D不认识图表区域一片空白。官方不做原生 3D 饼图逻辑上很好理解。饼图的本质是整体与部分的比例关系它的信息表达完全依赖扇区角度也就是一个二维量。一旦给它加上厚度这个厚度在数据上没有承载任何语义——它不是第三个维度只是视觉装饰。从数据可视化的严谨角度看3D 饼图属于用可读性换观感的典型。但在大屏场景里甲方要的从来不是最严谨而是看起来高级。所以这个需求长期存在echarts-gl 也就把这活儿接了。用生活化的类比2D 饼图是一张俯视的切蛋糕照片3D 饼图是你把这块蛋糕从桌上抬起来、侧过 40 度看。蛋糕本身没变变的是你的视角和它投下的阴影而人的眼睛对这些阴影的敏感度远比想象中高——这就是 3D 版本显得更贵的根本原因。1.2 三条路线的横向对比与选型建议我在不同项目里三种方案都用过结论很明确没有银弹看你项目的约束条件。维度echarts-gl pie3D多层 2D 饼图叠影three.js 自绘真实 3D 感强有光照和透视中只有厚度无透视最强完全可控可交互旋转支持鼠标可拖不支持支持引入体积约 600~800KB0 额外体积约 600KB 起浏览器兼容需 WebGL低端安卓吃力全兼容需 WebGL上手成本低配置项即可低但要手写循环高要写几何体和着色器与 ECharts 生态完全打通tooltip/事件复用完全打通完全脱离事件要自己写适合场景中大屏、PC 端为主兼容性优先、需要静态截图定制化极强的品牌大屏多数项目的正确解是第一条。原因有三个一是 ECharts 的 tooltip、legend、事件体系能直接复用你不需要重造轮子二是配置项驱动改需求时改数字就行不用动渲染逻辑三是 echarts-gl 的 pie3D 已经帮你处理了扇形几何体的三角剖分、法线计算和光照方向自己写这三个东西至少要一天。选第二条的唯一理由是兼容性。如果你的大屏要跑在政务大厅那种十年前的工控机、或者要保证在微信内置浏览器里不白屏WebGL 上下文可能压根创建不出来。这时候多层叠影是稳妥选择代价是失去旋转交互。选第三条只在这两种情况下考虑一是要做出扇区炸开、飞散、粒子化这种超常规效果二是设计稿里的光照、材质、反射有明确要求配置项调不出来。除此之外用 three.js 做饼图属于过度工程。1.3 依赖版本与环境准备版本搭配有坑我按实测最稳的一组给你。# npm 方式 npm i echarts5.4.3 echarts-gl2.0.9 # 或者 CDN 方式注意 echarts-gl 必须放在 echarts 之后 # script srchttps://cdn.jsdelivr.net/npm/echarts5.4.3/dist/echarts.min.js/script # script srchttps://cdn.jsdelivr.net/npm/echarts-gl2.0.9/dist/echarts-gl.min.js/script注意echarts-gl 2.x 要求的 ECharts 版本是 5.1.2 及以上。如果你项目里锁的是 ECharts 4.x必须用 echarts-gl 1.x两者的 API 有差异别混用。另外 echarts-gl 的按需引入支持非常有限pie3D这个系列的依赖链条拉得很长实际上大部分项目都是整包引入首屏体积多出 600~800KB 是正常的别为此纠结。初始化骨架很简单关键是容器必须有明确高度。这一点跟 2D 图表一样但 3D 场景对高度更敏感——高度不够时透视被压扁饼图会看起来像一块薄饼皮。import * as echarts from echarts; import echarts-gl; // 关键不引入这一行pie3D 会报 unknown series type const dom document.getElementById(chart); const chart echarts.init(dom, null, { renderer: canvas });实操心得echarts-gl 强制走 Canvas 渲染器你就算在 init 里传renderer: svg也会被内部覆盖。所以别指望用 SVG 导出高清矢量图3D 饼图的导出只能靠getDataURL()拿位图分辨率由devicePixelRatio决定。需要印刷级清晰度的把容器的 canvas 放大两倍再getDataURL。2. pie3D 的核心参数到底在控制什么2.1 厚度、角度、半径三个最容易调错的量pie3D继承自 2D 饼图所以radius、center、startAngle、minAngle、clockwise、data这些都能直接用。它额外加的关键参数其实只有三个height、angle、shading。height控制扇区拉伸的厚度单位是像素但这个像素在 3D 场景里受透视影响不等于屏幕上的实际像素。实测下来15 到 30 是大多数大屏合适的区间低于 12 像张纸高于 40 会显得笨重而且侧面的着色面积增大后如果配色不当会显脏。angle是饼图绕自身法线旋转的角度用来调整扇区的起始朝向。它不改变数据纯粹是构图。默认值很多时候会让最大的扇区正好卡在正前方挡住后面小扇区的标签这时候把angle调个 30 到 60 度往往就顺眼了。radius接受字符串百分比或数字数组用法跟 2D 完全一样。想要环形 3D 饼图中间挖空就用radius: [35%, 68%]。有个细节内半径越小中央的空洞在 3D 视角下越容易被前面的扇区挡住视觉上洞会显得比设定值小。所以我一般把内半径给到 35% 以上保证环形结构看得清。series: [{ type: pie3D, radius: [35%, 68%], height: 24, angle: 45, startAngle: 90, minAngle: 6, clockWise: true }]minAngle这个参数值得单独说。饼图里如果有个占比 0.3% 的数据项在 360 度里只有 1 度多3D 渲染下基本就是一条线鼠标根本点不中标签也挤在一起。设minAngle: 6能保证每个扇区至少占 6 度可点击、可标注。代价是角度总和超过 360 度饼图不再严格等比——所以这个值要在图例或者副标题里说明一下别让人误读比例。2.2 光照模型 shading 三选一的取舍shading决定扇区侧面和顶面怎么被照亮三个可选值color、lambert、realistic。color最省性能它压根不算光照侧面就是顶面颜色的固定比例加深看起来平、没有明暗过渡。适合那种一屏放五六个图表、性能吃紧的场景。lambert是默认值走的是朗伯漫反射模型只有漫反射没有高光扇区侧面会出现从亮到暗的自然渐变。这个是我最常用的性价比最高。realistic用的是 PBR基于物理的渲染有粗糙度和金属度扇区边缘会有明显的高光带质感接近塑料或者陶瓷。好看但代价很实在着色器复杂度上升低端设备帧率掉得厉害而且在深色背景下高光会过曝成一片白。注意如果你用了realistic一定要配合调itemStyle.opacity和背景色。深底 realistic 高透明度是翻车重灾区扇区会糊成一团发光体完全看不出边界。我的做法是深底用lambert浅底可以尝试realistic。2.3 视角控制 viewControl 与容器尺寸的隐性约束旋转和俯仰靠viewControl。这个配置在 ECharts GL 里是根级组件放在option顶层而不是 series 里。option { viewControl: { alpha: 42, // 俯仰角0 是正上方俯视90 是水平平视 beta: 0, // 水平旋转角 distance: 200, // 相机距原点的距离数值越小图像越大 autoRotate: false, // 是否自动旋转 autoRotateSpeed: 8, // 自动旋转速度 rotateSensitivity: 1, zoomSensitivity: 0 // 关掉滚轮缩放避免和页面滚动冲突 } };alpha是最关键的。设 0 就是完全俯视你会看到一个普通的 2D 饼图厚度完全看不见设 90 是完全平视饼图退化成一条线。实测 35 到 50 之间最舒服既能看清扇区比例又能看到厚度。我一般用 42 起步。zoomSensitivity我习惯设 0。大屏页面通常本身可以上下滚动如果滚轮被 3D 场景吃掉了用户在图表上滚动页面就卡住了体验很差。需要缩放就加个按钮或者用双指手势。autoRotate要谨慎。它确实能让大屏活起来但一旦开启鼠标悬停触发 tooltip 会变得很别扭——扇区一直在转你追不上。我的做法是默认不开只在无人交互超过 30 秒时通过定时器打开用户一碰鼠标就关掉。还有个隐性约束3D 场景的相机是透视投影容器宽高比会直接影响观感。同样是alpha: 42宽高比 4:1 的扁长容器和 1:1 的方形容器饼图看起来完全不是一个东西。扁长容器会显得饼图被横向拉宽。所以布局阶段就要把容器定成接近 1:1 或 4:3别为了省空间硬塞进一个扁条里。3. 从零手撸一个能上大屏的3D饼图3.1 数据清洗先算总数再决定要不要合并渲染之前先处理数据这一步比调参数重要得多。我的经验是扇区数量控制在 5 到 8 个之间超过 10 个基本就没法看了——3D 视角下后排扇区被前排遮挡标签互相挤鼠标也点不准。const rawData [ { name: 华东, value: 435 }, { name: 华北, value: 310 }, { name: 华南, value: 234 }, { name: 西南, value: 155 }, { name: 西北, value: 120 }, { name: 东北, value: 98 }, { name: 华中, value: 86 }, { name: 港澳台, value: 42 }, { name: 海外, value: 18 } ]; const TOP_N 6; const THRESHOLD 0.03; // 占比低于 3% 的合并 function normalize(raw) { const total raw.reduce((s, d) s d.value, 0); const sorted [...raw].sort((a, b) b.value - a.value); const major []; let otherValue 0; sorted.forEach((d, i) { // 前 TOP_N 个里占比够大的保留 if (i TOP_N d.value / total THRESHOLD) { major.push(d); } else { otherValue d.value; } }); if (otherValue 0) { major.push({ name: 其他, value: otherValue }); } return major; } const pieData normalize(rawData);这段逻辑看起来简单但有两个坑要避开。第一合并后的其他项可能排到前三位破坏排序直觉所以我在合并完后又做了一次排序。第二其他项的 tooltip 里最好能列出被合并的明细否则用户会疑惑这 144 到底包含了什么。// 给其他项挂一个自定义字段tooltip 里展示明细 major[major.length - 1].detail otherNames.join(、);实操心得数据合并的阈值不要写死。如果是按区域分通常保留前 6 大区域如果是按产品线分产品线数量本来就不多那就全保留。判断标准是用户会不会对某一项单独提问。会问的就必须保留不会问的合并掉。3.2 完整的 option 配置与逐项说明下面这份配置是我在多个大屏项目里反复调过的版本深色底青色系可以直接跑。const COLORS [ #00E5FF, #3D7EFF, #7A5CFF, #FF6B9D, #FFC93C, #2EE6A8, #8A93B2 ]; const option { backgroundColor: transparent, color: COLORS, tooltip: { trigger: item, backgroundColor: rgba(10,22,44,0.92), borderColor: rgba(0,229,255,0.35), borderWidth: 1, padding: [10, 14], textStyle: { color: #DCE8FF, fontSize: 13, lineHeight: 20 }, extraCssText: white-space:normal;word-break:break-all;max-width:260px; border-radius:6px;box-shadow:0 6px 20px rgba(0,0,0,0.45);, formatter: (p) { const percent p.percent.toFixed(1); let html div stylefont-weight:600;margin-bottom:6px;${p.name}/div; html div数值span stylecolor:#00E5FF;font-weight:600;${p.value}/span 万元/div; html div占比${percent}%/div; if (p.data.detail) { html div stylemargin-top:6px;color:#8FA6CC;font-size:12px;含${p.data.detail}/div; } return html; } }, series: [ { type: pie3D, name: 区域销售额, radius: [35%, 68%], height: 24, angle: 45, startAngle: 90, minAngle: 6, clockWise: true, shading: lambert, itemStyle: { opacity: 0.96, borderWidth: 1, borderColor: rgba(255,255,255,0.12) }, label: { show: true, distance: 14, textStyle: { color: #B9CCEB, fontSize: 13, fontWeight: 500 }, formatter: {b} }, labelLine: { show: true, lineStyle: { color: rgba(140,170,220,0.55), width: 1 } }, emphasis: { itemStyle: { opacity: 1 }, label: { textStyle: { color: #FFFFFF, fontWeight: 600 } } }, data: pieData } ], viewControl: { alpha: 42, beta: 0, distance: 210, autoRotate: false, rotateSensitivity: 1, zoomSensitivity: 0, panSensitivity: 0 } }; chart.setOption(option);几个点拆开讲。itemStyle.borderWidth在 3D 饼图里的作用和 2D 不太一样。2D 里它是扇区之间的分割线3D 里它作用在扇区的顶面边缘和侧面接缝处宽度给 1 是让相邻扇区在颜色接近时有条暗缝方便区分。给太大超过 2会在接缝处出现明显的亮边很丑。label.distance控制标签离扇区边缘的距离。3D 场景下这个值需要比 2D 给得更大因为透视会把标签往中心方向吸。2D 常用 5 到 83D 里我一般给 12 到 16。emphasis里我只改了透明度没做扇区弹出。pie3D 不支持 2D 那种emphasis.scale放大效果强行用itemStyle改尺寸无效。想要选中弹出的效果得靠后面 4.1 说的手动调整数据顺序或者叠加第二个 series 来实现。3.3 标签、图例与 tooltip 的3D适配细节标签是 3D 饼图最容易翻车的地方。ECharts 的标签系统本质上还是 2D 的它计算出扇区的某个位置点然后把文字画在屏幕坐标上。在 3D 场景里这个位置点是经过透视投影后的结果于是会出现两个问题。第一个是标签遮挡。位于后排的扇区它的标签可能被前排的扇区实体挡住或者飘到一个看起来毫无关联的位置。这一点没有完美解法只能靠调viewControl.alpha和angle把标签尽量拉开。我的经验是把占比最大的两个扇区安排在左右两侧把最小的几个堆到后方这样标签的分布最均匀。第二个是labelLine的偏移。2D 饼图里labelLine.length和length2是精确的折线长度3D 里这条线同样经过投影视觉长度会被压缩末端的小圆点或者折角经常会偏。如果你对精度有要求我建议干脆关掉 labelLine改用扇区内的标签加底部 HTML 图例。label: { show: true, position: inside, // 标签画在扇区内部避免引出线的偏移问题 textStyle: { color: #FFFFFF, fontSize: 12 }, formatter: (p) (p.percent 8 ? ${p.name}\n${p.percent.toFixed(0)}% : ) }注意formatter里我做了个过滤占比小于 8% 的扇区不显示内部标签。因为扇区太小文字根本放不下硬画会溢出到相邻扇区上一片混乱。小占比项的信息交给 tooltip 和图例去承载。关于图例pie3D对 legend 的支持不完整——你配了 legend 它会渲染出来但点击图例切换扇区显示隐藏的行为在部分版本里不生效或者切换后 3D 几何体重建出错位。我通常这么处理不用 ECharts 的 legend 组件而是在图表旁边用普通的 HTML 写一个图例列表颜色块从chart.getOption().color里取点击时通过chart.dispatchAction或者直接改数据重绘。div classlegend div classlegend-item v-for(item, i) in pieData :keyitem.name span classdot :style{ background: COLORS[i % COLORS.length] }/span span classname{{ item.name }}/span span classvalue{{ item.value }}/span /div /div这样做的好处是图例的排版、字号、间距完全由 CSS 控制不受 ECharts 内部布局的约束而且可以加上数值列信息密度更高。tooltip 的换行问题在这里也要处理。ECharts 的 tooltip 默认是white-space: nowrap内容长了会撑成一条很宽的横条甚至超出屏幕。解决办法就是上面配置里那个extraCssText把white-space改成normal配合max-width和word-break: break-all。这在展示其他项的明细列表时特别必要。3.4 移动端 rem 适配为何对 ECharts 完全失效这个坑我踩过两次值得单独讲。项目里用了postcss-pxtoremCSS 里写 px 会自动转 rem页面缩放没问题。但你会发现图表里的字号、间距、标签大小纹丝不动——因为 ECharts 的fontSize、lineWidth、symbolSize、itemGap、distance这些参数都是 JS 数字走的是 Canvas 绘制postcss 在构建时处理的是 CSS 文件两者根本不碰面。正确的做法是在 JS 里写一个换算函数基于当前根字号把设计稿的 px 值转成实际像素。const BASE_WIDTH 1920; const BASE_FONT 16; function setRootFont() { const clientWidth document.documentElement.clientWidth; const scale clientWidth / BASE_WIDTH; document.documentElement.style.fontSize (BASE_FONT * scale) px; } function rem(px) { const rootFont parseFloat( getComputedStyle(document.documentElement).fontSize ); return (px / BASE_FONT) * rootFont; } // 初始化时执行一次并在 resize 时重算 setRootFont();然后把 option 里所有跟尺寸有关的数值都过一遍rem()const option { tooltip: { textStyle: { fontSize: rem(13), lineHeight: rem(20) }, extraCssText: max-width:${rem(260)}px;white-space:normal;word-break:break-all; }, series: [{ type: pie3D, radius: [35%, 68%], height: rem(24), label: { distance: rem(14), textStyle: { fontSize: rem(13), fontWeight: 500 } }, labelLine: { lineStyle: { width: Math.max(1, rem(1)) } } }], viewControl: { alpha: 42, distance: rem(210) } };有两个细节必须记住。第一viewControl.distance也受缩放影响如果不缩放它小屏上图会显得离得很近、撑满容器。第二lineWidth这类值不能小于 1rem(1)在 375px 宽的手机上算出来是 0.31Canvas 会把小于 0.5 的线宽处理成半透明甚至不画所以要用Math.max兜底。还有一点容易忽略图表容器变宽变窄时必须重新调用chart.resize()。但很多人只监听window.resize在大屏项目里这是不够的——侧边栏收起、Tab 切换、抽屉打开这些都会改变容器宽度但不触发 window resize。正确做法是用ResizeObserver直接监听容器。const ro new ResizeObserver(() { chart.resize(); }); ro.observe(document.getElementById(chart)); // 组件卸载时记得断开否则内存泄漏 // onUnmounted(() { ro.disconnect(); chart.dispose(); });4. 交互进阶与视觉打磨4.1 点击选中、高亮与数据下钻pie3D 的点击事件和 2D 饼图完全一致直接用chart.on(click, params {...})params.name、params.value、params.dataIndex都能拿到。这一层不用改。想做点击某个扇区后它弹出来的效果pie3D 没有内置支持。我的替代方案是把被选中的那一项从数据里拆出来单独用一个pie3Dseries 渲染给它更大的radius和height再加一点center偏移视觉上就实现弹出。let selectedIndex -1; function buildOption(data, selectedIndex) { const baseSeries { type: pie3D, radius: [35%, 68%], height: rem(24), angle: 45, shading: lambert, label: { show: true, formatter: {b}, distance: rem(14) } }; const series [{ ...baseSeries, data: data.map((d, i) ( i selectedIndex ? { ...d, itemStyle: { opacity: 0 } } // 原位置留空 : d )) }]; if (selectedIndex 0) { series.push({ ...baseSeries, radius: [38%, 74%], height: rem(32), startAngle: 90, data: [ // 用透明项占位保证角度位置不变 ...data.map((d, i) ( i selectedIndex ? d : { ...d, value: d.value, itemStyle: { opacity: 0 } } )) ] }); } return { series, viewControl: { alpha: 42, distance: rem(210) } }; }注意这个方案有个前提就是 scale 出来的 series 必须和原 series 共用相同的radius基准和startAngle否则弹出的扇区角度会和原来错位。另外透明占位项虽然看不见但仍会参与 tooltip 命中判定需要在 tooltip 的 formatter 里过滤掉opacity 0的项。数据下钻就简单了监听点击后替换pieData重新setOption记得加chart.showLoading()和hideLoading()让过渡不那么突兀。回退时维护一个层级栈就行。4.2 图例的替代方案与外部联动前面提了不用内置 legend。这里补充一个更进阶的玩法图例悬停时让对应的扇区高亮。实现方式是在图例 DOM 上绑mouseenter拿到索引后调chart.dispatchAction({ type: highlight, seriesIndex: 0, dataIndex: i })mouseleave时调downplay。function bindLegendHover(chart, domList) { domList.forEach((el, i) { el.addEventListener(mouseenter, () { chart.dispatchAction({ type: highlight, seriesIndex: 0, dataIndex: i }); }); el.addEventListener(mouseleave, () { chart.dispatchAction({ type: downplay, seriesIndex: 0, dataIndex: i }); }); }); }这里有个细节dispatchAction触发的高亮走的是 series 的emphasis配置。如果你在emphasis里只改了label的样式没改itemStyle那高亮的视觉反馈会很微弱用户看不出来。建议至少改一个明显的属性比如itemStyle.opacity从 0.96 到 1或者配合viewControl微调alpha让选中的扇区抬起来。实操心得3D 场景里高亮效果天生比 2D 弱因为扇区本身已经有明暗变化再加一层透明度变化的辨识度不高。我在深色大屏上的做法是给emphasis加一个描边色比如borderColor: #FFFFFF、borderWidth: 2白色描边在深底上非常跳一眼就能看到。4.3 大屏性能与动画调优3D 饼图比 2D 饼图吃性能主要体现在两处一是 WebGL 上下文的初始化和着色器编译二是不停重绘时的 GPU 负担。以下是几个实测有效的压制手段。第一控制扇区数量。前面说了 5 到 8 个为宜。每多一个扇区几何体的顶点数和绘制调用都增加超过 12 个之后帧率下降会很明显。第二关掉不必要的动画。默认的入场动画在 3D 场景里是逐个扇区生长看起来不错但耗时约 1 秒。如果大屏上有多个图表同时加载这 1 秒会让人感觉页面卡。可以缩短。animationDuration: 600, animationEasing: cubicOut如果图表只是在展示不需要交互直接animation: false最省。第三慎开autoRotate。自动旋转意味着每帧都要重算相机矩阵和重新渲染GPU 占用会稳定在高位。我在一个集显工控机上测过1920×1080 全屏、8 个扇区的情况下静止时 GPU 占用约 12%开启自动旋转后升到 45%机身明显发热。所以自动旋转要配合闲置才开的策略。第四容器尺寸别虚高。ECharts 的 canvas 尺寸是按容器 CSS 尺寸乘以devicePixelRatio来的。一个3000px宽的容器在 2 倍屏上就是 6000px 宽的画布显存直接爆。大屏项目务必限制最大宽度或者在超宽屏上用Math.min(width, 2560)手动约束。function getSafeSize(el) { const rect el.getBoundingClientRect(); return { width: Math.min(rect.width, 2560), height: Math.min(rect.height, 1440) }; }第五页面隐藏时暂停渲染。大屏通常是常驻页面浏览器 Tab 切走后如果还在渲染就是纯浪费。监听visibilitychange隐藏时chart.clear()或者干脆不调 resize切回来再恢复。5. 踩坑实录与排查速查表5.1 图表一片空白的排查顺序这是个高频问题我按从最可能到最不可能排了个顺序照着走能覆盖九成情况。第一步看控制台有没有Series pie3D is used but not imported或者Unknown series type。有的话就是 echarts-gl 没引入检查 import 语句或者 CDN 的 script 标签顺序。用打包工具的注意import echarts-gl必须在 echarts 之后而且 echarts-gl 的入口文件依赖 echarts 已经注册到全局。第二步看容器有没有高度。pie3D的容器高度如果是 0 或者被 flex 挤压成 0WebGL 上下文创建不出来控制台会有一个关于 canvas 尺寸的警告。给容器加个明确的height: 100%并且确保父级链路上每一层都有高度。第三步看 WebGL 是否可用。在控制台跑document.createElement(canvas).getContext(webgl)如果返回 null就是设备或浏览器不支持。这种情况只能降级到 2D 饼图或者多层叠影方案。function isWebGLAvailable() { try { const canvas document.createElement(canvas); return !!(window.WebGLRenderingContext (canvas.getContext(webgl) || canvas.getContext(experimental-webgl))); } catch (e) { return false; } } if (isWebGLAvailable()) { chart.setOption(option3D); } else { chart.setOption(option2DFallback); // 降级到普通饼图 }第四步看data是不是空数组或者全是 0。我遇到过接口返回的 value 是字符串435的情况ECharts 对字符串数值的处理有版本差异某些情况下会全部当 0 处理饼图就什么都不画。稳妥做法是在前端做一次Number(d.value)转换并且过滤掉NaN。第五步看有没有多个实例。HMR热更新场景下很容易出现同一个 DOM 上初始化了多个 ECharts 实例旧实例的 canvas 还在新实例画不出来或者画在下面被盖住。加一个实例管理。let chart echarts.getInstanceByDom(dom); if (!chart) { chart echarts.init(dom); }5.2 文字模糊、标签错位与 resize 失效文字模糊的根本原因是 canvas 的 CSS 尺寸和实际像素尺寸不匹配。ECharts 默认会用devicePixelRatio来设置 canvas 的width/height属性和 CSSstyle.width/style.height两者比例正确就清晰。如果你在 CSS 里给 canvas 或者它的容器做了transform: scale()或者zoom比例就乱了。解决方法不要用 CSS transform 缩放图表容器。统一缩放用根字号方案见 3.4 节。如果确实需要整体缩放比如按 1920 设计稿等比缩放到任意屏幕用transform: scale()缩放外层包裹元素并且同步调整echarts.init的宽高参数。const scale Math.min(window.innerWidth / 1920, window.innerHeight / 1080); wrapper.style.transform scale(${scale}); wrapper.style.transformOrigin left top; chart echarts.init(dom, null, { width: 1920, height: 1080, devicePixelRatio: Math.min(window.devicePixelRatio, 2) });这里devicePixelRatio我做了上限 2 的处理。有些 4K 屏的devicePixelRatio是 2 或者更高如果直接透传canvas 像素数会是尺寸的四倍甚至更多显存和填充率都会爆掉帧率暴跌。上限设 2 是清晰度和性能的平衡点肉眼几乎看不出差别。标签错位除了前面说的 3D 投影原因还有一个常见触发点grid或者center配置残留。有些同学是从 2D 饼图代码改过来的series.center: [50%, 50%]没删而 pie3D 对 center 的解析规则略有不同导致标签整体偏了一截。把center删掉用默认值通常最稳。resize失效基本都是监听对象错了前面讲了用ResizeObserver。还有一个坑是chart.resize()在 3D 场景下需要重绘整个 WebGL 场景比 2D 慢如果 resize 触发非常频繁比如拖拽窗口边缘会造成明显卡顿。加个防抖。let resizeTimer null; const ro new ResizeObserver(() { clearTimeout(resizeTimer); resizeTimer setTimeout(() chart.resize(), 120); });5.3 常见问题速查表现象最可能的原因处理方式图表区空白控制台报 unknown seriesecharts-gl 未引入或顺序错误确保import echarts-gl在 echarts 之后有图但看不到厚度viewControl.alpha接近 0调到 35~50饼图像纸片height太小提到 18~30配合 rem 换算扇区缝隙发亮很丑itemStyle.borderWidth过大降到 1颜色改半透明标签飘到奇怪的位置3D 投影导致后排查扇区遮挡用position: inside或关 labelLine 改外部 HTML 图例小扇区点不中角度太小设minAngle: 6并在图例说明tooltip 撑成超宽一条默认white-space: nowrapextraCssText加normalmax-width移动端图表字号没跟着缩放JS 数值不受 postcss 影响写rem()函数逐个换算resize 后图表还是旧的尺寸只监听了 window改用ResizeObserver监听容器高 DPI 屏上文字发虚devicePixelRatio 过高或容器被 transform限制 DPR 上限为 2避免 CSS transform 缩放页面卡顿发热autoRotate 常开 扇区过多闲置才开旋转扇区控制在 8 个内热更新后图不显示同一 DOM 多个实例用getInstanceByDom复用实例我在实际项目里踩得最狠的一次是大屏在客户现场渲染正常回到公司测试机上一片空白。排查了两个小时才发现测试机的浏览器硬件加速被策略关掉了getContext(webgl)直接返回 null。那次之后我就在所有 3D 图表外面套了 WebGL 可用性检测和降级分支代码多写 20 行省下的是现场返工的机票钱。另一个体会是 3D 饼图千万不要硬套在所有场景上。环形图能表达的东西2D 版本在信息传递上永远更准。我在做内部数据报表时会坚持用 2D只有面向外部展示、需要视觉冲击力的大屏才上 3D。判断标准很简单看这张图的读者会不会去精确比较两个扇区的大小。会就用 2D只是要个大致印象用 3D 没问题。