ECharts 安装与使用完全指南：从全量引入到小程序分包优化

本文基于实际项目（uni-app + Vite + Vue3 + 微信小程序），系统梳理 ECharts 的各种引入方式、体积对比、按需构建方案，以及在小程序分包场景下的最佳实践。

一、ECharts 发行版文件结构

从 ECharts 官方 GitHub Releases 下载源码包（如 echarts-5.6.0.zip），解压后进入 dist 目录，你会看到以下文件：

文件名	格式	大小	说明
`echarts.js`	UMD	~3.4MB	全量版，包含所有图表和组件
`echarts.min.js`	UMD (压缩)	~1MB	全量压缩版，生产环境首选
`echarts.common.js`	UMD	~2.2MB	常用图表版（折线、柱状、饼图、散点等）
`echarts.common.min.js`	UMD (压缩)	~664KB	常用图表压缩版
`echarts.simple.js`	UMD	~1.6MB	精简版（仅折线、柱状、饼图）
`echarts.simple.min.js`	UMD (压缩)	~470KB	精简压缩版
`echarts.esm.js`	ESM	~3MB	全量 ESM 版，支持 Tree-shaking
`echarts.esm.min.js`	ESM (压缩)	~1MB	全量 ESM 压缩版
`echarts.esm.min.mjs`	ESM (压缩)	~1MB	同上，.mjs 后缀

如何选择？

Web 项目 ：优先 npm install echarts，配合 Tree-shaking 按需引入
小程序分包 ：选择 echarts.min.js（UMD）或 echarts.esm.min.js（ESM），体积可控
极致体积：自定义构建，只打包需要的图表类型

二、全量引入（npm 安装）

2.1 安装

bash 复制代码

npm install echarts --save

2.2 全局引入

javascript 复制代码

// main.js
import * as echarts from 'echarts'

// Vue 3 全局挂载
app.config.globalProperties.$echarts = echarts

vue 复制代码

<template>
  <div ref="chartRef" style="width: 100%; height: 400px;"></div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import * as echarts from 'echarts'

const chartRef = ref(null)

onMounted(() => {
  const chart = echarts.init(chartRef.value)
  chart.setOption({
    xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
    yAxis: { type: 'value' },
    series: [{ data: [150, 230, 220], type: 'bar' }]
  })
})
</script>

缺点：全量引入会将所有图表类型和组件打包，体积约 1MB（压缩后），对于只需要简单图表的项目来说过于臃肿。

三、按需引入（Tree-shaking）

ECharts 5.x 支持按需引入，只打包你使用的图表类型和组件。

3.1 按需引入示例

javascript 复制代码

// echarts.js（自定义入口文件）
import * as echarts from 'echarts/core'

// 按需引入图表类型
import { LineChart, BarChart, PieChart } from 'echarts/charts'

// 按需引入组件
import {
  TitleComponent,
  TooltipComponent,
  GridComponent,
  DatasetComponent,
  TransformComponent,
  LegendComponent
} from 'echarts/components'

// 标签自动布局、全局过渡动画等特性
import { LabelLayout, UniversalTransition } from 'echarts/features'

// Canvas 渲染器
import { CanvasRenderer } from 'echarts/renderers'

// 注册必须的组件
echarts.use([
  TitleComponent,
  TooltipComponent,
  GridComponent,
  DatasetComponent,
  TransformComponent,
  LegendComponent,
  LineChart,
  BarChart,
  PieChart,
  LabelLayout,
  UniversalTransition,
  CanvasRenderer
])

export default echarts

3.2 使用

javascript 复制代码

import echarts from './echarts.js'

const chart = echarts.init(dom)
chart.setOption({ /* ... */ })

体积对比：

引入方式	打包体积（压缩后）
全量引入	~1MB
按需引入（折线+柱状+饼图）	~300-400KB
按需引入（仅折线图）	~150-200KB

四、自定义构建（极致体积优化）

如果你只需要特定的图表类型，可以通过 ECharts 的在线构建工具或手动配置 Rollup 来生成专属小包。

4.1 使用 ECharts 在线构建工具

访问 ECharts 在线构建，勾选需要的图表和组件，下载定制版。

4.2 手动 Rollup 构建

javascript 复制代码

// build-echarts.js
const rollup = require('rollup')
const resolve = require('@rollup/plugin-node-resolve')
const commonjs = require('@rollup/plugin-commonjs')
const terser = require('@rollup/plugin-terser')

async function build() {
  const bundle = await rollup.rollup({
    input: 'src/echarts-custom.js',
    plugins: [resolve(), commonjs(), terser()]
  })
  
  await bundle.write({
    file: 'dist/echarts-custom.min.js',
    format: 'umd',
    name: 'echarts'
  })
}

build()

javascript 复制代码

// src/echarts-custom.js
import * as echarts from 'echarts/core'
import { LineChart } from 'echarts/charts'
import { GridComponent, TooltipComponent } from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'

echarts.use([LineChart, GridComponent, TooltipComponent, CanvasRenderer])
export default echarts

构建结果：仅包含折线图的定制包，体积约 100-150KB。

五、uni-app + 微信小程序实战

5.1 项目背景

我们的项目是 uni-app + Vite + Vue3 架构，需要部署到微信小程序。由于小程序有 2MB 主包限制，我们将 ECharts 放在分包 pagesStrategy 中。

5.2 分包结构

python 复制代码

src/
├── pages/              # 主包页面
├── pagesStrategy/      # 策略分包
│   ├── components/
│   │   ├── l-echart/   # lime-echart 组件（Canvas 渲染层）
│   │   │   ├── canvas.js
│   │   │   ├── l-echart.vue
│   │   │   └── utils.js
│   │   └── SimulatePerformanceTrends.vue  # 使用 echarts 的页面
│   └── utils/
│       └── echarts.esm.min.js  # ECharts ESM 版（1MB）
└── pages.json

5.3 lime-echart 组件

lime-echart 是一个专为 uni-app 设计的 ECharts 渲染组件，支持微信小程序的 Canvas 2D 渲染。

核心原理：

javascript 复制代码

// canvas.js - 创建 Canvas 上下文
export function setCanvasCreator(echarts) {
  echarts.setCanvasCreator(() => {
    return new Canvas()
  })
}

// l-echart.vue - 组件初始化
export default {
  methods: {
    async init(echarts) {
      // 获取 Canvas 节点
      const canvasNode = await this.getCanvasNode()
      // 设置 Canvas 创建器
      setCanvasCreator(echarts)
      // 初始化 ECharts 实例
      const chart = echarts.init(canvasNode, null, {
        renderer: 'canvas',
        devicePixelRatio: this.dpr
      })
      return chart
    }
  }
}

5.4 页面中使用

vue 复制代码

<template>
  <view>
    <l-echart ref="chartRef"></l-echart>
  </view>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import lEchart from './l-echart/l-echart.vue'
import * as echarts from '../utils/echarts.esm.min.js'

const chartRef = ref(null)

onMounted(() => {
  setTimeout(async () => {
    const myChart = await chartRef.value.init(echarts)
    myChart.setOption({
      xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
      yAxis: { type: 'value' },
      series: [{ data: [150, 230, 220], type: 'line' }]
    })
  }, 300)
})
</script>

5.5 体积优化方案

方案一：使用 ESM 版本（当前方案）

javascript 复制代码

import * as echarts from '../utils/echarts.esm.min.js'

优点：支持 Tree-shaking，构建工具可以优化
缺点：体积约 1MB

方案二：使用 UMD 版本 + 自定义 Vite 插件

javascript 复制代码

// vite.config.js
export default defineConfig({
  plugins: [
    {
      name: 'umd-esm-default',
      transform(code, id) {
        if (id.includes('echarts.min.js') && !id.includes('node_modules')) {
          return code + '\nexport default exports;'
        }
      }
    }
  ]
})

javascript 复制代码

// 组件中
import echarts from '../utils/echarts.min.js'

优点：UMD 版本体积更小（~1MB vs ESM ~1MB，但压缩率更高）
缺点：需要自定义插件处理

方案三：使用精简版

javascript 复制代码

// 下载 echarts.simple.min.js（470KB）
import echarts from '../utils/echarts.simple.min.js'

优点：体积最小
缺点：只支持折线、柱状、饼图

5.6 分包体积对比

方案	分包体积	说明
echarts.esm.min.js	~1MB	当前使用，支持所有图表
echarts.min.js (UMD)	~1MB	体积相近，需插件处理
echarts.common.min.js	~664KB	常用图表，减少 34%
echarts.simple.min.js	~470KB	精简版，减少 53%
自定义构建（仅折线）	~150KB	极致优化，减少 85%

六、常见问题与解决方案

6.1 UMD 模块导入报错

问题："default" is not exported by echarts.min.js

原因：UMD 格式没有显式的 default 导出。

解决：使用自定义 Vite 插件注入 export default exports。

6.2 `import * as` 导致属性为 undefined

问题：echarts.graphic 是 undefined

原因：Rollup 无法静态分析 UMD 的导出，Tree-shaking 时优化掉了。

解决：改用默认导入 + 自定义插件。

6.3 小程序跨分包引用

问题：module 'pagesStrategy/common/vendor.js' is not defined

原因：CommonJS 配置不当导致 echarts 代码泄漏到主包。

解决：避免使用 commonjsOptions.include，改用自定义 transform 插件。

6.4 Canvas 层级问题

问题：小程序中 Canvas 层级过高，遮挡其他元素。

解决：使用 type="2d" 的 Canvas 2D 模式，或使用 cover-view 覆盖。

vue 复制代码

<canvas type="2d" id="myChart"></canvas>
<cover-view class="overlay">浮层内容</cover-view>

七、最佳实践总结

7.1 Web 项目

bash 复制代码

npm install echarts

javascript 复制代码

// 按需引入
import * as echarts from 'echarts/core'
import { LineChart } from 'echarts/charts'
import { GridComponent } from 'echarts/components'
echarts.use([LineChart, GridComponent])

7.2 小程序主包（< 2MB）

不建议在主包使用 ECharts，体积太大。

7.3 小程序分包

javascript 复制代码

// 方案 A：ESM 版本（推荐）
import * as echarts from '../utils/echarts.esm.min.js'

// 方案 B：UMD 版本 + 插件
import echarts from '../utils/echarts.min.js'

// 方案 C：精简版（极致体积）
import echarts from '../utils/echarts.simple.min.js'

7.4 体积优化优先级

分包加载：将 ECharts 放在分包，避免占用主包空间
按需引入：只打包需要的图表类型
选择合适版本 ：simple < common < full
自定义构建：极致优化，只包含必需功能
延迟加载：将js文件放到分包中，通过延迟加载来实现，这样扩展性更好。

八、参考资源

项目信息：

框架：uni-app + Vite + Vue3
目标平台：微信小程序
ECharts 版本：5.6.0
分包策略：pagesStrategy（策略分包）

ECharts 安装与使用完全指南：从全量引入到小程序分包优化