pyecharts sankey要求nodes（按业务顺序排列的去重步骤名）和links（含source/target/value的字典列表），需从原始日志聚合转化频次，注意中文字体设置、流量归一化及低频路径保留。
Pyecharts Sankey 要求的数据结构必须是「节点列表 + 链接列表」，不能直接喂 Pandas DataFrame
很多人卡在第一步：把用户行为日志（比如 user_id, step, timestamp）丢进 Sankey 就报错。根本原因是 Sankey 不认原始行为序列，它只接受两个固定字段的列表：nodes（去重后的所有步骤名）和 links（每条边的 source/target/value）。你得自己聚合出每对相邻步骤之间的转化次数。
实操建议：
- 先用
pandas.DataFrame.sort_values(['user_id', 'timestamp'])确保每个用户的行为按时间排好序 - 对每个
user_id做shift(1)得到前一步，拼成(prev_step, curr_step)对 - 用
value_counts()统计每对出现频次，再转成字典列表：[{'source': '首页', 'target': '商品页', 'value': 1247}] -
nodes就是所有出现过的prev_step和curr_step并集，去重后按顺序生成索引（Sankey内部靠索引匹配，不是靠字符串名）
节点顺序错乱会导致桑基图交叉、流向反向，必须显式控制 nodes 的排列顺序
Sankey 默认按输入 nodes 列表的下标画图，source 和 target 都映射到这个下标。如果 nodes = ['注册', '登录', '下单']，但某条 link 是 {'source': '登录', 'target': '注册'}，就会画出反向倒流线——实际只是因为“登录”在列表里排第1、“注册”排第0，数值上 1→0 被当成从右往左流。
所以必须按真实路径顺序组织 nodes，例如典型转化漏斗：['曝光', '点击', '加购', '下单', '支付']。哪怕某个环节数据为0，只要逻辑上存在，就该占位，否则后续索引全偏移。
常见错误现象：Sankey 图中出现大量斜穿、线条缠绕、甚至“支付 → 曝光”这种明显逆序边——八成是 nodes 顺序没对齐业务流程。
中文节点名显示方块或乱码？关键是设置 font_family 并禁用 label_opts 的 rich 格式
Pyecharts 默认字体不支持中文，且 Sankey 的 label_opts 若启用了 rich 文本（比如带颜色、对齐），会进一步触发字体 fallback 失败，最终节点名变方块。
解决方法很直接：
- 全局设置：在
Sankey().set_global_opts(title_opts=...)之外，加一句import pyecharts.options as opts，然后传label_opts=opts.LabelOpts(font_family="Microsoft YaHei") - 更稳妥的做法是关掉 rich：
label_opts=opts.LabelOpts(is_show=True, font_family="SimSun", formatter="{b}")，其中{b}表示节点名，不套任何样式 - Windows 下推荐
"Microsoft YaHei"或"SimSun"；macOS 可试"PingFang SC"；Linux 需提前确认系统中文字体路径并用add_js_funcs注入
流量值太小导致线条过细看不见？别调 node_gap，优先归一化或设最小阈值
Sankey 的线条宽度严格正比于 value，但原始转化数可能从几千到个位数。如果最小边只有 1 次，而最大边有 5000 次，那小边几乎不可见——这时调 node_gap 或 layout_iterations 没用，它们只影响布局间距和收敛速度。
真正有效的做法：
- 对
links做阈值过滤：[link for link in links if link["value"] >= 5]，剔除噪声路径 - 或者做相对值转换：把每条边的
value改成「占上游节点总出度的比例」，即value / sum_out_degree[source]，再乘以 100 显示百分比（注意此时要同步调整tooltip_formatter显示原始数值） - 避免用
value做绝对计数+小数点后两位——Sankey会把它当 0.01 处理，线条直接消失
节点层级越深、路径越长，越容易漏掉低频但关键的分支（比如“下单→投诉”这种异常流），过滤时得留个心眼，别一刀切。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
