Python pathlib.rglob递归查找文件时为什么漏掉隐藏目录怎样完成一个可复用的最小示例

遇到 Path.rglob() 好像漏掉隐藏目录时，先记住一个容易被忽略的结论：pathlib 不会因为文件名以点号开头就自动跳过它。如果结果少了，优先检查你传入的模式、目录权限、符号链接策略，以及是不是把 glob 模块的行为误套到了 pathlib 上。

下面用一个不依赖具体项目路径的最小写法，把“递归遍历”和“匹配哪些文件”分开，再说明生产环境里最容易误判的边界。

先确认 pathlib 对隐藏项的默认语义

rglob(pattern) 可以理解为在当前路径前加上递归的 **/，例如 root.rglob("*.py") 查找任意层级下名称以 .py 结尾的路径。pathlib 的规则里，点号开头的文件不是特殊项，所以 .cache/config.py 只要满足模式，就不应因为“隐藏”二字被自动排除。

最小示例可以这样写。代码中的排序只是为了让调用方拿到稳定顺序；官方文档明确指出 glob 和 rglob 返回的路径没有特定顺序。

from pathlib import Path

def find_python_files(root: str) -> list[Path]:
    # 把输入目录转换成 Path，递归匹配所有层级的 Python 文件。
    base = Path(root)
    matches = base.rglob("*.py")
    # rglob 不保证返回顺序，批处理或生成清单前主动排序。
    return sorted(path for path in matches if path.is_file())

files = find_python_files("project")
for path in files:
    # 这里仅展示路径，实际业务可改为读取、索引或归档。
    print(path)

把递归范围和文件筛选分开看

标题里说“漏掉隐藏目录”，但很多代码真正写的是 rglob("*.py")。这个模式只返回最终路径名匹配 .py 的条目，不会返回隐藏目录本身，也不会返回目录中的 README.md。如果你需要先看到所有路径，再决定如何筛选，可以暂时使用 rglob("*")，随后用 is_dir() 和 is_file() 分组。

from pathlib import Path

def split_tree(root: str) -> tuple[list[Path], list[Path]]:
    # 使用 * 观察每一层的文件和目录，再在 Python 中做明确分类。
    paths = Path(root).rglob("*")
    directories: list[Path] = []
    files: list[Path] = []
    for path in paths:
        # is_dir/is_file 可能访问文件系统，生产代码应保留异常处理策略。
        if path.is_dir():
            directories.append(path)
        elif path.is_file():
            files.append(path)
    # 两类结果都排序，避免依赖文件系统遍历顺序。
    return sorted(directories), sorted(files)

如果你看到 .cache 目录没有出现在“目录列表”里，先检查是不是只展示了文件结果，或者把 rglob("*.py") 的返回值直接当成目录清单。模式决定结果集合，隐藏属性不是 pathlib 的额外过滤器。

排查真正造成缺项的边界

在生产目录中，缺项更常见的来源是扫描异常被忽略。当前 pathlib 文档说明，glob/rglob 扫描文件系统时产生的 OSError（包括 PermissionError）会被抑制；于是无读取权限的隐藏目录可能表现为“没有结果”，而不是抛出异常。另一个边界是符号链接：递归展开 ** 时默认不跟随符号链接，是否跟随要由 recurse_symlinks 明确决定。

排查时可以按下面的顺序缩小范围：

收敛成可复用的扫描函数

如果扫描结果要进入索引、备份或批处理，建议把根目录、模式、是否跟随链接和排序策略写成显式参数。这样遇到“隐藏目录不见了”时，可以先判断是输入、模式还是文件系统边界，而不是盲目改通配符。

from pathlib import Path
from collections.abc import Iterable

def iter_files(root: Path, pattern: str = "*.py", *, follow_symlinks: bool = False) -> Iterable[Path]:
    # pattern 只负责匹配名称，root 负责限定扫描范围。
    iterator = root.rglob(pattern)
    for path in sorted(iterator):
        # 默认不改变 pathlib 的链接语义；调用方可在入口处记录配置。
        if path.is_file() and (follow_symlinks or not path.is_symlink()):
            yield path

# 示例调用：隐藏目录不会被额外过滤，结果顺序保持稳定。
for source_file in iter_files(Path("project"), "*.py"):
    print(source_file)

这里的 follow_symlinks 只是业务层的筛选开关，并不会改变 rglob 本身的递归参数；如果必须让递归过程跟随链接，应根据所用 Python 版本显式传入对应参数，并评估循环链接风险。

常见问题

pathlib.rglob 会自动忽略 .git 或 .cache 吗？

不会因为点号前缀自动忽略。是否出现取决于模式、权限、链接和你后续的文件类型筛选。

为什么 rglob 扫描没有报 PermissionError？

pathlib 的 glob/rglob 会抑制扫描过程中的部分 OSError。需要把权限与运行账号当作排查项，而不能把空结果直接解释成“没有隐藏目录”。

什么时候应该用 Path.walk()？

当你需要在进入子目录前修改目录列表、主动剪枝或接收 on_error 回调时，Path.walk() 更适合表达控制需求；只做模式匹配时，rglob() 更简洁。

总结一下：先用模式确认你要找的是目录还是文件，再检查权限异常和符号链接策略，最后在批处理边界统一排序与配置。这样才能把“隐藏目录漏掉”还原成一个可定位的文件系统问题。