使用folium制作choropleth交互式地图时MultiPolygon不可序列化错误的解决方法

根因定位 #

• 你的数据合并环节校验正常，报错触发点确实在Choropleth函数的入参处理流程，和数据清洗、合并逻辑无关
• 报错本质是版本兼容问题：你本地安装的是0.16以上版本的folium，这类版本重构了GeoJSON类的底层序列化逻辑，不再内置对Shapely几何对象的自动转换兜底。当直接把GeoDataFrame作为geo_data参数传入时，默认JSON序列化流程无法识别Shapely生成的MultiPolygon、Polygon几何对象，最终抛出类型不支持的错误

修复步骤 #

1. 显式完成GeoDataFrame到GeoJSON的转换，绕过folium内部的自动转换逻辑
   不要直接把合并后的GeoDataFrame传给geo_data参数，提前手动完成格式转换：

   # 将带几何字段的GeoDataFrame转为标准GeoJSON字符串
   geo_layer = table.to_json()
   

2. 匹配新版Choropleth的参数设计逻辑拆分入参
   新版Choropleth对两个核心入参的职责做了明确划分：

   • geo_data：仅承载几何边界信息，不需要携带统计数值字段
   • data：仅承载待映射的数值表，只需保留匹配键和可视化数值两列，不需要携带几何信息
     调整后的Choropleth初始化代码如下：

   # 补全地图初始参数，避免默认视角偏移
   meat_map = folium.Map(location=[20, 0], zoom_start=3)
   
   folium.Choropleth(
       geo_data=geo_layer,
       name='choropleth',
       # 仅选取需要的两列传入data，减少冗余字段传输
       data=table[['name', 'kg/person (2002)[9][note 1]']],
       # 列名和传入的data字段保持一致，匹配key_on的查找规则
       columns=['name', 'kg/person (2002)[9][note 1]'],
       key_on='feature.properties.name',
       fill_color='YlGnBu',
       fill_opacity=0.7,
       line_opacity=0.2,
       legend_name="Meat consumption in kg/person"
   ).add_to(meat_map)
   

3. 校验依赖版本
   若完成格式转换后仍报序列化错误，执行以下命令安装适配版本的Shapely库，解决几何对象的序列化兼容问题：

   pip install shapely==2.0.3
   

常见踩坑提醒 #

• 不要盲目照搬旧教程的入参写法：0.12及更早版本的folium允许把GeoDataFrame同时传入geo_data和data两个参数，这种写法在新版会引入不必要的字段冗余，甚至触发转换错误
• 注意匹配键的一致性：你之前设置的key_on='feature.properties.name'是读取GeoJSON要素属性下的name字段，这个字段来自原始的world数据集，合并操作不会删除该字段，直接用它作为匹配键比用合并得到的Country字段更稳妥，能避免因字段内容差异导致的匹配失败、地图全白问题

内容的提问来源于stack exchange，提问作者Huascar