Go filepath.EvalSymlinks 返回错误时怎么区分原因

filepath.EvalSymlinks 返回错误时，最稳妥的做法不是比较完整错误字符串，而是先用 errors.Is 判断可处理的语义，再用 errors.As 取出 *fs.PathError 的操作、路径和底层原因。这样可以把“路径不存在”“权限不足”“中间组件不是目录”和“符号链接结构异常”分开处理。

官方文档：https://pkg.go.dev/path/filepath

我在排查这类问题时会把错误拆成两层：上层只关心是否可以重试、提示用户或跳过；底层保留 Go 错误链中的标准原因和失败路径。不要把一行日志里的文字当成稳定 API。

先确认 EvalSymlinks 的返回契约

EvalSymlinks 返回解析符号链接后的路径，并对结果执行 Clean。传入相对路径时，结果通常仍相对于当前工作目录；如果某个符号链接指向绝对路径，结果可能转到绝对路径。第二个返回值是 error，任何一个路径组件无法被正确解析，都可能让结果为空并返回错误。

package main

import (
    "fmt"
    "path/filepath"
)

func resolve(path string) (string, error) {
    // 解析链接只负责得到目标路径，不在这里猜测错误文字。
    resolved, err := filepath.EvalSymlinks(path)
    if err != nil {
        return "", err
    }
    // 调用方拿到的是清理过的解析结果，仍应按自己的业务边界使用。
    return resolved, nil
}

func main() {
    resolved, err := resolve("config/current.yaml")
    if err != nil {
        fmt.Println("resolve failed:", err)
        return
    }
    fmt.Println(resolved)
}

这个示例只说明接口边界，代码中的路径和输出不是本文制作过程中的执行记录。要判断失败原因，继续沿着错误链检查，而不是只打印 err.Error() 后做字符串包含判断。

用 errors.Is 判断可处理的原因

文件系统类错误通常会包装 fs.ErrNotExist、fs.ErrPermission 等可比较的语义值。errors.Is 会沿着 Unwrap 链查找匹配项，因此比 err == fs.ErrNotExist 更适合处理被 PathError 包装的结果。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "path/filepath"
)

func classify(path string) string {
    // EvalSymlinks 可能把底层文件系统错误包装在 PathError 中。
    _, err := filepath.EvalSymlinks(path)
    if err == nil {
        return "ok"
    }

    // 使用标准原因做分支，避免依赖不同系统的错误文本。
    switch {
    case errors.Is(err, fs.ErrNotExist):
        return "missing"
    case errors.Is(err, fs.ErrPermission):
        return "permission-denied"
    default:
        return "other-filesystem-error"
    }
}

func main() {
    fmt.Println(classify("config/current.yaml"))
}

“不存在”不只代表最后一个文件名不存在，也可能是某个链接目标不存在；“权限不足”同样可能发生在路径中间的目录。业务上可以对缺失做可选配置回退，对权限错误给出修复提示，但不要把所有 other 都当成可重试。

用 errors.As 读取 PathError 细节

标准库文件操作的错误常以 *fs.PathError 表示。它记录操作名 Op、失败路径 Path 和底层错误 Err。用 errors.As 取出它后，日志可以指出“在哪个路径、哪种操作失败”，上层仍然用 errors.Is 判断原因。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "path/filepath"
)

func explain(path string) error {
    // 保留原始错误，调用方可以继续用 errors.Is 检查标准原因。
    _, err := filepath.EvalSymlinks(path)
    if err == nil {
        return nil
    }

    var pathErr *fs.PathError
    if errors.As(err, &pathErr) {
        // Path、Op 和底层 Err 比完整字符串更适合结构化日志。
        fmt.Printf("op=%s path=%s cause=%v\n", pathErr.Op, pathErr.Path, pathErr.Err)
    }
    return err
}

func main() {
    _ = explain("config/current.yaml")
}

这里不要把 PathError.Err 直接强转成某个系统专属类型后当成跨平台协议。对通用代码，优先比较 fs.ErrNotExist、fs.ErrPermission；只有确实需要平台级诊断时，才在对应平台代码中解释更细的底层错误。

单独处理链接结构问题

如果 errors.Is 没有命中“不存在”或“权限”，还要检查路径结构。路径中间的普通文件不能继续作为目录；符号链接目标可以是相对路径，也可以是绝对路径；链接之间互相指向，或者解析过程中链接数量过多，也会失败。Go 标准库源码对解析过程维护了已走过的链接数量，超过上限时返回特定错误。

不要用 os.Stat 先把所有组件查一遍，再假设后面的 EvalSymlinks 一定成功：两次检查之间文件系统可能变化，而且预检查本身无法替代最终解析。需要判断某个路径最后一项是不是符号链接时，另用 os.Lstat，它不会跟随最后的链接。

封装面向调用方的错误模型

文章标题问的是“怎么区分原因”，实际工程里还要决定谁负责动作。底层函数应该返回原始错误或包一层带上下文的错误；服务层把它映射成可观测的分类；界面或任务调度层再决定提示、跳过、修复还是终止。

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "path/filepath"
)

func resolveConfig(path string) (string, error) {
    // 用 %w 保留错误链，让上层仍能 errors.Is / errors.As。
    resolved, err := filepath.EvalSymlinks(path)
    if err != nil {
        return "", fmt.Errorf("resolve config %q: %w", path, err)
    }
    return resolved, nil
}

func main() {
    resolved, err := resolveConfig("config/current.yaml")
    if err != nil {
        // 先识别稳定原因，再决定提示或回退策略。
        if errors.Is(err, fs.ErrNotExist) {
            fmt.Println("可使用默认配置")
        } else if errors.Is(err, fs.ErrPermission) {
            fmt.Println("请检查运行用户的目录权限")
        } else {
            fmt.Println("请检查符号链接结构")
        }
        return
    }
    fmt.Println("resolved:", resolved)
}

这里的错误分类不是让底层函数吞掉错误。相反，%w 保留了错误链，日志也可以另行通过 errors.As 取得 PathError。如果调用方需要区分更多业务状态，可以定义自己的错误类型，但不要丢弃底层原因。

排查时的取舍清单

• 先调用 errors.Is 检查 fs.ErrNotExist、fs.ErrPermission 等稳定语义。
• 再用 errors.As 读取 *fs.PathError，记录 Op 和 Path。
• 对未识别错误保留原值，不用字符串替换把循环链接伪装成缺失文件。
• 路径检查和最终解析之间可能发生变化，不能把预检查当成锁。
• 跨平台代码依赖 fs 的通用原因，平台特有错误放进平台分支。

常见问题

为什么不能直接写 err == fs.ErrNotExist？

因为文件系统操作常把底层原因包装在 PathError 中。用 errors.Is 才会沿错误链查找匹配的标准原因。

EvalSymlinks 会把相对路径变成绝对路径吗？

不一定。官方契约是相对输入通常保持相对结果，但遇到指向绝对位置的符号链接时，结果可能转为绝对路径。需要绝对路径时，应把这一要求作为单独的路径策略处理。

如何知道是哪个组件出错？

先用 errors.As 取得 *fs.PathError 并查看 Path、Op 和 Err；若还不足以定位，再结合业务记录的输入路径和链接拓扑排查。

遇到链接循环是否应该重试？

通常不应该。循环和链接数量过多是路径结构问题，重试不会改变拓扑；应修复链接关系或更换输入路径。

归纳起来，EvalSymlinks 的错误处理顺序可以固定为：用 errors.Is 识别稳定原因，用 errors.As 补齐失败位置，最后把未识别的原始错误交给上层决定。这样既保留了 Go 标准库的错误语义，也不会把跨平台排障绑死在某一段英文错误文字上。