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 只解决“空值导致索引失败”这一个问题，它不负责类型清洗、不修复编码错误、也不让模糊匹配变精确——该检查数据质量的地方，一步都不能省。
