组里一个刚接手可视化模块的同事上周发来一段录屏，画面里的柱状图鼠标一划过去，被悬停的那根柱子还在，其余几根像被人按了隐身键一样直接淡出画布。他反复确认了三遍数据源，甚至把series.data打印到控制台一个一个核对，愣是没找到问题。这类问题在 echarts 柱状图 hover 场景里其实非常高频，症状相似但成因天差地别，表现出来都是"柱子不隐藏"这个诉求的反面——柱子该在的时候不见了。我做可视化这块前后也有几年，光是这个现象就见过至少五种不同的来源：有的改一行配置就解决，有的得把主题文件翻出来重写。下面我把这套排查思路完整铺开，从渲染机制到具体配置项，再到可以直接抄走的修复模板，尽量让不管刚上手还是已经写了大半年图表的同学都能对号入座。

1. 先把"柱子消失"这件事拆开看

1.1 hover 时 echarts 到底动了哪几层样式

很多人第一反应是"柱子被删了"，其实 canvas 上的图形一直在那儿，只是它的绘制属性被切换了。echarts 5 之后把图形状态拆成了四套：normal（常态）、emphasis（高亮）、blur（淡出）、select（选中）。鼠标进入某个数据项时，图表实例内部会派发一个高亮动作，把目标元素切到emphasis状态，同时按emphasis.focus和emphasis.blurScope的设置，把周围元素切到blur状态。所以你在屏幕上看到的"消失"，绝大多数是blur状态里的opacity被压低了，而不是图形真的没了。

理解这个分层之后，排查方向立刻就清晰了：如果你是"被悬停的那根不见了"，问题在emphasis.itemStyle；如果是"其余几根不见了"，问题在blur；如果是"整片区域都灰掉"，那是blurScope的范围设得太大了。我见过最离谱的一次，是有同学在主题里写了blur: { itemStyle: { color: 'transparent' } }，结果所有非高亮柱子直接变成完全透明，看起来就跟删掉一样，调试半天以为是数据问题。

这里有个很重要的前提认知：emphasis、blur这些状态并不是只有主题能设，series级别、全局option级别都能设，而且优先级是series> 主题 > 默认。当项目里同时存在自定义主题文件和组件内联配置时，很容易出现"我明明没写这个，它为什么变淡了"的困惑。遇到这种情况，先别急着改代码，把chart.getOption()打出来看一眼最终合并结果，比盲猜高效得多。

1.2 三类"消失"现场的分辨方法

我习惯按观察到的现象分三类，每类对应完全不同的排查路径，这个分类帮我省过很多时间。

第一类是兄弟柱子变淡。悬停某根柱子，同一坐标系内其他柱子透明度明显降低，但坐标轴、网格线、标签都正常。这类九成以上是emphasis.focus被设成了'series'或'self'。第二类是被悬停的柱子本身变淡或消失。鼠标移上去那一刻柱子自己没了，移开又回来。这类要看emphasis.itemStyle里是不是写了opacity: 0或者颜色被覆盖成了背景色。第三类是柱子被盖住。图形其实还在，颜色也正常，但视觉上被一层半透明的遮罩盖住了。这类多半是tooltip.axisPointer.type设成了'shadow'，或者showBackground的背景色和柱子颜色撞了。

提示：判断"真消失"还是"被遮挡"，把图表容器截图后用取色器点一下就能确认。如果是遮挡，柱子边缘色值是背景色和柱子色的混合；如果是透明度变化，色值会向容器背景色靠拢但保留色相偏移。

这个分类还有个衍生价值：它能帮你判断问题是不是可复现的。blur类问题在任何数据、任何尺寸下都稳定复现；遮挡类问题往往跟容器尺寸、tooltip内容长度有关，换个屏幕就变了；而样式覆盖类问题可能只在某个数据区间出现，比如负值柱子、零值柱子。我一般会先把数据换成一组固定的测试值（五根正数、一根零、一根负数），在这组数据上做排查，把变量控制住。

2. 头号元凶：emphasis.focus 触发的 blur 状态

2.1 focus 的三个取值，影响面完全不同

emphasis.focus有三个取值，很多人知道有这个东西但没细究过它们的差别，这恰恰是问题源头。'none'是默认值，表示不改变其他元素的样式，悬停谁就只高亮谁，其他柱子纹丝不动。'self'表示把同一坐标系内除当前元素外的其他数据项切成blur状态。'series'表示把除当前系列外的其他系列切成blur状态——注意这里粒度是系列不是数据项，单系列柱状图里设'series'几乎没效果，多系列分组柱状图里才会看到整组整组地变淡。

问题就出在这个默认值上。echarts 官方默认是'none'，但很多团队的主题文件、内部组件库、甚至某些第三方图表封装，为了让悬停效果更"聚焦"，会在主题里统一写emphasis: { focus: 'series' }。这套配置在饼图、折线图上效果确实不错，但放到单系列柱状图上，一旦有blurScope: 'global'配合，整个画布除了当前柱子全部变淡，视觉冲击特别强烈，用户第一反应就是"柱子没了"。

blurScope这个属性值得单独说一句，它控制blur状态的作用范围，取值有'coordinateSystem'（默认，只在当前坐标系内生效）、'series'（只在当前系列内）、'global'（全图表生效）。这三个值跟focus是组合生效的，focus: 'self'加blurScope: 'coordinateSystem'是局部变淡，focus: 'self'加blurScope: 'global'就是全场变淡。我排查时习惯把这两个属性一起看，因为它们经常是被同一个封装层一次性写进去的，改一个不改另一个还会残留奇怪的效果。

2.2 最小改动修复：把 blur 的透明度拉回来

如果你的诉求是"保留焦点效果但别让柱子淡到看不见"，最直接的改法是显式覆盖blur状态的透明度。默认blur状态下图形会被压到很低的透明度，具体数值跟主题有关，视觉上确实接近消失。把它拉回到一个仍然能被看清的值，问题立刻缓解：

series: [{ type: 'bar', data: [120, 200, 150, 80, 70, 110], emphasis: { focus: 'self', blurScope: 'coordinateSystem', itemStyle: { // 高亮项保持完全不透明 opacity: 1 } }, blur: { itemStyle: { // 关键：把默认被压低的透明度拉回来 opacity: 0.6 } } }]

这段配置的意图很明确：高亮项保持 1，其余项给 0.6，既保留了"当前项更突出"的层级感，又不至于让其他柱子淡到看不出轮廓。0.6 这个值不是拍脑袋来的，我实测过 0.4、0.5、0.6、0.7 四档，0.4 以下在浅色主题里依然接近隐形，0.7 以上又和常态区分度不够，0.6 是个比较稳的中间值。如果你用的是深色主题，可以往 0.65 到 0.7 调，深色背景下同样的透明度视觉上会显得更暗。

注意：blur.itemStyle.opacity只对柱体本身生效，柱子上方的标签（label）在blur状态下有独立的透明度控制。如果发现柱子回来了但数字标签还是淡的，需要补上blur: { label: { opacity: 1 } }，两处得一起改。

2.3 想在保留焦点效果的同时不"消失"的折中做法

有些业务场景确实需要"聚焦"的视觉效果，比如大屏看板上鼠标划过某一项时希望它跳出来。这种时候完全关掉focus反而损失了交互价值，我更推荐用亮度或者描边来做区分，而不是靠透明度。具体做法是让blur状态的柱子保持不透明，但降低饱和度，同时给emphasis状态加一圈描边：

series: [{ type: 'bar', emphasis: { focus: 'self', itemStyle: { opacity: 1, borderColor: '#2b6cb0', borderWidth: 2, shadowBlur: 8, shadowColor: 'rgba(0, 0, 0, 0.15)' } }, blur: { itemStyle: { opacity: 1, color: 'rgba(140, 150, 165, 0.85)' } } }]

这套方案的核心思路是"用颜色区分，不用透明度区分"。所有柱子都保持实心，非高亮的那几根统一换成低饱和的灰蓝色，高亮那根保持原色并加描边和阴影。好处是视觉上没有任何元素"消失"，色块面积不变，用户对数据的整体感知不会被打断。我在一个需要同时对比五六根柱子的看板项目里用过这个方案，反馈比透明度方案好不少。

不过这个方案有个前提：blur.itemStyle.color一旦写死成固定色值，原本用来区分系列的调色板就失效了。如果是多系列图表，得给每个系列单独写，或者干脆放弃这个方案，改用 2.2 里的透明度微调。这也是我一直强调"没有万能配置"的原因，得先看清自己的图表结构再选方案。

3. 第二类原因：emphasis 样式本身覆盖掉了柱子

3.1 itemStyle 与 emphasis.itemStyle 的继承与覆盖规则

第二个高频来源是被悬停的那根柱子自己出问题。这里得先讲清楚itemStyle和emphasis.itemStyle的合并逻辑：它们不是简单的整体替换，而是属性级别的浅合并。也就是说emphasis.itemStyle里没写的属性会从itemStyle继承，写了的会覆盖。这个规则听起来很合理，但坑就坑在"没写"和"写了 undefined"是两回事，以及某些属性在emphasis状态下有内置的默认值。

举个实际遇到的例子。有个项目里柱子的常态样式是itemStyle: { color: '#4a90d9', opacity: 0.9 }，然后在emphasis.itemStyle里只写了color: '#f5a623'，没写opacity。按继承规则应该继承 0.9 才对，但实际表现是高亮时柱子变得几乎看不见。后来定位到是主题文件里在全局emphasis层写了opacity: 0.3，这个全局配置参与了合并，把继承链打断了。这类问题的隐蔽性在于：单个组件的代码看起来完全正确，问题藏在几十行之外的全局配置里。

我现在的习惯是，只要遇到样式异常，第一件事就是把chart.getOption()的结果打印出来，直接看series[0].emphasis里到底有哪些属性被塞进来了。这个方法比翻代码快十倍，因为它是运行时合并后的真实结果，主题、全局配置、setOption多次调用的影响全都在里面。

3.2 透明度、描边、颜色三处最容易踩的坑

opacity是第一号嫌疑人。除了上面说的继承被截断的情况，还有一种更隐蔽的写法：用rgba颜色代替opacity。color: 'rgba(74, 144, 217, 0.2)'这种写法在emphasis里出现时，柱子的透明度是写死在颜色里的，itemStyle.opacity设成 1 也救不回来。我排查过一个案例，同事在主题里用rgba做了一整套渐变色，高亮色不小心写成了alpha: 0.15，视觉上就是柱子直接没了。所以我的建议是颜色和透明度分开控制，颜色用hex或纯色，透明度统一走opacity。

borderWidth和borderColor是第二号。有些主题为了做"描边高亮"，在emphasis里写了borderWidth: 3，但borderColor用了跟背景色接近的浅灰。柱子的填充色被边框覆盖掉一部分，如果柱子本身宽度不大（比如 12px、16px），左右各 3px 的边框直接把填充区挤没了，看起来就是个灰框或者什么都没有。这种情况在小尺寸图表、移动端、以及设置了barWidth的窄柱子里特别常见。

第三号是color被设成'transparent'或者跟画布背景完全一致。这种通常是从别的主题文件复制配置时带过来的，或者是设计稿里的"高亮反白"效果被误解成了透明。定位方法很简单：在浏览器开发者工具里用取色器点一下高亮时的柱子位置，如果取到的是画布背景色，基本可以确认是被设成透明或者同色了。

我的经验是，emphasis里尽量只写颜色和描边这类"加法"属性，少碰opacity和color的透明变体。加法属性出问题最多是效果不明显，透明类属性出问题是直接看不见，排查成本完全不是一个量级。

4. 第三类原因：图层与遮罩造成的"假消失"

4.1 axisPointer 的 shadow 与 line 两种模式

排除了上面两类，剩下的多半是"柱子还在但被盖住了"。最常见的元凶是tooltip.axisPointer。这个属性控制悬停时坐标轴指示器的样式，type有三种取值：'line'画一条竖线，'shadow'画一块矩形色块覆盖当前类目区域，'none'什么都不画。'shadow'模式在很多官方示例里的默认观感很好，因为它能给类目一个整体的高亮背景，但如果shadowStyle.color设成了半透明深色，而柱子颜色又偏暗，视觉上柱子就被压暗了，尤其在深色背景的图表里，效果接近"柱子被吃掉"。

我遇到过一个特别典型的场景：图表用了深蓝底配亮蓝柱子，axisPointer.type是'shadow'，shadowStyle.color用了rgba(0, 0, 0, 0.35)。悬停时整块类目区域变暗，亮蓝柱子的对比度被拉低，用户反馈"鼠标一放上去柱子就没了"。实际把shadowStyle.color改成rgba(255, 255, 255, 0.08)之后，问题完全消失，柱子甚至因为背景略亮而更突出了。这种问题不看代码根本猜不到，因为从数据到系列配置全是正常的。

tooltip: { trigger: 'axis', axisPointer: { type: 'shadow', shadowStyle: { // 深色图表里用浅色遮罩，别用深色 color: 'rgba(255, 255, 255, 0.06)' } } }

这条经验我是这么总结的：遮罩色的明暗方向要和画布背景相反。浅色背景用略深的遮罩（rgba(0,0,0,0.05)到0.08），深色背景用略亮的遮罩（rgba(255,255,255,0.05)到0.08），透明度都不宜超过 0.1。超过这个量级，遮罩就会开始干扰图形本身的观感，柱状图这种大面积填充的图形尤其敏感。

4.2 背景条、柱宽、类目间距的视觉陷阱

showBackground这个属性也常被忽略。打开之后每根柱子后面会有一条满高的背景条，backgroundStyle.color默认是浅灰。正常情况这没什么问题，但如果背景条颜色和柱子颜色接近，或者背景条透明度很低但柱子本身透明度也调过，两者叠加就糊成一片。更麻烦的是showBackground在blur状态下也参与渲染，非高亮的柱子变淡之后，背后的背景条反而更显眼，视觉上就成了"柱子变成了背景条"。

barWidth和barCategoryGap的组合也会制造消失的错觉。类目间距设得很大（比如barCategoryGap: '60%'），柱子又设了固定宽度很小，视觉上柱子就是一根细线。这时候配上 hover 时加粗的描边，描边宽度接近柱宽，填充色就被边框完全挤压掉了。这类问题在响应式图表里特别容易出现，因为宽度是按容器百分比算的，大屏上正常，缩小到手机尺寸就全乱。

还有一种情况是stack堆叠配合emphasis.focus: 'series'。堆叠柱状图里同一个类目下的多段柱子属于不同系列，focus: 'series'会把非当前系列的全部切到blur，视觉上整根柱子只剩一段是亮的，其余段变淡，看起来就像柱子"缺了一截"。这个现象跟 2.1 说的是同一个机制，但在堆叠场景下的表现完全不一样，很容易被误判成渲染 bug。

快速验证是不是遮挡类问题：把tooltip.axisPointer.type临时改成'none'，把showBackground临时关掉，把barWidth临时写死成30。如果这三个动作做完问题消失，那就是遮挡类；如果还在，回到第 2、3 节继续查。

5. 一套可复用的五步定位流程

5.1 从控制台到手写最小 demo 的剥离法

排查这类问题我有一套固定流程，第一步永远是"剥离"。把出问题的图表代码从项目里抽出来，放到一个只有 echarts 容器、option对象和setOption的最小 HTML 文件里，数据用固定的测试数组，不引用任何主题文件、不引入任何内部组件库。这一步花不了五分钟，但能砍掉 80% 的干扰变量。

剥离之后先跑一次。如果问题消失了，说明是环境引入的——主题、全局配置、样式覆盖、多次setOption的残留，一个一个加回去，加到哪个问题复现，元凶就找到了。这个方法听起来笨，但在大型项目里是最靠谱的，因为图表配置的合并层级太深，靠读代码推测容易漏。

如果剥离之后问题依然存在，那就是option本身的问题，进入第二步：逐个注释。先注释emphasis整块，看是否恢复；再注释blur整块；再注释tooltip.axisPointer；最后注释showBackground。每次只注释一块，观察变化。这个顺序不是随便排的，是我按历史出现频率排的，emphasis系的问题占了我遇到的大约六成。

第三步是用getOption()做交叉验证。这里有个细节要注意：getOption()返回的是合并后的配置，但它返回的emphasis对象可能跟你写的不完全一样，因为内部会补默认值。我一般会把它JSON.stringify之后扔到控制台，按series[0]展开看。如果看到emphasis.focus是'series'而你代码里根本没写，那就锁定是主题或者封装层加的了。

第四步是手动派发动作。echarts 提供了dispatchAction，可以直接触发高亮。用chart.dispatchAction({ type: 'highlight', seriesIndex: 0, dataIndex: 2 })把第三根柱子强制高亮，然后观察效果。这个动作绕过了鼠标事件，能排除掉事件绑定层面的干扰。如果手动高亮正常、鼠标悬停异常，那问题在事件或者tooltip的触发逻辑上，不在样式上。

第五步是版本对照。echarts 5 的大版本里，emphasis、blur这些状态的处理逻辑有细微调整，不同小版本之间的默认值也可能不同。我手上就有一个项目，4.x 升级到 5.x 之后，原本正常的悬停效果突然出现大面积变淡，原因是 5.x 对blurScope的默认值做了改动。遇到"升级后才出现"的问题，直接查版本变更说明比猜快得多。

5.2 用 getOption 与事件面板做交叉验证

getOption()之外，我还习惯开一个事件监听面板，把mouseover、mouseout、highlight、downplay这几个事件都监听上，console.log打出来看触发顺序和参数。有一次排查一个"悬停后部分柱子永久消失"的诡异问题，就是靠这个面板发现mouseout事件没被正常触发，导致blur状态没被还原，柱子一直卡在淡出状态。根因是容器上绑了一个mouseleave的监听，把事件冒泡拦掉了。

这种"状态卡死"的问题其实不少见，尤其在图表被放进弹窗、Tab 切换、或者带过渡动画的容器里时。表现是鼠标移开之后柱子还是淡的，或者鼠标快速划过时部分柱子保持在blur状态。遇到这种情况，可以在容器的显示切换回调里手动调用一次chart.dispatchAction({ type: 'downplay' })，强制清掉所有高亮和淡出状态。

// 容器显隐切换后强制复位状态 function resetChartState(chart) { chart.dispatchAction({ type: 'downplay' }); chart.dispatchAction({ type: 'hideTip' }); } // Tab 切换、弹窗打开等场景调用 tabChangeHandler(() => { resetChartState(myChart); myChart.resize(); });

resize()这一步也别省。图表在隐藏容器里初始化时尺寸是 0，重新显示后如果没resize，柱宽计算会基于错误尺寸，可能算出极窄的柱子，视觉上也是"消失"。这个问题在弹窗里特别常见，我自己就踩过，查了半天样式，最后发现是resize漏了。

6. 实操心得与常见问题速查

6.1 那些文档里没写、但总在项目里冒出来的坑

第一个坑是主题文件的全局配置优先级比你想象的高。很多人以为组件里写的series配置一定能覆盖主题，实际上主题里的emphasis是写在全局层的，如果series里没显式写emphasis，全局的就会生效。而setOption的第二个参数notMerge默认是false，多次调用会做合并，历史配置可能残留。我现在的做法是，只要涉及状态样式的调试，setOption一律传{ notMerge: true }，把残留因素彻底排除。

第二个坑是同一页面多图表实例共享主题配置。通过echarts.registerTheme注册的主题是全局的，A 图表改成深色主题，B 图表如果没重新init，样式也会跟着变。这个现象在多图表看板里很常见，表现为"只改了一个图，另一个图也跟着坏了"。解决办法是每个图表init时显式传主题名，或者干脆不用全局主题，把配置直接写进各自的option。

第三个坑是**dataZoom与blur的交互**。图表带缩放条时，如果缩放到只剩一两个类目，emphasis.focus: 'self'的blur范围计算可能出问题，非高亮项没有可淡出的对象，会表现为当前柱子跟着一起淡。这个属于边界情况，但看板场景下用户经常缩放到很小范围，很容易撞上。规避方式是在dataZoom的zoom事件里判断当前可见类目数，少于 3 个时临时把focus改回'none'。

第四个坑是**label的position与柱宽冲突**。label.position: 'inside'在柱宽较小时文字会溢出，配上 hover 时emphasis.label.fontSize变大的设置，文字可能把整根柱子盖住。视觉上就是柱子被一片文字糊掉了，看着像消失。这种情况把label.position改成'top'或者在emphasis.label里别动fontSize就能解决。

第五个坑是负值柱子的方向。数据里有负数时，柱子在零轴下方绘制，emphasis的阴影、描边方向如果按正值写（比如shadowOffsetY: -4），阴影会往上飘盖住柱体。这类问题只在特定数据下出现，测试时容易漏，建议在开发阶段就用一组包含正负值的数据跑一遍。

6.2 常见现象对照表与最终配置模板

下面这张表是我这几年攒下来的，基本覆盖了柱状图 hover 时"消失"的常见成因，排查时从上往下对一遍，命中率挺高。

最后给一份我目前项目里在用的基准配置，单系列和多系列都适用，核心思路是"关掉聚焦、保留轻微高亮、手动控制淡出透明度"。这份配置在浅色和深色主题下都验证过，没有出现柱子消失的情况。

const baseBarOption = { tooltip: { trigger: 'axis', axisPointer: { type: 'shadow', shadowStyle: { color: 'rgba(120, 140, 170, 0.06)' } } }, grid: { left: 48, right: 24, top: 32, bottom: 40, containLabel: true }, xAxis: { type: 'category', data: ['一月', '二月', '三月', '四月', '五月', '六月'], axisTick: { alignWithLabel: true } }, yAxis: { type: 'value' }, series: [{ name: '样本量', type: 'bar', barWidth: '42%', data: [120, 200, 150, 80, 70, 110], itemStyle: { color: '#4a7fd4', borderRadius: [4, 4, 0, 0] }, emphasis: { // 关键一：不做聚焦，避免兄弟柱变淡 focus: 'none', itemStyle: { // 关键二：高亮项保持完全不透明 opacity: 1, color: '#2f5fa8', shadowBlur: 10, shadowColor: 'rgba(47, 95, 168, 0.25)' }, label: { opacity: 1 } }, blur: { itemStyle: { opacity: 0.85 }, label: { opacity: 0.85 } }, label: { show: true, position: 'top', color: '#5a6478', fontSize: 12 } }] };

这份配置里我特意把blur的透明度留在 0.85 而不是 0.6，原因是focus: 'none'之后，blur状态其实很少被触发，只有手动调用dispatchAction做联动高亮时才会用到。留一个接近不透明的值，等于给后续的联动功能留了余量，即使哪天真触发了也不会出现"柱子消失"的惊吓。

联动场景下还有个小技巧值得分享。多个图表之间做 hover 联动时，dispatchAction({ type: 'highlight' })会把目标图表里对应的柱子切到emphasis，同时按该图表自己的focus设置处理其他柱子。如果各图表的focus设置不一致，联动效果就会很跳——一个图里其他柱子正常，另一个图里全淡掉了。我现在的做法是给所有参与联动的图表统一注入同一套emphasis和blur配置，抽成一个函数在setOption前合并进去，从源头保证一致。

这套排查思路我用了挺长时间，最大的体会是：柱状图 hover 出问题，九成不是数据的事，也不是 echarts 的 bug，而是状态样式在某个你没想到的层级被改过。把emphasis、blur、blurScope这三个概念吃透，再配上getOption()这个"透视镜"，绝大多数情况十分钟内就能定位。剩下那一成，多半是遮挡和状态复位的问题，把axisPointer、showBackground和downplay这三处过一遍，基本也就收工了。