本文详解 folium 中批量添加 polyline 时因 numpy 数据类型不兼容导致 jupyter 内核崩溃的问题，提供可靠的数据类型转换方案与健壮的绘图实践。
本文详解 folium 中批量添加 polyline 时因 numpy 数据类型不兼容导致 jupyter 内核崩溃的问题，提供可靠的数据类型转换方案与健壮的绘图实践。
在使用 Folium 结合 pandas DataFrame 批量绘制折线（PolyLine）时，一个常见但隐蔽的陷阱是：直接从 DataFrame 中提取的数值（如 row[“Breitengrad_x”]）常为 numpy.int64 或 numpy.Float64 类型，而 Folium 的底层序列化逻辑（尤其是 json.dumps）对部分 NumPy 类型支持不完善。这会导致地图对象构建失败，触发 Jupyter 内核异常终止（Kernel died），尤其在循环中反复调用 .add_to(m) 时风险更高——这正是你遇到问题的根本原因。
✅ 正确做法：显式转换为 Python 原生数值类型
Folium 要求 locations 参数中的坐标必须是 Python 原生 float 或 int（即 built-in 类型），而非 NumPy 标量。因此，需在构造坐标前进行安全转换：
import folium import pandas as pd # 示例数据（请替换为你的实际 DataFrame） dfFilter = pd.DataFrame({ "Breitengrad_x": [48.8566, 51.5074, 40.7128], # 纬度（巴黎、伦敦、纽约） "Längengrad_x": [2.3522, -0.1278, -74.0060] # 经度 }) # 初始化地图（注意：经纬度顺序为 [纬度, 经度]，Folium 使用此约定） m = folium.Map( location=[dfFilter["Breitengrad_x"].iloc[0], dfFilter["Längengrad_x"].iloc[0]], zoom_start=2, max_zoom=18 ) # 安全循环绘线：关键在于 int()/float() 显式转换 for idx, row in dfFilter.iterrows(): try: # ✅ 强制转为 Python 原生类型（解决核心问题） lat = float(row["Breitengrad_x"]) # 推荐统一用 float，兼容整数/浮点列 lon = float(row["Längengrad_x"]) # 构造线段：此处以每点连接到固定参考点 [20, 20] 为例 coordinates = [[lat, lon], [20.0, 20.0]] folium.PolyLine( locations=coordinates, color="#FF0000", weight=4, opacity=0.8 ).add_to(m) except (ValueError, TypeError) as e: print(f"跳过第 {idx} 行：坐标转换失败 — {e}") continue m # 显示地图⚠️ 关键注意事项
- 坐标顺序不可颠倒：Folium 的 locations 参数要求每个点为 [纬度, 经度]（即 [lat, lon]），与常见 GIS 的 [lon, lat] 顺序相反，务必核对列名含义；
- 避免 numpy.int64 直接传入：即使值看起来是整数（如 50），numpy.int64(50) ≠ int(50)，JSON 序列化会失败；
- 增强鲁棒性：建议使用 float() 而非 int()，因地理坐标多为浮点数；并加入 try-except 捕获异常行，防止单条错误中断整个循环；
- 性能提示：若数据量极大（>1000 条线），考虑改用 folium.FeatureGroup 分组管理，或预生成 GeoJSON 后一次性加载，避免频繁 dom 操作。
✅ 验证是否修复成功
运行后若地图正常渲染且无内核崩溃，说明类型问题已解决。可进一步验证：
# 检查原始数据类型 print(dfFilter["Breitengrad_x"].dtype) # 通常输出: int64 或 float64 print(type(dfFilter.iloc[0]["Breitengrad_x"])) # 如为 <class 'numpy.int64'>，则需转换遵循以上实践，即可稳定、高效地在 Folium 中批量绘制动态折线，彻底规避“Kernel died”陷阱。