Go os.Stat 怎样区分文件不存在与路径权限问题

调用 os.Stat 失败时，最稳妥的判断方式不是比较 err.Error() 文本，而是用 errors.Is 匹配 fs.ErrNotExist 和 fs.ErrPermission。前者表示目标路径不存在，后者表示当前进程没有足够权限；如果两者都不匹配，再把它当作其它文件系统错误处理。

先建立错误分类基线

os.Stat(name) 成功时返回 FileInfo；失败时通常返回一个 *os.PathError。这个错误至少携带操作名、出错路径和底层原因，所以日志里应保留它，而不是只打印一段自定义提示。

先把判断目标写成三个互斥分支：路径确实不存在、路径被权限阻止、无法归入前两类的系统或文件系统错误。这样后续的重试、用户提示和监控标签才不会混在一起。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "os"
)

func classifyStatError(path string) string {
    _, err := os.Stat(path)
    if err == nil {
        return "found" // 成功拿到 FileInfo，路径当前可访问。
    }

    switch {
    case errors.Is(err, fs.ErrNotExist):
        return "not-exist" // 目标或路径中的目录不存在。
    case errors.Is(err, fs.ErrPermission):
        return "permission-denied" // 当前进程缺少访问所需权限。
    default:
        return "other-error" // 保留未知错误，交给上层决定是否重试。
    }
}

func main() {
    fmt.Println(classifyStatError("config/app.yaml")) // 分类结果只表达业务标签。
}

这段代码的判断成本很低，但它把“文件不存在”和“权限问题”从同一个失败分支里拆开了。需要注意，示例只返回分类标签；生产日志仍应同时记录原始 err。

用 errors.Is 区分不存在与权限拒绝

errors.Is 会沿错误的包装链查找目标，因此即使 os.Stat 返回的外层错误包含了操作名和路径，也不需要拆字符串。对标准库错误分类，优先比较 fs.ErrNotExist 与 fs.ErrPermission。

func statStatus(path string) (string, error) {
    _, err := os.Stat(path)
    if err == nil {
        return "found", nil // 成功分支不返回额外错误。
    }

    if errors.Is(err, fs.ErrNotExist) {
        return "not-exist", err // 把原始错误交回调用方，便于记录 PathError。
    }
    if errors.Is(err, fs.ErrPermission) {
        return "permission-denied", err // 权限拒绝应与缺失路径分开提示。
    }
    return "other-error", err // 例如挂载、I/O 或平台特定错误。
}

不要写成 err == os.ErrNotExist，也不要写成 strings.Contains(err.Error(), "permission")。错误可能经过包装，文本还会随平台和语言环境变化；errors.Is 才是稳定的语义判断。

需要排障时提取 PathError 字段

分类只解决“应该走哪条业务分支”，排障还需要知道哪个操作、哪个路径、哪个底层原因触发了失败。可以用 errors.As 把错误提取成 *fs.PathError；由于 os.PathError 是别名，使用 fs.PathError 也能覆盖标准文件系统接口。

func logStatError(path string) {
    _, err := os.Stat(path)
    if err == nil {
        return
    }

    var pathErr *fs.PathError
    if errors.As(err, &pathErr) {
        // Op、Path、Err 分别说明动作、目标和底层失败原因。
        fmt.Printf("stat failed: op=%s path=%s cause=%v\\n", pathErr.Op, pathErr.Path, pathErr.Err)
    } else {
        // 自定义文件系统可能返回其它错误类型，仍要保留原始错误。
        fmt.Printf("stat failed: path=%s err=%v\\n", path, err)
    }
}

如果只需要判断权限，errors.Is(err, fs.ErrPermission) 足够；只有在日志、指标或上层需要定位具体路径时，才进一步提取 PathError。分类结果和诊断字段是两层信息，不要互相替代。

路径中间目录与平台边界

“文件不存在”不一定只表示最后一个文件名缺失。如果路径中间的目录不存在，也会匹配 fs.ErrNotExist；如果中间目录存在但当前进程无法遍历，可能匹配 fs.ErrPermission。因此，业务提示可以说“目标路径不可用”，日志里再保留完整路径和底层原因。

同样不要把某一次机器上的结果当成所有平台的固定文本。文件系统、挂载方式和运行用户都会影响底层错误；调用方应依赖标准错误语义，必要时把未知错误单独计数，而不是强行归类。

最后可以把规则压缩成一句话：先用 errors.Is 做语义分类，再用 errors.As 补充 PathError 诊断字段，任何无法确认的情况都保留原始错误交给上层。

常见问题

为什么不直接判断 os.IsNotExist？

os.IsNotExist 仍可用于兼容旧代码，但新代码更适合统一使用 errors.Is(err, fs.ErrNotExist)，这样能明确表达错误包装链的语义。

权限问题一定会被识别成 fs.ErrPermission 吗？

只有底层错误被标准库映射为权限拒绝时才会匹配。若是挂载失效、I/O 或其它平台特定问题，应进入其它错误分支并保留原始错误。

Stat 成功后还需要检查权限吗？

需要区分“能获取元数据”和“后续读写一定成功”。Stat 成功只说明这次元数据查询成功，后续操作仍可能因权限、竞态或文件类型不同而失败。

参考资料：https://pkg.go.dev/os#Stat；https://pkg.go.dev/os#PathError；https://pkg.go.dev/errors#Is。