Skip to content
环境准备：Node.js 与项目初始化
ECharts 通过 npm 分发，安装前需要 Node.js 运行时。到 Node.js 官网 下载对应系统的 LTS 版本，或使用系统包管理器安装。完成后在终端验证：
bash
node -v
npm -vECharts 对 Node.js 版本没有严格要求，任意较新版本均可。随后创建项目目录：
bash
mkdir echarts-demo
cd echarts-demo
npm init -y-y 跳过交互式提问，直接生成 package.json。此时项目环境已就绪。
安装 ECharts
在项目根目录执行：
bash
npm install echarts该命令将 ECharts 安装到 node_modules，并自动写入 package.json 的 dependencies 字段。安装完成后可在 node_modules/echarts/dist/ 下看到多个构建产物：
echarts.js— 完整版（UMD）echarts.esm.js— ES module 版本echarts.common.js— 常用组件版- 按需引入所需的
echarts/core、echarts/charts、echarts/components等模块
要确认实际安装的版本，执行：
bash
npm list echarts或直接查看 node_modules/echarts/package.json 中的 version 字段。
引入方式：import 与 require
ECharts 支持 ES module 和 CommonJS 两种引入方式，功能上没有差异，取决于项目的模块系统。
ES module（推荐）。适用于使用 webpack、Vite 等打包工具的现代前端项目：
javascript
import * as echarts from 'echarts';如果关注打包体积，可按需引入：
javascript
import { init, use } from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { CanvasRenderer } from 'echarts/renderers';
import {
GridComponent,
TooltipComponent
} from 'echarts/components';
use([BarChart, CanvasRenderer, GridComponent, TooltipComponent]);按需引入需要显式注册所用的图表类型和组件，未注册的部分在运行时不会生效。
CommonJS。适用于 Node.js 环境或仍使用 require 的旧项目：
javascript
const echarts = require('echarts');在浏览器中渲染第一个图表
ECharts 的浏览器端渲染依赖一个具有明确宽高的 DOM 容器。
HTML 结构：
html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
</head>
<body>
<div id="main" style="width: 600px; height: 400px;"></div>
</body>
</html>容器宽高必须通过行内样式或 CSS 指定，不得为 0 或 auto——echarts.init 在创建实例时读取容器尺寸，尺寸无效会导致渲染空白。
JavaScript 入口文件（以 ES module 方式引入）：
javascript
import * as echarts from 'echarts';
const dom = document.getElementById('main');
const chart = echarts.init(dom);
const option = {
xAxis: {
type: 'category',
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']
},
yAxis: {
type: 'value'
},
series: [
{
type: 'bar',
data: [120, 200, 150, 80, 70]
}
]
};
chart.setOption(option);这段代码的执行流程：
echarts.init(dom)在指定容器内创建图表实例，并读取容器的像素尺寸。option对象描述图表配置：xAxis定义横轴为类别轴并给出五组标签，yAxis定义纵轴为数值轴，series中声明一个柱状系列及五组数值。setOption(option)将配置传入实例，完成渲染。页面应显示五根高度与数据对应的柱子。
xAxis、yAxis、series 三者构成一个最小可用的直角坐标系图表配置，没有额外的组件依赖。
容器尺寸与异步渲染
echarts.init 在调用时读取容器尺寸。如果此时容器不可见（display: none）或尺寸为 0，实例无法确定绘图区域，后续 setOption 也不会产生可见输出。常见触发场景：
- 脚本在
<head>中执行，DOM 尚未渲染。 - 容器位于选项卡或折叠面板中，初始化时处于隐藏状态。
- CSS 使用
height: 100%，但父元素高度未明确设置。
可靠的解决方式是保证脚本执行时容器已参与布局且具有明确的像素尺寸。
在异步获取数据的场景中，如果数据到达时容器尺寸可能已发生变化（例如用户切换了选项卡），应在数据就绪后先调用 chart.resize() 再执行 setOption。
图表实例不会自动监听窗口尺寸变化。如需图表跟随窗口缩放，应在 window 的 resize 事件中调用 chart.resize()。未处理时，容器宽度改变但画布保持旧尺寸，表现为图表变形或留白。
进阶：Node.js 服务端渲染静态图表
ECharts 可在 Node.js 环境中生成静态图片，需要配合 node-canvas 提供 Canvas 实现。
安装依赖：
bash
npm install canvas示例脚本：
javascript
const echarts = require('echarts');
const { createCanvas } = require('canvas');
const canvas = createCanvas(800, 500);
const chart = echarts.init(canvas);
chart.setOption({
xAxis: { type: 'category', data: ['A', 'B', 'C'] },
yAxis: { type: 'value' },
series: [{ type: 'bar', data: [30, 50, 20] }]
});
const buffer = canvas.toBuffer('image/png');echarts.init 接收 canvas 对象后，使用方式与浏览器端一致。区别在于 Node.js 没有浏览器的自动渲染机制，需要显式通过 canvas.toBuffer() 导出图像数据，随后可写入文件或返回给 HTTP 响应。
注意点：
echarts.setPlatform在不同版本中行为有差异。部分较高版本已在内部处理 node-canvas 的适配，可直接使用echarts.init(canvas)。如果遇到Not implemented错误，可尝试require('echarts/node')或查阅对应版本的官方文档。
node-canvas 的编译依赖系统级的 Cairo 库，不同操作系统的安装方式不同，运行前需确保编译通过。
渲染结果验证与排错
渲染成功的判定：页面中显示柱状图，柱子高度与数据对应，控制台无 ECharts 报错。
常见错误及排查方向：
| 现象 | 原因 | 检查点 |
|---|---|---|
空白页，控制台报 dom should be a valid element | echarts.init 传入 null | 确认 getElementById 的 id 与 HTML 一致，且脚本在 DOM 渲染后执行 |
| 空白页，无报错，图表区域高度为 0 | 容器未指定高度或初始化时被隐藏 | 在开发者工具的 Elements 面板查看容器实际宽高 |
echarts is not defined | 未正确引入 ECharts | 检查 import 语句或 CDN 链接是否有效 |
| 坐标轴显示但柱子不出现 | series 中 type 或 data 拼写错误 | type: 'bar' 为全小写，检查是否有大写字母或多余空格 |
| 容器尺寸变化后图表不跟随 | 这是默认行为，需要手动调用 resize | 在 resize 事件或数据更新后调用 chart.resize() |
Node.js 渲染报 Not implemented | node-canvas 未正确安装或编译不完整 | 确认 node-canvas 的编译依赖（Cairo 等）已安装 |
排错的一般顺序：先查看控制台错误信息，再确认容器尺寸，最后校验 option 结构的合法性。
小结
从项目初始化、npm 安装、模块引入，到浏览器端渲染出第一个柱状图，这几步覆盖了 ECharts 开发的基本链路。其中容器尺寸的处理和异步渲染时机的把握是实际使用中容易出错的两个环节。服务端渲染作为另一种运行形态，扩展了 ECharts 的使用场景。
下一章将在当前基础上配置折线图、饼图、散点图及混合图表，进一步掌握 series 与坐标系的搭配方式。