str.contains默认使用正则模式，需设regex=false匹配中文或特殊字符；空值需显式指定na=false；大小写敏感应加case=false；性能优化需预处理或合并关键词。
str.contains 为什么匹配不到中文或特殊字符
默认正则模式会把中文、括号、加号等当作正则元字符处理，比如 str.contains("C++") 直接报错或行为异常，因为 + 是正则里的量词。
- 加
regex=False关闭正则，走纯字符串查找：df[df["name"].str.contains("C++", regex=False)] - 若必须用正则（比如要匹配“Python2”或“Python3”），得手动转义：
df[df["name"].str.contains(r"Python[23]", regex=True)] - 中文基本不用正则也能满足大多数模糊需求，
regex=False更安全、更快
空值（NaN）导致整个结果变空或报错
str.contains 遇到 NaN 默认返回 NaN，而布尔索引中 NaN 被视为 False，但更常见的是——你根本没意识到某列有空值，结果过滤后数据莫名少了一半。
- 显式用
na=False把空值当False处理：df[df["desc"].str.contains("测试", na=False)] - 不加
na=...时，Pandas 0.25+ 版本默认是na=None，返回NaN；旧版本可能直接抛ValueError - 先检查：
df["desc"].isna().sum()，别靠猜
大小写不一致导致漏匹配
默认区分大小写，"Apple" 不会匹配到 "apple" 或 "APPLE"，尤其在用户输入、日志文本等场景下极容易踩坑。
- 统一转小写再查：
df[df["product"].str.lower().str.contains("iphone", regex=False)] - 或者用
case=False参数（推荐）：df[df["product"].str.contains("iPhone", case=False, regex=False)] -
case=False在正则模式下也生效，但注意：某些 Unicode 字符（如德语 ß）的大小写转换逻辑可能和预期不同
性能差？别在大表上反复调用 str.contains
对千万行 DataFrame 每次都 .str.contains(...)，底层是逐元素 Python 循环 + 正则引擎开销，比向量化操作慢一个数量级。
- 提前用
.str.lower()或.str.strip()做一次预处理，存成新列，后续直接查新列 - 如果只是判断是否包含几个固定关键词，用
df["text"].str.contains("|".join(keywords), regex=True, na=False)合并成单次正则，比循环调用快得多 - 真要高频模糊检索，考虑转向
rapids/cudf（GPU）、duckdb或加全文索引（如 Elasticsearch）——Pandas 不是为这个设计的
模糊匹配看着简单，但 regex、na、case 这三个参数组合起来，稍不注意就漏数据或崩掉。尤其线上跑批任务时，建议加一行断言：assert not df_filtered.empty, "str.contains 未匹配到任何行，请检查关键词和 na 参数"
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
