numpy.int64等类型不被MongoDB BSON协议支持，需用.item()转为Python原生标量或.tolist()转为原生列表，Pandas批量处理应遍历列按dtype分类转换，避免自定义编码器引发隐性问题。
为什么 numpy.int64 直接插 MongoDB 会报错
MongoDB 的 BSON 协议只认 Python 原生类型（如 int、float、str），不支持 numpy.int64、numpy.float32 这类扩展类型。PyMongo 在序列化时遇到它们会直接抛 TypeError: Object of type int64 is not JSON serializable 或类似错误。
这不是 PyMongo 版本问题，也不是配置能绕过的——BSON 编码器硬性拒绝 numpy 类型。
- 常见错误现象：
TypeError: Type <class> not supported</class>、Cannot encode object - 典型场景：用
pandas.read_csv()读数据后直接转dict插入；或从 NumPy 数组切片取值后没处理就塞进文档 - 别试
json.dumps(..., default=str)：它会让数字变字符串，丢失类型语义，且无法被 MongoDB 正确索引
tolist() 和 item() 该选哪个
两者都用于降维/转换，但适用粒度不同，乱用会导致嵌套结构出错或静默失败。
-
tolist()适合整个 NumPy 数组（含多维）：返回 Python 原生 list/nested list，保留结构层级
→ 例如np.array([[1, 2], [3, 4]]).tolist()→[[1, 2], [3, 4]] -
item()只适用于标量（0维数组）或单元素数组：返回纯 Python 标量（int/float）
→ 例如np.int64(42).item()→42（类型是int）；np.array(3.14).item()→3.14（类型是float） - 对一维数组误用
item()会报ValueError: can only convert an array of size 1 to a Python scalar - 对多维数组用
tolist()是安全的；但若字段本该是单值（比如"age": np.int64(25)），必须用.item()，否则插入的是 list[25]
如何批量处理 Pandas DataFrame 插入前的类型清洗
Pandas 的 dtypes 常含 int64、float64、object（实际存着 numpy 类型），不能直接 to_dict('records') 后插入。
立即学习“Python免费学习笔记（深入）”；
- 最稳妥做法：遍历每列，按 dtype 分类转换
df = df.astype({col: 'int64' for col in int_cols})不解决问题——这只是 Pandas 内部类型，底层仍是 numpy 类型 - 推荐在转 dict 前统一映射：
def clean_numpy_types(obj): if isinstance(obj, (np.integer, np.floating)): return obj.item() elif isinstance(obj, np.ndarray): return obj.tolist() else: return obj records = df.applymap(clean_numpy_types).to_dict('records') - 注意
applymap()已弃用（Pandas ≥ 2.1），新写法用map()配合apply()：records = df.apply(lambda s: s.map(clean_numpy_types)).to_dict('records') - 性能提示：对百万级数据，避免逐元素判断类型；可先用
df.select_dtypes(include=['number']).columns锁定数值列，再批量.astype(float).round().astype(int)强制转原生类型（但会丢失 uint 等边界精度）
PyMongo 插入时自动转换的陷阱
有人想用自定义 BSON 编码器一劳永逸，但实际踩坑更多。
- PyMongo 的
CodecOptions+ 自定义TransformCodec确实能拦截 numpy 类型，但需严格匹配所有子类（np.int32、np.uint64…），漏一个就崩 - 更隐蔽的问题：自定义编码器会影响所有插入操作，包括你没意识到的第三方库调用（比如某些 ORM 封装），导致行为不一致
- 如果用了
mongoengine或beanie，它们有自己的序列化流程，加 PyMongo 编码器可能完全不生效 - 真正省事的做法不是“全局拦截”，而是「在哪读进来，就在哪清掉」：Pandas 处理完立刻
.astype(object).applymap(...)，或 NumPy 计算后显式.item()赋值给字典字段
最易被忽略的一点：布尔值。np.bool_(True) 不是 Python bool，MongoDB 虽能存，但部分驱动版本会把它当 int 处理（存成 1/0），查的时候类型不一致。务必用 .item() 转。
