Go embed.FS 读取不存在资源时怎么区分错误类型

用 embed.FS.ReadFile 读取内置资源时，最稳妥的做法不是比较错误字符串，而是先用 errors.Is(err, fs.ErrNotExist) 判断资源是否缺失，再用 errors.As 取出 *fs.PathError 的操作名和路径。这样“资源没打进包”“请求路径写错”和“其他读取失败”就不会被混成一个模糊的 404。

结论：缺失资源看 fs.ErrNotExist，错误细节看 *fs.PathError；不要依赖 err.Error() 的文字。

embed.FS 的错误要先看路径与底层类型

//go:embed 在编译期把匹配到的文件放进程序，embed.FS 对外实现的是 io/fs.FS。因此读取名不是操作系统绝对路径，而是相对资源树、使用斜杠分隔的路径。例如源码里嵌入了 static/index.html，读取时应传入 static/index.html，不能把工作目录拼进来。

这个边界解释了第一类常见问题：路径写错通常发生在运行时，模式没有匹配文件则会在构建阶段暴露。两者都可能让业务看到“找不到资源”，但处理位置不同，不能只在读取函数里补一个字符串判断。

用 errors.Is 区分不存在、非法路径与其他失败

读取函数可以把缺失资源当成可恢复分支，其余错误继续向上返回。errors.Is 会沿着包装链判断语义，比比较完整错误文本稳定；代码只关心“是不是不存在”，就不要强行断言具体错误结构。

package main

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

//go:embed static/index.html
var assets embed.FS

func readAsset(name string) ([]byte, error) {
    data, err := assets.ReadFile(name)
    if err == nil {
        return data, nil
    }
    // 缺失资源可以交给上层返回默认内容或 404，其余错误不能静默吞掉。
    if errors.Is(err, fs.ErrNotExist) {
        return nil, fmt.Errorf("资源不存在 %q: %w", name, err)
    }
    return nil, fmt.Errorf("读取嵌入资源 %q 失败: %w", name, err)
}

这里保留了 %w 包装，所以调用方仍然可以继续使用 errors.Is。如果资源服务需要把缺失映射成默认页面，可以在更外层处理；库函数本身应保留原始语义。

用 errors.As 读取 PathError 的诊断信息

当日志需要说明到底对哪个路径执行了什么操作，可以把错误提取为 *fs.PathError。它通常包含 Op、Path 和底层 Err，而 Unwrap 让错误仍能被 errors.Is 识别。

var pathErr *fs.PathError
if errors.As(err, &pathErr) {
    // Path 和 Op 用于定位输入，Err 用于保留底层错误语义。
    fmt.Printf("embed 操作=%s 路径=%s 原因=%v\n", pathErr.Op, pathErr.Path, pathErr.Err)
}

不要把 PathError.Err 的显示文本当作协议字段。对外分支仍优先使用 errors.Is；errors.As 只负责提取结构化诊断，避免日志里只剩一句“file does not exist”。

把错误分类交给正确的调用层

实际项目中可以在启动检查、模板加载和 HTTP 静态服务之间采用不同策略：启动阶段缺少关键模板应直接失败，用户请求的可选资源可以返回 404，而诊断日志统一保留路径和底层错误。核心原则只有一个：用错误语义做分支，用结构体做定位，用包装保留上下文。

常见问题

为什么不建议比较 err.Error()？

错误文本可能因包装层和实现变化而变化；errors.Is 比较的是错误语义，适合稳定分支。

embed.FS 读取路径可以以斜杠开头吗？

不应这样写。io/fs 使用相对、斜杠分隔的路径；从资源树根开始传入类似 static/index.html 的名字。

什么时候使用 errors.As？

当调用方需要记录操作名、资源路径或底层原因时使用；如果只需要判断是否缺失，errors.Is 就足够。