为什么在聚宽(JoinQuant)研究环境Notebook中Pyecharts渲染不出来？

在聚宽（JoinQuant）的研究环境（Jupyter Notebook）中使用 pyecharts 0.5.x 版本时，经常会遇到图表显示为空白或无法渲染的问题。这通常是因为 Notebook 无法正确加载本地的 Echarts JavaScript 依赖库。此外，关于版本更新，聚宽为了保证大量历史策略和研究代码的兼容性，官方环境的默认库版本更新通常较为谨慎。

以下是针对这两个问题的详细解决方案：

一、 解决 Pyecharts 0.5.x 在 Notebook 中无法渲染的问题

在 0.5.x 版本中，如果图表渲染为空白，可以通过调用 pyecharts.online() 方法，强制让 Notebook 从在线 CDN 加载 Echarts 的 JS 资源，而不是使用本地可能缺失或路径错误的资源。

修复代码示例：

# 导入需要的图表类
from pyecharts import Bar
import pyecharts

# 关键步骤：强制使用在线的 JS 资源库
pyecharts.online()

# 创建图表
bar = Bar("我的第一个图表", "这里是副标题")
bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])

# 在 Jupyter Notebook 的 Cell 最后直接调用图表对象即可渲染
bar

注意：在 0.5.x 版本中，不需要调用 .render_notebook()，直接在单元格最后放置图表对象变量名即可。

二、 如何在聚宽中更新/使用新版 Pyecharts (1.x 及以上)

虽然聚宽官方环境默认自带的是 0.5.x 版本，但聚宽的研究环境允许用户自行安装和升级第三方库。由于 1.x 版本的 pyecharts 与 0.5.x 版本在语法上完全不兼容，建议将其安装在自定义目录中，避免破坏系统默认环境。

升级步骤：

1. 在 Notebook 中新建一个目录并安装新版 Pyecharts

在 Notebook 的一个代码单元格中运行以下命令（利用 !pip 安装到指定目录）：

# 创建一个存放自定义库的文件夹（如果已有可跳过）
!mkdir -p /home/jquser/my_libs

# 将 pyecharts 安装到该目录中
!pip install pyecharts --target="/home/jquser/my_libs" --no-dependencies

2. 在代码中引入自定义路径并使用新版

每次重启研究环境或新建 Notebook 时，在代码最上方添加环境变量路径，即可使用新版本的 pyecharts：

import sys
# 将自定义库路径加入系统路径
sys.path.append("/home/jquser/my_libs")

import pyecharts
print(pyecharts.__version__) # 此时应该输出 1.x.x 或 2.x.x 的新版本号

# 新版 Pyecharts 的绘图语法示例
from pyecharts.charts import Bar
from pyecharts import options as opts

bar = (
    Bar()
    .add_xaxis(["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"])
    .add_yaxis("商家A", [5, 20, 36, 10, 75, 90])
    .set_global_opts(title_opts=opts.TitleOpts(title="主标题", subtitle="副标题"))
)

# 新版在 Notebook 中渲染需要调用 render_notebook()
bar.render_notebook()

总结

• 短期解决：直接在现有代码中加入 pyecharts.online() 即可解决 0.5.x 的白屏问题。
• 长期解决：通过 --target 参数将新版 pyecharts 安装到个人目录 /home/jquser/my_libs，并通过 sys.path.append 引入，这样既能用上最新特性，又不会受官方环境版本更新进度的限制。