str.contains 返回 NaN 是因空值传播规则，无法判断 NaN 是否匹配；设 na=False 可使 NaN 视为 False；正则需转义或设 regex=False；忽略大小写推荐 case=False；复杂正则应预编译提速。
str.contains 为什么返回 NaN 而不是 False？
当你对含 NaN 的字符串列（如 pandas Series）调用 str.contains()，默认会把 NaN 对应位置的结果也设为 NaN，而不是布尔值。这不是 bug，是 pandas 的空值传播规则——它无法判断 NaN 是否“包含”某个模式。
解决方法很简单：显式传入 na=False 参数：
df['col'].str.contains(r'abc', na=False)
这样所有 NaN 都会被当作 False 处理，结果全是布尔值，可直接用于布尔索引。
- 不加
na=False→ 结果含NaN，df[mask]可能意外丢行或报错 - 加了之后 → 安全用于
df[df['col'].str.contains(...)] - 若你真想保留
NaN语义（比如后续要区分“未匹配”和“无数据”），才不设该参数
正则特殊字符没转义导致匹配失败
str.contains() 默认启用正则引擎，所以像 .、+、[、( 这些字符有特殊含义。如果你只想匹配字面量的点号（比如邮箱里的 @domain.com），却写成 r'domain.com'，它实际会匹配 domain + 任意单字符 + com。
立即学习“Python免费学习笔记（深入）”；
正确做法分两种：
- 用原始字符串 + 手动转义：
r'domain\.com' - 关闭正则，走纯文本匹配：
df['col'].str.contains('domain.com', regex=False)
后者更安全、更快，尤其当你只是做子串查找。只有需要“以 abc 开头且后面跟数字”这类逻辑时，才必须用正则（并注意转义）。
忽略大小写的匹配怎么写才可靠？
很多人习惯加 flags=re.I，但要注意：pandas 的 str.contains() 接收的是整数 flag，不是 re 模块对象。直接写 flags=re.I 会报 NameError（除非你先 import re）。
推荐写法是：
df['col'].str.contains('ABC', case=False)
case=False 是 pandas 封装好的参数，等价于 flags=re.IGNORECASE，且无需导入 re，兼容性更好。
-
case=False→ 简洁、安全、推荐 -
flags=re.I→ 需提前import re，且在某些旧 pandas 版本中可能不稳定 - 别混用：同时写
case=False和flags=...会报错
性能差？可能是正则太重或没预编译
如果列很长（百万级）、正则较复杂（比如带回溯的嵌套量词），str.contains() 会明显变慢。pandas 内部对每个元素都调用 re.search()，没复用编译后的 pattern。
提速关键点：
- 简单子串优先用
regex=False（比正则快 3–5 倍） - 复杂正则且高频使用时，手动预编译：
pat = re.compile(r'a.*b.*c')，再传df['col'].str.contains(pat) - 避免在循环里反复调用
str.contains()；一次性筛完再切片
预编译后，pandas 会跳过重复编译开销，对长列效果显著。但注意：预编译对象不能跨进程共享，多进程里得各自重新编译。
