ECharts：超详细部署与使用教程

Apache ECharts 是一个免费、强大的纯 JavaScript 图表与可视化库，基于轻量级 Canvas 渲染库 ZRender 构建，可轻松为商业产品添加直观、交互丰富、高度可定制的图表。它是 Apache 软件基金会顶级项目，也是国内使用最广泛的前端可视化框架之一。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Apache ECharts 是一套面向 Web 的开源可视化图表库，名称来源于「Enterprise Charts」（商业级数据图表）。它起源于百度前端团队（EFE），2018 年毕业成为 Apache 软件基金会顶级项目。ECharts 采用声明式语法（Option 配置项），开发者只需描述「想要什么样的图」，无需关心渲染细节；底层基于自研的轻量级 Canvas 库 ZRender，支持 Canvas 与 SVG 两种渲染器，兼容 PC 与移动端浏览器，广泛用于数据大屏、BI 报表、监控平台、金融行情、运营分析等场景。

1.2 核心功能

• 丰富的图表类型：折线图、柱状图、饼图、散点图、K 线图、雷达图、仪表盘、漏斗图、地图、热力图、关系图、树图、桑基图、平行坐标等数十种基础与高级图表。
• 强大的交互能力：图例开关、数据区域缩放（dataZoom）、视觉映射（visualMap）、提示框（tooltip）、图表联动（connect）、框选/刷选（brush）、图例与图表漫游。
• 动画与渲染：数据更新自动过渡动画；支持 Canvas / SVG 两种渲染器；移动端自动适配。
• 大数据量渲染：适用于十万级数据的散点/热力/线图渲染，配合渐进式渲染与大数据优化。
• 声明式配置：一套 Option 描述整个图表，易学易用；官方提供在线实例编辑器可直接调试。
• 扩展生态：ECharts GL（3D 图、地球、WebGL）、liquidfill 水球图、wordcloud 字符云、百度地图扩展、vue-echarts（Vue 组件）、echarts-stat 统计工具等官方/社区扩展。
• 无障碍与国际化：内置无障碍渲染、多语言支持（以官方文档为准）。

1.3 技术架构

ECharts 官方 Logo：

官方示例库中的折线图（line-simple）与饼图（pie-simple）效果：

技术上，ECharts 自下而上分为三层（依据 README 与官方文档）：

1. 渲染层 ZRender：轻量级 Canvas 库，负责图形元素（group/shape）管理、事件处理、Canvas/SVG 渲染；
2. 组件与图表层：Chart（LineChart、BarChart、PieChart 等）与 Component（GridComponent、TooltipComponent、LegendComponent、DataZoomComponent 等）；
3. 入口与适配层：echarts.init(dom) 创建实例、setOption(option) 声明式更新、事件绑定、坐标系与动画调度。

二、环境要求

普通使用者（网页里插一张图）的门槛极低：一个 HTML 文件 + 一个 <script> 标签即可。只有在「改源码、参与贡献、构建自定义发行版」时才需要 Node.js 环境。

三、部署方式

下面给出四种引入方式：CDN 引入（零构建最快）→ npm 全量引入 → npm 按需引入（生产推荐）→ 源码构建（二次开发）。

3.1 方式一：CDN 引入（最快上手，零构建）

直接在 HTML 中通过 jsDelivr CDN 引入官方脚本（README 推荐的 CDN 地址）：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8" />
  <title>ECharts 快速上手</title>
  <!-- jsDelivr CDN 引入；版本号可换成实际使用版本（当前 6.1.0） -->
  <script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0/dist/echarts.min.js"></script>
</head>
<body>
  <!-- 图表容器：必须显式指定宽高 -->
  <div id="main" style="width: 600px; height: 400px;"></div>
  <script>
    // 1) 基于容器初始化图表实例
    var myChart = echarts.init(document.getElementById('main'));
    // 2) 声明式配置 Option
    var option = {
      title: { text: '一周销量' },
      tooltip: {},
      legend: { data: '销量' },
      xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] },
      yAxis: { type: 'value' },
      series: [{ name: '销量', type: 'line', data: [150, 230, 224, 218, 135, 147, 256] }]
    };
    // 3) 绑定配置，渲染图表
    myChart.setOption(option);
  </script>
</body>
</html>

用浏览器直接打开该 HTML 文件，即可看到与官方示例一致的折线图（数据即官方 line-simple 示例数据）。

CDN 也可换用其他公共镜像（如 unpkg、cdnjs），或下载 echarts.min.js 到本地项目自行托管。

3.2 方式二：npm 全量安装（工程化项目）

# 初始化项目（如已有项目可跳过）
mkdir echarts-demo && cd echarts-demo
npm init -y

# 官方 README 命令：安装 echarts
npm install echarts --save

在 ES Module 工程中全量引入：

import * as echarts from 'echarts';

const myChart = echarts.init(document.getElementById('main'));
myChart.setOption({
  title: { text: '一周销量' },
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] },
  yAxis: { type: 'value' },
  series: [{ type: 'line', data: [150, 230, 224, 218, 135, 147, 256] }]
});

3.3 方式三：npm 按需引入（生产环境推荐）

全量引入包体偏大（完整包约 1MB 级别），生产环境推荐按需引入，配合 Webpack/Vite/Rollup 的 Tree-shaking 剔除未用代码：

import * as echarts from 'echarts/core';
import { LineChart, BarChart, PieChart } from 'echarts/charts';
import {
  TitleComponent,
  TooltipComponent,
  GridComponent,
  LegendComponent
} from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';

// 显式注册本项目用到的图表与组件
echarts.use([LineChart, BarChart, PieChart, TitleComponent, TooltipComponent, GridComponent, LegendComponent, CanvasRenderer]);

const myChart = echarts.init(document.getElementById('main'));
myChart.setOption({
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [150, 230, 224, 218, 135, 147, 256] }]
});

未注册的图表/组件不会打包进产物，也不会渲染；如运行时控制台提示「xxx is not registered」，即漏注册了对应 Chart 或 Component。

3.4 方式四：源码构建（二次开发 / 贡献代码）

需要先安装 Node.js（README 要求）：

git clone https://github.com/apache/echarts.git
cd echarts

# 安装依赖
npm install

# 开发模式：watch 源码变化，自动构建并打开 ./test 目录（可打开 -cases.html 查看全部用例）
npm run dev

# 校验 TypeScript 类型正确性
npm run checktype

# 构建全部生产产物（输出到 dist/ 目录）
npm run release

构建完成后，产物在 dist/ 目录（如 dist/echarts.min.js），可直接在页面引用。

3.5 验证部署成功（通用）

1. CDN 方式：浏览器打开 HTML，F12 Console 无报错，页面出现折线图；
2. npm 方式：npm run dev 启动后访问页面，图表正常渲染；
3. 快速自检代码：

// 控制台执行：打印版本号，确认引入成功
console.log(echarts.version);   // 期望输出类似 "6.1.0"

四、使用方法

4.1 基础用法：一个完整的饼图（官方 pie-simple 示例）

var myChart = echarts.init(document.getElementById('main'));
var option = {
  title: { text: '网站访问来源', subtext: '示例数据', left: 'center' },
  tooltip: { trigger: 'item' },
  legend: { orient: 'vertical', left: 'left' },
  series: [{
    name: '访问来源',
    type: 'pie',
    radius: '50%',
    data: [
      { value: 1048, name: '搜索引擎' },
      { value: 735, name: '直接访问' },
      { value: 580, name: '邮件营销' },
      { value: 484, name: '联盟广告' },
      { value: 300, name: '视频广告' }
    ],
    emphasis: { itemStyle: { shadowBlur: 10, shadowOffsetX: 0, shadowColor: 'rgba(0, 0, 0, 0.5)' } }
  }]
};
myChart.setOption(option);

4.2 常用 API

// 响应式：窗口尺寸变化时自动重绘
window.addEventListener('resize', function () {
  myChart.resize();
});

// 点击柱子时获取数据
myChart.on('click', function (params) {
  console.log('点击了:', params.name, params.value);
});

4.3 进阶功能

• 图表联动：echarts.connect([chart1, chart2]) 让多个图表共享 tooltip 与缩放状态，常用于大屏多视图联动。
• 数据集（dataset）：option.dataset 声明数据与维度映射，便于多系列复用同一份数据。
• 视觉编码：visualMap 组件将数值映射到颜色/尺寸渐变，做热力图、气泡图。
• 主题定制：echarts.init(dom, 'dark') 使用内置主题；也可通过官方主题编辑器下载自定义 .js 主题后 import 注册。
• 数据区域缩放（dataZoom）：大数据时间轴必备，示例：

javascript option = { xAxis: { type: 'category', data: months }, yAxis: { type: 'value' }, dataZoom: [ { type: 'inside' }, // 鼠标滚轮缩放 { type: 'slider' } // 底部滑动条 ], series: [{ type: 'line', data: values }] };

• 服务端渲染（SSR）：Node 环境可用 SSRRenderer（以官方文档为准）输出 SVG 字符串。
• 扩展生态：ECharts GL（3D 柱状/地球）、liquidfill 水球图、wordcloud 字符云、百度地图扩展、vue-echarts（Vue 2/3 组件）、echarts-stat 统计回归。
• 地图与地理可视化：配合 GeoJSON 注册地图（echarts.registerMap）实现行政区划图（官方示例库提供 choropleth 示例）。

4.4 适用场景

• 企业数据大屏、BI 报表与运营监控面板；
• 金融行情（K 线、分时、买卖点）；
• 后台管理系统的数据统计图表；
• 地理信息可视化（行政区划、迁徙、热力）；
• 移动端 H5 数据页、可视化报告；
• 需要图表联动/钻取的复杂可视化应用。

五、常见问题排查（FAQ）

Q1：页面空白，控制台报 echarts is not defined - 原因：CDN 脚本未加载成功（网络问题/路径错误）或 echarts.min.js 放错了位置。 - 解决：确认 <script src> 可访问；Network 面板查看是否 200；改用本地下载的 echarts.min.js 自托管。

Q2：图表容器高度为 0，图渲染不出来 - 原因：容器 div 没有显式宽高（ECharts 不会撑开父容器）。 - 解决：给容器设置 width/height（CSS 或内联），或确保父级有确定尺寸。

Q3：窗口缩放后图表变形/不全 - 原因：未监听 resize 重绘。 - 解决：window.addEventListener('resize', () => myChart.resize())。

Q4：按需引入后控制台报 Component series.xxx is not used - 原因：用了某图表/组件但未 echarts.use([...]) 注册。 - 解决：按提示补注册对应 Chart（如 BarChart）或 Component（如 DataZoomComponent）。

Q5：npm 安装后 import * as echarts from 'echarts' 包体太大 - 原因：全量引入。 - 解决：改用 3.3 节的 echarts/core 按需引入；用 webpack-bundle-analyzer 检查产物。

Q6：Vue/React 中图表在路由切换后不渲染或残留 - 原因：组件卸载时未 dispose，DOM 复用导致初始化到已销毁容器。 - 解决：组件 beforeDestroy/useEffect cleanup 中调用 myChart.dispose()，挂载时重新 init。

Q7：数据量大（几万点）时图表卡顿 - 解决：① 开启 dataZoom 渐进式渲染；② 用 large: true 大数据优化（散点/线图）；③ 降级为 SVG 渲染器（小数据量）或 Canvas（大数据量）；④ 服务端预聚合。

Q8：build 时报 TypeScript 类型错误 / 找不到模块声明 - 解决：ECharts 自带 TS 类型声明；升级到与 echarts 版本匹配的 TS 配置；确认 moduleResolution 正常。

六、部署注意事项与最佳实践

1. 生产环境用按需引入 + 固定版本号：npm install echarts@6.1.0 --save 锁定版本，避免 ^ 自动升级带来的不兼容；Tree-shaking 减小包体。
2. 容器尺寸契约：ECharts 要求容器有确定宽高，响应式布局务必监听 resize 并调用 chart.resize()。
3. 及时销毁实例：SPA 路由切换时 dispose()，避免内存泄漏与 canvas 残留。
4. CDN 与自托管权衡：公网演示可用 CDN；内网/政企项目建议下载 echarts.min.js 自托管，避免 CDN 故障。
5. 主题统一：企业级项目建议统一沉淀一套自定义主题（通过官方主题编辑器），避免每个图表单独配色。
6. 数据更新用增量 setOption：频繁刷新时用 setOption(newOption) 增量合并，配合动画过渡；不必每次 dispose 重建。
7. 无障碍：重要数据页建议开启 aria 相关配置（以官方文档为准）。
8. 版本升级先读迁移文档：5.x → 6.x 有配置项废弃/变更，升级前查阅官方升级日志与 Option 手册。

工程化提示：Vue 项目推荐直接使用官方维护的 vue-echarts 组件；React 项目可参考社区封装。CDN 引入时务必在 URL 中锁定版本号（如 echarts@6.1.0），避免 CDN 自动升级带来的页面变更。

七、参考资料

• GitHub 仓库：https://github.com/apache/echarts
• 中文官网：https://echarts.apache.org/zh/index.html
• 快速上手（Handbook）：https://echarts.apache.org/handbook/zh/get-started/
• API 文档：https://echarts.apache.org/api.html
• Option 配置项手册：https://echarts.apache.org/option.html
• 官方示例集合：https://echarts.apache.org/examples/zh/
• 下载页：https://echarts.apache.org/zh/download.html
• jsDelivr CDN：https://www.jsdelivr.com/package/npm/echarts
• npm 页面：https://www.npmjs.com/package/echarts
• Vue 组件 vue-echarts：https://github.com/ecomfe/vue-echarts
• 扩展合集 Awesome ECharts：https://github.com/ecomfe/awesome-echarts
• Release 下载：https://github.com/apache/echarts/releases