Go问答：path/filepath.Glob通配符路径为什么匹配不到文件怎样完成一个可复用的最小示例

我第一次用 filepath.Glob 找一批配置文件时，最容易误判的是“返回空切片就说明 Glob 失效了”。实际上，空结果只表示当前 pattern 没有匹配到名称；根目录不存在、相对路径基准不对、通配符跨不过目录分隔符，都会得到类似现象。把这些边界拆开后，Glob 反而是一个很轻量的文件筛选工具。

官方资料：https://pkg.go.dev/path/filepath

本文围绕一个小任务展开：在指定目录中找到第一层的 .txt 文件，同时让调用方知道是目录不存在、pattern 非法，还是确实没有命中。示例不依赖第三方包，也不把递归遍历和通配符匹配混为一谈。

先把“匹配不到”拆成三个不同问题

filepath.Glob(pattern) 的返回值是 (matches, err)。如果 pattern 语法错误，err 通常是 filepath.ErrBadPattern；如果语法正确但没有命中，matches 为空且错误为 nil。另外，Glob 会忽略读取目录时遇到的部分 I/O 错误，因此排查时最好先确认根目录存在。

先确认通配符到底覆盖了哪一段

Glob 使用 filepath.Match 的规则。* 匹配同一层中任意长度的非分隔符字符，? 匹配一个非分隔符字符，字符类可以写成 [ab]。关键点是：* 不会跨过目录分隔符。

例如 reports/*.txt 能匹配 reports/today.txt，不能直接匹配 reports/2026/today.txt。如果把 reports/**/*.txt 当成很多工具里的递归通配符，也容易得到空结果或不符合预期的结果；filepath.Glob 没有把 ** 定义成“任意层目录”的特殊语法。

跨平台代码还要避免手写 data\\*.txt 或 data/*.txt。用 filepath.Join 拼出目录和 pattern，才能让分隔符由当前操作系统决定。

用一个小函数把目录问题提前说清楚

下面的函数只做一件事：确认输入是目录，拼出“当前目录下一层的 txt 文件”这个 pattern，再把 Glob 的非法模式错误原样转成调用方可读的错误。它不会假装空结果是异常，也不会把递归功能偷偷塞进来。

package main

import (
    "fmt"
    "os"
    "path/filepath"
)

// listTextFiles 只匹配 root 下一层的 .txt 文件。
func listTextFiles(root string) ([]string, error) {
    info, err := os.Stat(root)
    if err != nil {
        // 先报告目录本身的问题，避免把“目录不存在”误判为空结果。
        return nil, fmt.Errorf("检查目录 %q: %w", root, err)
    }
    if !info.IsDir() {
        // Glob 的目标是目录匹配；传入普通文件时直接给出明确提示。
        return nil, fmt.Errorf("路径 %q 不是目录", root)
    }

    // Join 负责选择当前系统的分隔符，星号只覆盖这一层的文件名。
    pattern := filepath.Join(root, "*.txt")
    matches, err := filepath.Glob(pattern)
    if err != nil {
        // 非法字符类等语法问题会通过 ErrBadPattern 返回。
        return nil, fmt.Errorf("解析匹配模式 %q: %w", pattern, err)
    }
    // matches 为空且 err 为 nil，表示目录存在但这一层没有命中项。
    return matches, nil
}

func main() {
    // 相对路径以进程启动时的工作目录为基准。
    files, err := listTextFiles("./reports")
    if err != nil {
        fmt.Println(err)
        return
    }
    if len(files) == 0 {
        // 空结果是正常业务分支，不等同于 Glob 调用失败。
        fmt.Println("没有找到当前目录下的 txt 文件")
        return
    }
    for _, file := range files {
        // Glob 返回的名称可直接交给后续读取逻辑。
        fmt.Println(file)
    }
}

这个写法的价值不只是“能跑”：os.Stat 把根目录缺失单独拎出来，filepath.Glob 负责模式匹配，空结果则由业务层决定是提示用户、返回默认值还是结束任务。

相对路径是最常见的隐藏变量

如果代码在编辑器里启动时能找到文件，换成命令行、测试进程或服务管理器后却找不到，优先怀疑工作目录变化。相对的 ./reports 不是相对于源码文件，而是相对于进程启动时的当前工作目录。

cwd, err := os.Getwd()
if err != nil {
    // 获取工作目录失败时停止继续拼接相对 pattern。
    return fmt.Errorf("获取当前工作目录: %w", err)
}
fmt.Println("当前工作目录:", cwd)

// 用绝对目录拼接 pattern，排查时更容易复现同一个目标。
pattern := filepath.Join(cwd, "reports", "*.txt")
matches, err := filepath.Glob(pattern)
if err != nil {
    // 这里仍然要处理非法 pattern，而不是只看 matches 长度。
    return fmt.Errorf("匹配文件: %w", err)
}
fmt.Println("匹配数量:", len(matches))

排查时把最终的 cwd 和 pattern 打出来通常比反复修改星号更有效。路径大小写是否敏感也由文件系统决定，不要把在某台机器上命中的大小写写法当成跨平台保证。

什么时候应该换成 WalkDir

Glob 适合“我已经知道目录位置，只筛选这一层名称”的任务，例如读取某个目录下的配置片段。它不负责递归遍历，也不适合在需要判断文件类型、跳过隐藏目录、统计权限错误或自定义过滤条件时硬套 pattern。

如果需求是“从根目录向下遍历所有层级，再挑出扩展名为 .txt 的普通文件”，应考虑 filepath.WalkDir。这时筛选条件由回调控制，不要把 ** 当作 Glob 的递归开关。

一张表快速定位空结果

回到最开始的问题：Glob 匹配不到文件时，先看错误，再看根目录和最终 pattern，最后才调整通配符。只要把“语法错误”“路径基准错误”和“合法但没有命中”分开，绝大多数问题都能在一个很小的函数里定位。

相关问题

filepath.Glob 没有匹配项时会返回错误吗？

通常不会。pattern 合法但没有命中时，返回空结果和 nil 错误；只有模式语法非法时才应重点检查 ErrBadPattern。

为什么 filepath.Glob 不适合递归搜索？

它按 filepath.Match 规则匹配路径段，* 不跨分隔符，** 也不是额外的递归语法。递归筛选应交给 WalkDir 等遍历 API。

相对路径应该相对于哪个目录？

相对于进程当前工作目录，而不是 Go 源文件所在目录。遇到环境差异时先记录 os.Getwd()。