Go os.Lstat 返回错误时怎么区分原因

Go 的 os.Lstat 返回错误时，用 errors.Is 判断不存在、权限不足等原因，用 errors.As 取出 *fs.PathError 的操作与路径信息。两者解决不同问题：前者决定程序怎样处理，后者帮助解释失败发生在哪里。没匹配到已知原因的错误必须保留，不能统一当成“不存在”。

官方地址：https://pkg.go.dev/os#Lstat

把“原因分类”与“诊断上下文”分开

设想一个文件清单工具：它展示用户传入的路径，失败时标记原因。最早的实现只输出一个“文件不存在”，后来接入受限目录，同样的提示开始误导用户去重新创建文件。这里适合引入一个很小的模式：底层返回可追溯的错误，上层再把错误映射成业务标签。

这个模式不需要单独建立复杂的错误框架。保留一条原始错误链，维护几个清晰的标签，就能把“如何展示”和“怎样诊断”分开。missing、permission、invalid、other 是本文工具自己约定的分类名，不是操作系统返回的固定字符串。

先明确：要查目录项，还是链接目标

Lstat 描述末端目录项本身。末端为符号链接时，它不会为了取得该目录项的信息而跟随到目标。因此，链接本身可以存在，而目标已经缺失；这时查询链接的 Lstat 可以成功。只有业务确实关心目标信息时，才考虑另一次 os.Stat，并独立处理那次调用的错误。

“不跟随末端链接”不等于路径解析中所有父目录都不涉及链接，也不等于路径后续操作受到了保护。本文只处理一次元数据查询的错误，不把它包装成路径隔离方案。先确认对象语义，可以避免在错误分类层补救一个本来就问错的问题。

清单工具的需求是保留链接条目，所以这里选择 Lstat。它也不需要打开文件内容。读取元数据成功，不代表随后读取内容、遍历目录或写入文件一定成功。

一个保留错误链的最小实现

把下面代码保存成 main.go，可以作为单路径查询工具。inspectEntry 仅负责调用和补充操作语境，classify 仅负责原因分类；命令行入口将两份信息组合成可读输出。示例用于说明实现，本文未执行它，也不提供虚构的运行日志。

package main

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

// classify 只提炼原因，不丢弃调用方持有的原始错误。
func classify(err error) string {
    switch {
    case err == nil:
        return "ok"
    case errors.Is(err, fs.ErrNotExist):
        return "missing"
    case errors.Is(err, fs.ErrPermission):
        return "permission"
    case errors.Is(err, fs.ErrInvalid):
        return "invalid"
    default:
        return "other"
    }
}

func inspectEntry(name string) (fs.FileInfo, error) {
    info, err := os.Lstat(name)
    if err != nil {
        // 保留错误链，让上层仍能查询原因与 PathError。
        return nil, fmt.Errorf("inspect entry: %w", err)
    }
    return info, nil
}

func run(args []string) int {
    if len(args) != 1 {
        fmt.Fprintln(os.Stderr, "用法: entrycheck 路径")
        return 2
    }

    info, err := inspectEntry(args[0])
    if err != nil {
        fmt.Fprintf(os.Stderr, "kind=%s error=%v\n", classify(err), err)
        var pe *fs.PathError
        if errors.As(err, &pe) {
            // 命令行面向本机用户；服务端日志需另行限制路径暴露。
            fmt.Fprintf(os.Stderr, "op=%s path=%q cause=%v\n",
                pe.Op, pe.Path, pe.Err)
        }
        return 1
    }

    // 仅成功时读元数据，链接标志描述的是目录项本身。
    link := info.Mode()&fs.ModeSymlink != 0
    if _, err := fmt.Printf("name=%q symlink=%t mode=%s\n",
        info.Name(), link, info.Mode()); err != nil {
        fmt.Fprintln(os.Stderr, "写出结果失败:", err)
        return 1
    }
    return 0
}

func main() {
    os.Exit(run(os.Args[1:]))
}

关键点是 %w：它让增加一层说明后的错误仍然可查询。若只拼接错误文本，后续分类就失去可靠依据。errors.As 接收的是变量 pe 的地址；只有返回 true 时，才读取这个变量。这样即使外层新增包装，诊断处也不必假设最外层就是 PathError。

错误匹配文档：https://pkg.go.dev/errors

文件系统错误类型：https://pkg.go.dev/io/fs#PathError

invalid 不是“所有不合法路径”的总入口；实际返回取决于系统及文件系统。缺失类也不能仅凭标签断定是最后一级名字不存在。需要定位具体组成部分时，应结合路径、底层错误及当前运行环境，而不是从一个标签推演出完整故障现场。

三个反例：字符串、布尔值与先查后用

第一种反例是搜索错误文本中的英文短语。提示文字可能受平台、包装层和底层实现影响；它适合给人阅读，不适合成为业务协议。第二种是把所有非空错误转换成 exists=false。这会把权限失败、路径解析问题以及其他文件系统错误一起隐藏。

第三种是先 Lstat 成功，再假设随后的 Open 必然成功。两次操作之间目录项可能变化，且两个操作需要的条件也不同。真正要读文件时，应直接处理 Open 的错误；Lstat 只承担本次清单查询，不替未来操作提供成功承诺。

分类的收益与代价

收益是调用方不再依赖系统提示文本，错误展示也能保持一致。代价是分类一定有损：other 可能包含多个完全不同的底层原因，permission 也不说明应该修改哪个具体权限。因此，本例同时保留标签和原始错误，而没有让标签替代全部诊断信息。

如果系统只部署在一种操作系统，确实需要区分更具体的错误，可以在平台专用文件中增加底层错误判断，并保留兜底分支。不要把某个平台的错误编号当作所有平台共享的接口，也不要把无法归类理解成“可以安全忽略”。本例没有自动重试；只有业务了解失败是否可能恢复、重复操作是否合适时，才设计重试策略。

落地判断清单与相关问题

• 先说明业务查询的是末端目录项还是链接目标。
• 先处理非空错误，再访问 FileInfo 的方法。
• 把原因标签与 PathError 的操作、路径、底层原因分开保存。
• 包装错误时保留链路，未知原因保留原始错误。
• 不要把元数据查询成功转换成后续文件操作的保证。

为什么外层加了说明后，类型断言失败了？

直接断言只检查最外层具体类型。本文使用 errors.As 查询错误链，避免调用方依赖包装层数；分类则交给 errors.Is。

权限错误能否直接提示用户提权？

先核对运行身份、路径是否正确以及父目录访问条件。一个权限标签不足以判断应采用什么改动，更不应让程序自行扩大权限。

是否还可以用 os.IsNotExist？

旧代码中可以见到它；Go 文档对新代码建议使用 errors.Is 配合 fs.ErrNotExist。对于本文这种额外包装的错误入口，统一使用错误链匹配也更易维护。

链接目标缺失为什么没有进入 missing？

因为本次 Lstat 查询的是链接条目。目标是否可访问是另一个问题；不要让同一个“存在”布尔值混合这两种含义。