Apache ECharts 常用 CLI 命令与工具详解
汇总 Apache ECharts 常用命令与 API：npm 安装卸载、Node 运行验证，以及 init、setOption、resize、dispose、getDataURL、renderToSVGString、use 速查。
Apache ECharts 常用 CLI 命令与工具详解
实测环境：Ubuntu 22.04.5 LTS / CentOS Linux 8，ECharts 6.1.0，Node.js 18.20.8，npm 10.8.2。
一、概述
ECharts 是 JavaScript 库，不像服务型组件那样自带 echarts 命令行程序。日常「CLI 操作」实际围绕三块展开：
- 包管理命令：
npm/pnpm/yarn负责安装、查看与移除依赖。 - Node 运行与构建命令：
node执行 SSR 脚本，打包器执行构建。 - ECharts 实例 API：在代码中调用，等价于编程接口「命令」。
二、npm 与包管理常用命令
2.1 安装与卸载
npm i echarts # 安装到 dependencies
npm i echarts@6.1.0 # 安装指定版本
npm i -D echarts # 安装到 devDependencies
npm uninstall echarts # 卸载
# 卸载回显：removed 40 packages, and audited 1 package in 3s
使用镜像源加速：
npm config set registry https://registry.npmmirror.com
npm config get registry
# 回显：https://registry.npmmirror.com/
2.2 查看版本与依赖树
npm ls echarts
# 回显：
# echarts-lab@1.0.0 /opt/echarts-lab
# └── echarts@6.1.0
npm view echarts version
# 回显：6.1.0
node -e "console.log(require('echarts/package.json').version)"
# 回显：6.1.0
2.3 运行项目脚本
在 package.json 的 scripts 中定义后使用 npm run <name>：
npm run build
# 回显（示意）：vite v5.x building for production...
npm run ssr
# 执行自定义 SSR 渲染脚本
2.4 其他常用命令
npm outdated # 查看可升级的依赖
npm pack echarts # 生成 echarts-6.1.0.tgz 供离线分发
npm cache clean --force
三、Node 运行与验证命令
直接运行 SSR 脚本并检查产物：
node ssr-demo.mjs
# 回显：
# ### bar SVG 长度=5565 文件大小=5597
# ### line SVG 长度=4766 文件大小=4788
# ### pie SVG 长度=3880 文件大小=3932
ls -l *.svg
# 回显：
# -rw-r--r-- 1 root root 5085 bar-on-demand.svg
# -rw-r--r-- 1 root root 5597 bar.svg
# -rw-r--r-- 1 root root 4788 line.svg
# -rw-r--r-- 1 root root 3932 pie.svg
校验 SVG 内容首行：
head -c 60 bar.svg
# 回显：<svg width="800" height="400" xmlns="http://www.w3.org/2000/
四、ECharts 实例 API 速查
以下方法均由 echarts.init() 返回的实例调用。
4.1 init
创建实例：echarts.init(dom, theme, opts)。SSR 场景传 null 作为挂载节点：
const chart = echarts.init(null, null, { renderer: 'svg', ssr: true, width: 800, height: 400 });
4.2 setOption
设置或更新配置，notMerge 为 true 时完全替换而非合并：
chart.setOption(option); // 合并更新
chart.setOption(option, { notMerge: true }); // 整体替换
4.3 resize
挂载节点尺寸变化时重算布局：
chart.resize();
chart.resize({ width: 1000, height: 500 });
4.4 dispose
销毁实例并释放资源；SSR 批处理时建议每张图渲染后调用：
echarts.dispose(chart);
4.5 getDataURL
导出图片的 DataURL。Canvas 渲染返回 data:image/png;base64,...：
const url = chart.getDataURL({ type: 'png', pixelRatio: 1, backgroundColor: '#fff' });
// 回显前缀：data:image/png;base64,iVBORw0K
// 实测 PNG 文件大小：Ubuntu 9419 字节 / CentOS 9474 字节
4.6 renderToSVGString
仅 renderer:'svg' + ssr:true 可用，返回 SVG 字符串：
const svg = chart.renderToSVGString();
// 实测：柱状图 5565 字符，折线图 4766 字符，饼图 3880 字符
4.7 use（按需注册）
配合 echarts/core 注册所需图表与组件：
import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { TitleComponent, TooltipComponent, GridComponent } from 'echarts/components';
import { SVGRenderer } from 'echarts/renderers';
echarts.use([BarChart, TitleComponent, TooltipComponent, GridComponent, SVGRenderer]);
// 实测：按需引入 SVG 长度=5071 文件大小=5085
4.8 其他常用方法
chart.on('click', fn); // 绑定事件
chart.off('click', fn); // 解绑事件
chart.getOption(); // 获取当前配置
chart.clear(); // 清空内容但保留实例
echarts.registerTheme('my', themeObject); // 注册自定义主题
五、构建与打包工具
- Vite：
npm i -D vite，vite build产物即为静态资源，天然支持 ECharts 按需引入的 tree-shaking。 - Webpack：
npm run build，配合import 'echarts/core'减小包体。 - esbuild：
esbuild src/main.js --bundle --minify --outfile=dist/main.js。
查看打包后依赖体积：npm ls echarts-zrender（zrender 为 ECharts 底层渲染库）。
六、常见问题排查
Q1：renderToSVGString is not a function？
确认 init 时使用了 { renderer:'svg', ssr:true }。Canvas 渲染器不支持该方法。
Q2：SSR 渲染出来是空白？
多为未传 width/height。SSR 无 DOM 可测量，必须显式指定尺寸。
Q3：getDataURL 报 Cannot read properties of null？
Canvas SSR 需安装 canvas 包，并传入 canvas 作为挂载节点：
import { createCanvas } from 'canvas';
echarts.setPlatformAPI({ createCanvas: (w, h) => createCanvas(w || 600, h || 360) });
const root = createCanvas(600, 360);
const chart = echarts.init(root, null, { renderer: 'canvas', width: 600, height: 360 });
Q4：图片中文乱码或报 Fontconfig 错误？
服务器缺少字体。CentOS 8 执行 dnf -y install dejavu-sans-fonts fontconfig，Ubuntu 执行 apt-get install -y fonts-dejavu-core fontconfig。