1. 为什么数据可视化绕不开 pyecharts

做 Web 数据展示这行十来年，我见过太多项目在“把数据画出来”这一步翻车。后端接口跑得飞快，数据库查询毫秒级返回，结果前端拿到一堆 JSON 之后，要么用原生 Canvas 手搓图表搓到怀疑人生，要么引入某个重型图表库，配置项多到文档翻三遍还找不到北。尤其是做后台管理系统、运营看板、数据大屏这类场景，图表种类多、交互要求高、还得跟 Python 后端无缝衔接，这时候pyecharts就成了一个绕不过去的选项。

pyecharts 是什么？一句话讲清楚：它是一个 Python 库，把百度的 ECharts 图表能力封装成了 Python 对象，你写 Python 代码，它帮你生成 ECharts 能识别的配置，最终输出成 HTML 文件或者可嵌入网页的图表组件。能做什么？折线图、柱状图、饼图、散点图、地图、雷达图、词云、桑基图、关系图，基本上你能想到的常规图表它都有，而且支持交互——鼠标悬停显示数值、点击图例隐藏系列、缩放拖拽，这些都不用你写一行 JavaScript。解决了什么问题？解决了 Python 开发者不熟悉前端图表库、又需要快速产出可交互可视化页面的痛点。适合谁看？做数据分析的、写 Django/Flask/FastAPI 后台的、搞数据大屏的、以及任何需要把数据变成图给老板或客户看的人。

我最早接触 pyecharts 是在一个运营数据看板项目里，当时团队里没人愿意碰前端图表，后端同学用 Matplotlib 生成的静态图片被产品经理嫌弃“太丑、不能点、不能缩放”。换成 pyecharts 之后，同样的数据，半天时间就搭出了一个可交互的看板，产品经理当场闭嘴。从那以后，但凡遇到“Python 后端 + Web 图表”的需求，我第一反应就是它。

不过话说回来，pyecharts 虽然上手快，但坑也不少。版本迭代快、文档分散、配置项命名有时候反直觉、和 Web 框架集成时静态资源路径容易出问题。这篇内容我就按自己实际踩过的路，从核心思路、关键细节、实操流程到问题排查，完整拆一遍，让你少走弯路。

2. 核心设计思路与方案选型拆解

2.1 为什么是 pyecharts 而不是 Matplotlib 或 Plotly

先聊选型。Python 生态里画图的库一抓一大把，Matplotlib、Seaborn、Plotly、Bokeh、Altair，每个都有自己的地盘。但放到 Web 实战场景里，选择逻辑就变了。

Matplotlib 是静态图王者，科研论文、离线报告用它没问题，但它生成的图片是死的，没有交互，放到网页上就是一张 img 标签，用户想放大看某个数据点？没门。Seaborn 基于 Matplotlib，更偏向统计可视化，同样不解决 Web 交互问题。Plotly 其实很强，交互能力甚至比 pyecharts 更细腻，但它的 Python 端配置风格偏底层，而且默认走的是 Plotly.js，和国内项目里常见的 ECharts 生态不太一样。Bokeh 适合做数据应用，但学习曲线陡，配置复杂。Altair 基于 Vega-Lite，语法优雅，但定制能力有限，复杂图表容易卡住。

pyecharts 的核心优势在于三点。第一，ECharts 的底子。ECharts 在国内前端图表领域占有率极高，文档全、社区大、样式符合国内审美，pyecharts 直接复用了这套渲染引擎，出来的图默认就好看。第二，Pythonic 的 API。它把 ECharts 那套 JSON 配置封装成了链式调用的 Python 对象，add_xaxis、add_yaxis、set_global_opts，读起来像自然语言，写起来顺手。第三，输出灵活。可以生成独立 HTML 文件，可以渲染成 Jupyter Notebook 里的内嵌图，也可以拿到图表配置 JSON 自己塞进前端，甚至能配合 Flask/Django 直接返回页面。

我个人的判断标准很简单：如果图表要嵌入 Web 页面、需要交互、团队以 Python 为主，选 pyecharts；如果是纯离线静态报告，Matplotlib 够用；如果追求极致交互和 3D 效果，可以考虑 Plotly 或直接上前端 ECharts。

2.2 版本选择：v1 和 v2 的差异与取舍

pyecharts 的版本问题是个大坑，必须单独说。早期 v0.5.x 和后来的 v1.x 在 API 上几乎是两个库，网上很多老教程还在用 v0.5 的写法，你照着抄到 v1 环境里直接报错。目前主流是 v1.x 和 v2.x，v2 在 v1 基础上做了一些调整，但核心 API 基本兼容。

v1 和 v2 的主要差异体现在几个地方。首先是默认主题和渲染方式的微调，v2 对 Jupyter Notebook 的支持更顺滑。其次是部分图表类型的配置项命名有变化，比如某些set_series_opts里的参数。再就是依赖管理，v2 对 Python 版本要求更高，建议 3.7 以上。

我的建议是：新项目直接上 v2，老项目如果 v1 跑得稳就别折腾。安装的时候一定要锁版本，pip install pyecharts==2.0.3这种写法比裸装靠谱，因为 pyecharts 的小版本更新偶尔会引入不兼容改动。我吃过一次亏，本地开发环境装的是最新版，服务器上装的是旧版，同一个脚本跑出来的图配置不一样，排查了半天才发现是版本问题。

提示：安装 pyecharts 时建议同时确认snapshot-selenium或snapshot-phantomjs这类截图依赖是否需要，如果只是生成 HTML 不截图，不用装这些，能省不少事。

2.3 渲染机制：从 Python 对象到浏览器图表

理解 pyecharts 的渲染机制，能帮你少踩很多坑。它的工作流程大致是这样的：你在 Python 里创建一个图表对象，比如Bar()，然后调用add_xaxis和add_yaxis往里面塞数据，再通过set_global_opts设置标题、图例、工具箱这些全局配置。这些操作本质上是在构建一个巨大的配置字典，结构跟 ECharts 的 option 对象一一对应。

当你调用render()的时候，pyecharts 会做两件事：一是把配置字典序列化成 JSON，二是生成一个 HTML 文件，里面引入 ECharts 的 JavaScript 库，然后用一段脚本把 JSON 配置传给 ECharts 实例，浏览器打开这个 HTML 就能看到图。如果你在 Jupyter Notebook 里调用render_notebook()，它会走另一套逻辑，把图表直接内嵌到 Notebook 的输出单元格里。

这里有个关键点：生成的 HTML 默认会从 CDN 加载 ECharts 的 JS 文件。这意味着如果你的运行环境不能访问外网，或者内网环境有网络限制，图表就渲染不出来，页面一片空白。解决办法是用CurrentConfig.ONLINE_HOST把 CDN 地址改成本地静态文件路径，或者直接用render_embed()把 JS 代码内嵌进 HTML，代价是文件体积变大。我在内网项目里被这个问题坑过，本地测试好好的，部署到内网服务器上图表全白，后来把 ECharts 的 JS 文件下载下来放到静态目录才解决。

3. 核心细节解析与实操要点

3.1 图表对象的构建逻辑：链式调用怎么用

pyecharts 的 API 设计是链式调用风格，这个风格用熟了很爽，但新手容易懵。我拿一个柱状图举例，把每一步拆开讲。

from pyecharts.charts import Bar from pyecharts import options as opts bar = ( Bar() .add_xaxis(["一月", "二月", "三月", "四月", "五月"]) .add_yaxis("销售额", [120, 200, 150, 80, 170]) .add_yaxis("利润", [20, 50, 30, 10, 40]) .set_global_opts( title_opts=opts.TitleOpts(title="月度经营数据"), yaxis_opts=opts.AxisOpts(name="金额（万元）"), toolbox_opts=opts.ToolboxOpts(is_show=True), ) ) bar.render("bar_chart.html")

这段代码里，Bar()创建了一个柱状图实例。add_xaxis设置 X 轴分类，add_yaxis每调用一次就加一个数据系列，第一个参数是系列名，第二个参数是数据列表。set_global_opts是全局配置入口，标题、坐标轴、工具箱、图例都在这里设。最后render输出 HTML。

这里有几个细节值得注意。第一，add_yaxis可以多次调用，每次加一个系列，系列名会显示在图例里。第二，set_global_opts的参数都是opts模块下的配置类，比如TitleOpts、AxisOpts、ToolboxOpts，这些类的命名基本能望文生义。第三，链式调用的顺序有讲究，add_xaxis和add_yaxis要在set_global_opts之前，因为全局配置依赖于已有的系列数据。

我见过有同学把set_global_opts写在add_yaxis前面，结果图例不显示，排查半天。原因是全局配置在设置时如果还没有系列，某些依赖系列信息的配置项就失效了。所以记住一个原则：先加数据，再设全局。

3.2 配置项体系：opts 模块的正确打开方式

pyecharts 的配置项都集中在pyecharts.options模块里，这个模块内容非常多，新手容易迷路。我按使用频率把它分成几类，你按这个分类去查文档会快很多。

全局配置类：TitleOpts管标题，LegendOpts管图例，TooltipOpts管提示框，ToolboxOpts管右上角的工具箱，VisualMapOpts管视觉映射（比如用颜色深浅表示数值大小），DataZoomOpts管数据缩放。这些通过set_global_opts设置。

坐标轴配置类：AxisOpts管 X 轴和 Y 轴的通用配置，AxisLineOpts管轴线，AxisTickOpts管刻度，AxisLabelOpts管标签文字。这些通过set_global_opts里的xaxis_opts和yaxis_opts传入。

系列配置类：LabelOpts管数据标签显示，LineStyleOpts管线条样式，ItemStyleOpts管图形元素样式，MarkPointOpts管标记点，MarkLineOpts管标记线。这些通过set_series_opts设置，作用于所有系列。

图表专属配置类：比如饼图的PieOpts、地图的MapOpts、雷达图的RadarOpts，这些是特定图表类型才有的配置。

我个人的经验是，不用背这些类名，用的时候去官方文档的“配置项”章节搜关键词就行。但有几个高频配置必须记住：is_show控制显示隐藏，name设置名称，pos_left、pos_right、pos_top、pos_bottom控制位置，color设置颜色。这些参数在多个配置类里通用，记住一次到处能用。

注意：set_global_opts和set_series_opts是两个不同的入口，前者管全局，后者管系列。有些配置项在两个地方都能设，但优先级不同，系列级配置会覆盖全局配置。如果你发现某个样式没生效，先检查是不是被系列级配置覆盖了。

3.3 数据格式的坑：列表、字典还是 DataFrame

pyecharts 对数据格式的要求比较灵活，但灵活意味着容易出错。add_yaxis的第二个参数接受列表、元组，也接受 pandas 的 Series。但如果你传的是 DataFrame 的某一列，记得先.tolist()转一下，否则某些版本会报类型错误。

X 轴数据同理，add_xaxis接受列表。如果你的分类是数字，比如年份[2020, 2021, 2022]，pyecharts 默认会当成数值轴处理，刻度可能变成2020.5这种奇怪的值。解决办法是把数字转成字符串，["2020", "2021", "2022"]，这样就是分类轴了。

还有一个常见坑是数据长度不一致。X 轴有 5 个分类，某个系列只给了 4 个数据，pyecharts 不会报错，但图表会显示异常，最后一个分类没有数据。这种问题在动态生成数据时特别容易发生，比如从数据库查出来的月份列表和销售数据列表长度对不上。我的做法是在add_yaxis之前加一个断言，assert len(x_data) == len(y_data)，提前暴露问题。

对于多系列图表，数据组织方式也有讲究。你可以循环调用add_yaxis，也可以把数据整理成列表推导式。我倾向于先把数据整理成[(系列名, 数据列表), ...]的结构，然后循环添加，这样代码更清晰，也方便动态调整系列数量。

3.4 主题与样式：让图表不丑的实用技巧

pyecharts 内置了十几套主题，通过InitOpts的theme参数指定。常用的有LIGHT、DARK、CHALK、ESSOS、INFOGRAPHIC等。做数据大屏一般用DARK或CHALK，做后台管理系统用LIGHT或ESSOS。

from pyecharts.globals import ThemeType bar = Bar(init_opts=opts.InitOpts(theme=ThemeType.DARK))

但内置主题只能改整体色调，想精细控制颜色还得靠ItemStyleOpts。比如给柱状图的每个柱子设不同颜色：

.set_series_opts( itemstyle_opts=opts.ItemStyleOpts( color="rgba(30, 144, 255, 0.8)" ) )

如果要按数值大小渐变颜色，用VisualMapOpts：

.set_global_opts( visualmap_opts=opts.VisualMapOpts( min_=0, max_=200, is_piecewise=False, range_color=["#50a3ba", "#eac763", "#d94e5d"] ) )

这里range_color是一个颜色列表，从最小值到最大值渐变。is_piecewise设为True则是分段显示，适合做等级划分。

我个人的审美偏好是：少用默认色，多用低饱和度配色。ECharts 默认的蓝色、绿色、黄色饱和度偏高，放在大屏上刺眼。我一般会自定义一套配色，比如["#5B8FF9", "#5AD8A6", "#5D7092", "#F6BD16", "#E86452"]，这套颜色对比度适中，长时间看眼睛不累。

4. 实操过程与核心环节实现

4.1 环境搭建与依赖安装

先把环境弄干净。我习惯用虚拟环境，避免和系统 Python 打架。

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install pyecharts==2.0.3

如果你需要 pandas 处理数据，一并装上：

pip install pandas

如果需要生成截图，比如做自动化报告，再装snapshot-selenium：

pip install snapshot-selenium

但截图功能依赖浏览器驱动，配置起来麻烦，不是必需就别装。我一般只在需要批量导出图片时才用。

安装完之后验证一下：

import pyecharts print(pyecharts.__version__)

能打印出版本号就说明装好了。

4.2 第一个完整图表：从数据到 HTML

我拿一个模拟的月度销售数据来演示完整流程。假设有某公司五个区域的销售额和利润数据，要做一个分组柱状图。

from pyecharts.charts import Bar from pyecharts import options as opts from pyecharts.globals import ThemeType # 准备数据 regions = ["华东", "华南", "华北", "西南", "东北"] sales = [320, 280, 210, 150, 190] profits = [64, 56, 42, 30, 38] # 构建图表 bar = ( Bar(init_opts=opts.InitOpts( theme=ThemeType.LIGHT, width="900px", height="500px" )) .add_xaxis(regions) .add_yaxis("销售额", sales, category_gap="40%") .add_yaxis("利润", profits, category_gap="40%") .set_global_opts( title_opts=opts.TitleOpts( title="各区域销售与利润对比", subtitle="数据来源：模拟数据", pos_left="center" ), legend_opts=opts.LegendOpts(pos_top="8%"), tooltip_opts=opts.TooltipOpts(trigger="axis", axis_pointer_type="shadow"), yaxis_opts=opts.AxisOpts(name="金额（万元）"), xaxis_opts=opts.AxisOpts(name="区域"), toolbox_opts=opts.ToolboxOpts(is_show=True), ) .set_series_opts( label_opts=opts.LabelOpts(is_show=True, position="top"), markline_opts=opts.MarkLineOpts( data=[opts.MarkLineItem(type_="average", name="平均值")] ) ) ) bar.render("regional_sales.html")

这段代码跑完，当前目录下会生成regional_sales.html，双击用浏览器打开就能看到图。几个关键点解释一下。

category_gap="40%"控制柱子之间的间距，值越大柱子越细。默认是20%，我一般调到40%到50%，看起来更透气。

tooltip_opts里的trigger="axis"表示鼠标悬停时显示整条轴上的所有系列数据，axis_pointer_type="shadow"是加一个阴影指示器，体验更好。

markline_opts加了一条平均值标记线，type_="average"是内置的统计类型，也可以传具体数值。

label_opts的position="top"让数值显示在柱子上方，如果柱子太密可以设成"inside"显示在柱子内部。

4.3 多图表组合：Grid 和 Page 的用法

实际项目里很少只画一张图，通常是多张图拼在一个页面里。pyecharts 提供了Grid、Page、Tab三种组合方式。

Grid是网格布局，适合把几张图叠在一个坐标系里，或者上下左右排列。比如上面一张折线图，下面一张柱状图：

from pyecharts.charts import Bar, Line, Grid bar = Bar().add_xaxis(regions).add_yaxis("销售额", sales) line = Line().add_xaxis(regions).add_yaxis("利润率", [20, 20, 20, 20, 20]) grid = ( Grid(init_opts=opts.InitOpts(width="900px", height="600px")) .add(bar, grid_opts=opts.GridOpts(pos_bottom="60%")) .add(line, grid_opts=opts.GridOpts(pos_top="60%")) ) grid.render("grid_demo.html")

pos_bottom="60%"和pos_top="60%"控制两张图在画布上的位置，一个占下半部分，一个占上半部分。

Page是分页布局，适合图表很多、一屏放不下的场景。它会把每张图渲染成一个可切换的页面：

from pyecharts.charts import Page page = Page(layout=Page.SimplePageLayout) page.add(bar, line, pie, scatter) page.render("page_demo.html")

Page.SimplePageLayout是简单纵向排列，还有DraggablePageLayout可以拖拽调整位置，适合做自定义看板。

Tab是标签页布局，每张图一个标签，点击切换。适合图表类型多但不想占太多空间的场景。

我个人的经验是：数据大屏用 Grid 精确控制位置，后台报表用 Page 简单排列，移动端用 Tab 节省空间。

4.4 与 Web 框架集成：Flask 和 Django 的接入方式

pyecharts 生成的 HTML 是独立文件，但实际项目里往往需要嵌入现有 Web 应用。以 Flask 为例，有两种集成方式。

第一种是直接返回 HTML 字符串。pyecharts 的图表对象有render_embed()方法，返回一段包含图表 HTML 和 JS 的字符串，你可以把它塞进模板：

from flask import Flask, render_template from pyecharts.charts import Bar app = Flask(__name__) @app.route("/") def index(): bar = Bar().add_xaxis(["A", "B", "C"]).add_yaxis("数据", [1, 2, 3]) return render_template("index.html", chart=bar.render_embed())

模板里用{{ chart | safe }}渲染。

第二种是只返回图表配置 JSON，前端自己用 ECharts 初始化。这种方式更灵活，前后端分离项目常用：

@app.route("/chart_data") def chart_data(): bar = Bar().add_xaxis(["A", "B", "C"]).add_yaxis("数据", [1, 2, 3]) return bar.dump_options_with_quotes()

前端拿到 JSON 后，echarts.init(dom).setOption(JSON.parse(data))即可。

Django 的集成思路类似，在视图里生成图表对象，通过render_embed()或dump_options_with_quotes()传给模板或接口。

这里有个坑要注意：render_embed()生成的 HTML 里包含<script>标签，如果模板引擎自动转义了，图表就显示不出来。Flask 的 Jinja2 需要用| safe过滤器，Django 模板需要用| safe或{% autoescape off %}。

另一个坑是静态资源路径。如果项目部署在内网，CDN 加载不了 ECharts 的 JS，需要把 JS 文件下载到static目录，然后配置CurrentConfig.ONLINE_HOST指向本地路径：

from pyecharts.globals import CurrentConfig CurrentConfig.ONLINE_HOST = "/static/echarts/"

这个配置要在创建图表对象之前设置，否则不生效。

4.5 动态数据更新：定时刷新与 WebSocket 思路

数据看板往往需要实时更新。pyecharts 本身是生成静态 HTML 的，不直接支持动态刷新，但可以通过几种方式实现。

最简单的是前端定时请求接口。后端提供一个返回图表配置 JSON 的接口，前端用setInterval每隔几秒请求一次，拿到新配置后调用setOption更新图表。这种方式实现简单，适合数据变化不频繁的场景。

进阶一点的是WebSocket 推送。后端在数据变化时主动推送新配置给前端，前端收到后更新图表。这种方式实时性更好，但需要维护 WebSocket 连接，复杂度高一些。

还有一种取巧的方式是整页刷新。如果数据更新频率很低，比如每小时一次，直接让页面定时刷新就行，不用搞太复杂。

我做过一个实时监控看板，用的是前端定时请求方案，每 5 秒拉一次数据。实测下来，只要接口响应够快，体验完全够用。WebSocket 方案我也试过，但维护成本高，除非对实时性要求极高，否则不推荐。

5. 常见问题与排查技巧实录

5.1 图表不显示或显示空白

这是最高频的问题，原因通常有几种。

CDN 加载失败。打开浏览器控制台，如果看到 ECharts 的 JS 文件 404 或超时，就是这个问题。解决办法是把 JS 文件下载到本地，配置CurrentConfig.ONLINE_HOST。

数据为空。检查add_xaxis和add_yaxis的数据列表是否为空。空列表不会报错，但图表是空白的。

配置项冲突。某些配置项设置不当会导致整个图表渲染失败。比如VisualMapOpts的min_和max_设置反了，或者range_color列表为空。排查方法是把set_global_opts和set_series_opts里的配置逐段注释掉，看哪一段导致问题。

HTML 文件编码问题。如果生成的 HTML 文件编码不是 UTF-8，中文会乱码，图表也可能显示异常。render()方法默认用 UTF-8，一般不用改，但如果你手动处理过文件内容，注意别破坏编码。

5.2 中文乱码与字体问题

中文乱码通常出现在两个地方：图表标题和坐标轴标签。如果生成的 HTML 用浏览器打开正常，但嵌入到其他页面后乱码，多半是页面编码问题，确保页面<meta charset="utf-8">。

如果图表里的中文显示成方块，是字体问题。ECharts 默认用系统字体，某些 Linux 服务器上没有中文字体，渲染出来就是方块。解决办法是在InitOpts里指定字体：

init_opts=opts.InitOpts( chart_id="chart1", width="900px", height="500px", page_title="数据看板" )

或者在TitleOpts和AxisLabelOpts里单独设font_family。

5.3 图表尺寸与响应式适配

pyecharts 默认生成的图表宽度是900px，高度500px。如果容器宽度不够，图表会溢出。解决办法是在InitOpts里把宽度设成百分比：

init_opts=opts.InitOpts(width="100%", height="400px")

但百分比宽度需要父容器有明确宽度，否则可能计算出错。更稳妥的方式是用固定宽度配合 CSS 的max-width和overflow控制。

响应式适配方面，ECharts 本身支持resize，但 pyecharts 生成的 HTML 默认没有监听窗口变化。如果需要响应式，得在前端加一段 JS：

window.addEventListener("resize", function() { chart.resize(); });

其中chart是 ECharts 实例。pyecharts 生成的 HTML 里，实例变量名是自动生成的，你需要找到对应的变量名，或者用echarts.getInstanceByDom获取。

5.4 性能问题：大数据量下的卡顿

pyecharts 渲染几万个数据点时会明显卡顿，因为 ECharts 默认会渲染所有点。解决办法有几种。

开启大数据量模式。ECharts 提供了large和largeThreshold配置，在set_series_opts里设置：

.set_series_opts( large=True, large_threshold=2000 )

这样超过 2000 个点时会启用优化渲染。

使用sampling降采样。折线图可以设置sampling="lttb"，用 Largest-Triangle-Three-Buckets 算法降采样，视觉上几乎无损，但性能提升明显。

分页或缩放。用DataZoomOpts让用户自己缩放查看局部数据，避免一次性渲染全部。

我处理过一个百万级数据点的折线图，直接渲染浏览器直接卡死。后来用sampling="lttb"加上DataZoomOpts，流畅度立刻上来了。

5.5 常见问题速查表

5.6 几个我踩过的坑和独家技巧

坑一：render()重复调用会覆盖文件。如果你在循环里多次调用render()输出到同一个文件名，后面的会覆盖前面的。正确做法是每次输出不同文件名，或者用Page组合。

坑二：Jupyter Notebook 里render_notebook()需要额外依赖。如果报错说找不到某个模块，装pyecharts的时候要带上[notebook]额外依赖：pip install pyecharts[notebook]。

坑三：dump_options_with_quotes()返回的 JSON 字符串里引号被转义了。前端JSON.parse之前要先处理一下，或者直接用dump_options()返回对象。

技巧一：用opts.AxisOpts的axislabel_opts旋转标签。X 轴标签太长时，设rotate=45让标签倾斜，避免重叠。

技巧二：用opts.TooltipOpts的formatter自定义提示内容。可以传 JavaScript 函数字符串，实现复杂的提示格式。

技巧三：批量生成图表时用函数封装。把图表的创建逻辑写成一个函数，传入数据和配置，返回图表对象，这样代码复用率高，也方便统一修改样式。

技巧四：用Page的DraggablePageLayout做可拖拽看板。生成 HTML 后，用户可以自己拖拽调整图表位置和大小，调整完点击保存，会生成一个布局配置 JSON，下次加载时应用这个配置就能保持布局。这个功能做演示特别方便。

6. 进阶玩法与扩展思路

6.1 地图图表的特殊处理

地图是 pyecharts 里比较特殊的一类，因为它依赖地理数据文件。v1 之后，地图数据不再内置，需要单独安装echarts-countries-pypkg、echarts-china-provinces-pypkg、echarts-china-cities-pypkg这些包。

pip install echarts-countries-pypkg pip install echarts-china-provinces-pypkg pip install echarts-china-cities-pypkg

装完之后，Map图表才能正常显示中国地图或省份地图。如果不装，地图会显示成空白或者报错。

地图的数据格式是[(地区名, 数值), ...]，地区名要和地图数据里的名称完全匹配，比如“广东”不能写成“广东省”。这个匹配问题很坑，我建议先用Map的add方法把数据加进去，然后看哪些地区没显示，再对照地图数据文件里的名称修正。

6.2 自定义图表类型与扩展

pyecharts 内置的图表类型覆盖了大部分场景，但偶尔会遇到特殊需求，比如自定义图形、3D 图表、流程图。这时候有几种扩展方式。

用Graph图表画关系图。Graph支持节点和边的自定义，可以做流程图、拓扑图、社交网络图。

用Custom图表完全自定义。Custom允许你直接写 ECharts 的renderItem函数，实现任意图形。这个门槛较高，需要对 ECharts 的图形系统有了解。

直接改配置 JSON。pyecharts 生成的配置字典本质上是 ECharts 的 option，你可以在render()之前手动修改这个字典，加入 pyecharts 没有封装的配置项。比如：

bar.options["series"][0]["itemStyle"]["borderRadius"] = [5, 5, 0, 0]

这样就能给柱子加圆角，虽然 pyecharts 没有直接提供这个配置项。

6.3 自动化报告生成思路

pyecharts 配合定时任务，可以做自动化数据报告。思路是：定时从数据库拉数据，生成图表 HTML，用邮件或消息推送给相关人员。

如果需要生成图片格式的报告，可以用snapshot-selenium把 HTML 截图成 PNG，然后插入到 Word 或 PDF 里。这个流程我做过几次，整体可行，但截图环节偶尔不稳定，需要加重试机制。

另一种思路是生成 HTML 报告，把所有图表用Page组合成一个长页面，直接发链接给用户。这种方式比图片报告体验好，因为图表可以交互。

6.4 主题定制与品牌色适配

如果项目有品牌色要求，pyecharts 的内置主题可能不够用。这时候可以自定义主题。

一种方式是修改InitOpts的theme参数，传入自定义主题的 JSON 文件路径。ECharts 支持自定义主题，你可以在 ECharts 官网的主题编辑器里配好颜色，导出 JSON，然后让 pyecharts 加载。

另一种方式是逐个设置颜色。在set_series_opts里用itemstyle_opts设颜色，在set_global_opts里用visualmap_opts设渐变色。这种方式灵活但繁琐，适合图表数量不多的场景。

我一般会定义一个颜色常量列表，然后在每个图表里循环使用，保证整体风格统一。

7. 一些个人体会

pyecharts 这个库，上手容易精通难。容易是因为 API 直观，半天就能画出能看的图；难是因为配置项太多，遇到问题排查起来费时间。我的建议是：先跑通一个最小可用示例，再逐步加配置。不要一上来就追求完美样式，先把数据正确展示出来，再调样式。

另外，多看 ECharts 官方文档。pyecharts 的配置项命名和 ECharts 的 option 是一一对应的，遇到 pyecharts 文档没写清楚的，去 ECharts 文档搜同名配置，基本都能找到解释。这个技巧帮我省了很多查文档的时间。

最后，版本锁定很重要。pyecharts 迭代快，不同版本之间可能有细微差异。生产环境一定要锁版本，并且在requirements.txt里写清楚。我见过太多因为版本不一致导致的“本地能跑服务器不能跑”的问题，排查起来非常浪费时间。

这个库后续还可以往几个方向扩展：结合 FastAPI 做异步数据接口、用 WebSocket 做实时推送、集成到低代码平台做可视化搭建。如果你在做数据相关的 Web 项目，pyecharts 值得花时间深入。