echarts图表渲染失败的三大主因是容器无显式宽高、dom未就绪即初始化、xaxis.data与series.data长度不一致；需确保容器设宽高、init前监听domcontentloaded、数据长度严格匹配。

echarts.init 必须在 DOM 元素已挂载且具备明确宽高后调用，否则图表不渲染或显示为空白 —— 这是新手踩坑率最高的问题。

容器必须有显式宽高，不能靠父级撑开

很多人写 <div id="chart"></div> 后直接 echarts.init，但没设 width 和 height，结果图表区域塌陷、myChart 初始化成功却无内容。

常见错误现象：console.log(myChart) 有实例，但页面空白；检查元素发现 #chart 的 computed height 是 0px。

• 正确做法：用内联样式或 CSS 类确保容器有确定尺寸，例如 <div id="chart" style="width:600px;height:400px;"></div>
• 响应式场景下可只设 width:100%，但 height 仍需固定值（如 400px）或通过父容器 min-height + position:relative 配合子元素绝对定位实现
• 切勿依赖 display:flex 父容器自动撑高——ECharts 不会主动触发重排来读取 flex 布局下的动态高度

CDN 引入比本地文件更稳，优先选 echarts.min.js

本地引入 echarts.js 容易因路径错误（比如误写成 js/echarts.js 而实际在根目录）导致 echarts is not defined 错误，且调试困难。

CDN 方式省去下载、路径管理，加载失败时浏览器控制台报错清晰（如 404），也天然支持多版本回滚。

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

• 推荐链接（2026 年稳定可用）：<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
• 避免使用过时的百度 CDN（echarts.baidu.com 已于 2025 年底逐步停服），也不要用未带版本号的裸 URL（如 echarts@latest），防止意外升级破坏兼容性
• echarts.min.js 比非 min 版本体积小 60%+，首屏加载更快；开发阶段若需断点调试，可临时换为 echarts.js（非压缩版）

setOption 调用前必须确认 DOM 就绪

把 echarts.init 和 setOption 写在 底部看似安全，但如果脚本被标记 async 或放在外部 JS 中，仍可能执行早于 DOM 解析完成。

典型错误：控制台报 Cannot read property 'getAttribute' of null 或 document.getElementById(...) is null。

• 最简保障方式：将初始化代码包裹在 DOMContentLoaded 事件中：

  document.addEventListener('DOMContentLoaded', () => {
    const chartDom = document.getElementById('chart');
    const myChart = echarts.init(chartDom);
    myChart.setOption(option);
  });

• 如果使用模块化构建（如 Webpack/Vite），则无需手动监听，但需确保 init 调用发生在挂载节点已存在之后
• 不要用 window.onload —— 它等所有资源（含图片、字体）加载完才触发，延迟明显

配置项里 xAxis.data 和 series.data 长度必须一致

柱状图/折线图中，横轴类别数与数据点数不匹配，会导致图表渲染异常：部分柱子缺失、坐标轴错位、甚至整个 series 不显示。

例如 xAxis.data 是 ["A","B","C"]（3 项），而 series.data 是 [10,20]（2 项），第三列将无对应数据，但 ECharts 默认不会报错，只静默跳过。

• 调试建议：在调用 setOption 前加校验：

  if (option.xAxis?.data?.length !== option.series?.[0]?.data?.length) {
    console.warn('xAxis.data 与 series.data 长度不一致，图表可能显示异常');
  }

• 动态数据场景下，务必保证前后端返回的数据结构对齐；若后端字段名不统一（如返回 categories 和 values），前端需做一次映射转换
• 注意：ECharts V6 开始对空数组、null 值更敏感，V5 中可能容忍的写法（如 data: []）在 V6 中可能直接中断渲染

真正卡住人的往往不是语法，而是容器尺寸未生效、DOM 未就绪、或数据长度错位这类“看不见的约束”。尤其当多个图表并存、或嵌套在 Vue/React 组件里时，这些条件更容易被忽略。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！