str.contains 默认遇 NaN 返回 NaN，导致布尔索引报错；加 na=False 可将 NaN 统一转为 False，安全用于筛选，且与 regex 参数正交兼容。

str.contains 找不到空值行就直接报错？

默认情况下 str.contains 遇到 NaN 会返回 NaN，而布尔索引不接受 NaN —— 所以一执行 df[df.col.str.contains("x")] 就抛 ValueError: cannot index with vector containing NA / NaN values。

这不是你写错了，是 Pandas 的默认行为：它把 NaN 当作“未知”，既不是 True 也不是 False，所以无法参与布尔筛选。

• na=False 是最直接的解法：让所有 NaN 统一映射为 False，这样布尔索引就能安全运行
• 别用 fillna("") 后再查——可能误匹配（比如原数据是 None，填空串后变成有效字符串）
• 如果真想保留空值参与逻辑，得先显式分离：用 df.col.isna() 单独处理，再和 str.contains 结果合并

正则模式下 na=False 还管用吗？

管用，但要注意正则本身是否兼容空值。只要加了 na=False，无论 regex=True（默认）还是 regex=False，NaN 都会被转成 False，不会进正则引擎。

• 默认走正则，所以 "."、"^a" 这类会生效；若只想字面匹配，务必加 regex=False
• na=False 和 regex=... 是正交参数，可以同时用，互不影响
• 如果正则写错（比如未转义括号），错误发生在非空值上，na=False 不会掩盖这类语法错误

为什么有时候加了 na=False 还报错？

常见原因不是 na=False 失效，而是列根本不是字符串类型——比如存的是数字、列表、字典，或者混合类型（object 列里有 int 和 str）。

• 先确认类型：df.col.dtype 是 object 不代表全是字符串；用 df.col.apply(type).unique() 看真实类型分布
• 稳妥做法是先转字符串：df.col.astype(str).str.contains("x", na=False)，但注意数字 123 会变成 "123"，可能引发意外匹配
• 更精准的做法是预过滤：df[col].apply(lambda x: isinstance(x, str) and "x" in x)，但性能差，只适合小数据

性能敏感时，na=False 有代价吗？

几乎没有。设置 na=False 只是控制 NaN 的输出值，不改变底层扫描逻辑；真正影响性能的是正则编译、字符串长度、数据量级。

• 大数据量下，优先用 regex=False + na=False，比默认正则快 3–5 倍
• 避免在循环里反复调用 str.contains；一次性生成布尔掩码，再用于多列筛选
• 如果只是判断“是否存在”，用 df.col.str.contains(..., na=False).any() 比先取子集再 len > 0 更轻量

真正容易被忽略的是：na=False 只解决“空值导致索引失败”这一个问题，它不负责类型清洗、不修复编码错误、也不让模糊匹配变精确——该检查数据质量的地方，一步都不能省。