Python按文件名关键词搜索文件教程

用Python递归遍历目录，按文件名关键词（支持多个关键词、大小写、模糊匹配）快速定位文件，输出完整路径清单，比Windows搜索快十倍。

场景痛点

电脑里攒了几年的文档，几百个文件夹层层嵌套，想找一份"客户合同"相关的文件，只记得文件名里带"合同"两个字。用Windows搜索框卡半天还经常漏结果，翻目录翻到眼花。用Python写一段几十行的脚本，秒级扫完整颗硬盘，把命中的文件路径一行行列出来，还能同时按后缀过滤，这才是办公自动化该有的效率。

用到的库

pip install openpyxl

核心用标准库 os、pathlib，导出结果到Excel时用到 openpyxl。

完整代码

import os
from pathlib import Path
from openpyxl import Workbook


def search_files(root_dir: str, keywords: list,
extensions: list = None,
case_sensitive: bool = False):
"""
在 root_dir 下递归搜索文件名包含任意关键词的文件。
keywords: 关键词列表，命中任意一个即算匹配（OR 逻辑）
extensions: 限定后缀，如 ['.pdf', '.docx']，None 表示不限
case_sensitive: 是否区分大小写
"""
root = Path(root_dir)
hits = []

for dirpath, _, filenames in os.walk(root):
for name in filenames:
# 后缀过滤
if extensions:
ext = Path(name).suffix.lower()
if ext not in {e.lower() for e in extensions}:
continue

# 关键词匹配
target = name if case_sensitive else name.lower()
for kw in keywords:
kw_norm = kw if case_sensitive else kw.lower()
if kw_norm in target:
full = Path(dirpath) / name
hits.append(str(full))
break  # 命中一个关键词即可，避免重复收录

return hits


def export_to_excel(results: list, out_path: str):
"""把结果写入 Excel 台账，方便筛选和二次处理。"""
wb = Workbook()
ws = wb.active
ws.title = "搜索结果"
ws.append(["序号", "文件完整路径"])
for idx, path in enumerate(results, 1):
ws.append([idx, path])
# 列宽拉宽一点，路径才看得全
ws.column_dimensions['A'].width = 8
ws.column_dimensions['B'].width = 100
wb.save(out_path)


if __name__ == "__main__":
# 搜索根目录
ROOT = r"D:\工作资料"
# 关键词：文件名里只要包含任意一个就命中
KEYWORDS = ["合同", "客户", "contract"]
# 只搜这些后缀，不需要就传 None
EXTS = [".pdf", ".docx", ".doc", ".xlsx"]

results = search_files(ROOT, KEYWORDS, EXTS)
print(f"共找到 {len(results)} 个文件：")
for p in results:
print(" -", p)

export_to_excel(results, r"D:\工作资料\搜索结果.xlsx")
print("结果已导出：D:\\工作资料\\搜索结果.xlsx")

代码讲解

os.walk 是Python遍历目录树的标准做法，每次返回当前目录路径、子目录列表、文件列表三件套，递归一层都不用自己写。关键词匹配用最简单的 in 子串判断，大小写不敏感时把文件名和关键词都 lower() 再比，这是最稳的写法。后缀过滤放在关键词判断前面，能提前跳过 .tmp、.sys 这类无关文件，扫描速度快很多。命中一个关键词就 break，避免同一个文件被多个关键词重复收录。导出Excel那段用 openpyxl 直接写表头和路径，列宽手动拉到100，不然路径全被截断。