Go embed FS 打开不存在资源时怎样保留错误上下文

Go embed.FS 读取不存在的资源时，应保留资源逻辑路径与底层错误，再用 errors.Is(err, fs.ErrNotExist) 判断缺失，用 errors.As 获取 *fs.PathError。在读取前用 fs.ValidPath 区分非法路径形式；模板读取成功后若解析失败，应记录为另一阶段，不要统一改成“模板不存在”。

设想应用启动时加载一个内嵌卡片模板：路径写错、文件没装入构建和模板语法损坏都会阻止加载，但处理动作不同。下面做一个小项目，让四种输入经过同一加载函数，以类型和错误链保留上下文，不靠错误文字猜原因。

官方文档：https://pkg.go.dev/embed、https://pkg.go.dev/io/fs#ValidPath、https://pkg.go.dev/errors。

先明确日志需要保留哪些上下文

这里的 资源名 是 embed 文件系统内部的名字，不是当前工作目录里的磁盘路径。AssetError 保存 name 与 stage，底层可能是 PathError，也可能是模板解析错误。业务再包装一层“初始化卡片模板”，不应该丢掉前面的结构化信息。

如果只写 fmt.Errorf("加载失败：%v", err)，底层错误只是变成文字，调用方无法依靠这一层继续解包。简单补充文字可用 %w；需要长期保留阶段字段时，可定义带 Unwrap 的错误类型。本文把两种方式结合起来，不要求调用方解析一整段错误字符串。

准备两个确实能匹配构建模式的模板

创建 main.go 和 templates 目录，目录中只需两个文件。不要创建 missing.tmpl，它是运行时缺失案例。embed 模式 templates/*.tmpl 至少有实际匹配，示例才能进入运行时读取分支。若构建期模式本身匹配不到文件，那是构建错误，不是程序运行后返回 ErrNotExist。

templates/card.tmpl：

{{/* 正常模板样本，仅用来观察加载与解析。 */}}
{{.Title}}

templates/broken.tmpl：

{{/* 故意缺少 end，构造解析失败案例，不是生产模板。 */}}
{{if .Title}}标题存在

内嵌文件保存的是原始文本，构建 embed 不替你检查模板语法。broken.tmpl 能被嵌入但后续 Parse 会遇到语法问题，这正好区分构建收集与模板解析两层职责。

给读取与解析各留一层明确的阶段

main.go 内容如下。为了让错误归属清楚，示例先 ReadFile，再 Parse。ReadFile 在这里用于读取小型内嵌资源，避免手工 Open 后漏掉 Close；如果改为 Open 流式读取，文件关闭责任需另外安排。

package main

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

// 资源在构建时装入，运行时使用 FS 内部逻辑路径。
//go:embed templates/*.tmpl
var resources embed.FS

type AssetError struct {
    Stage string
    Name string
    Err error
}

func (e *AssetError) Error() string {
    return fmt.Sprintf("模板资源 %q 阶段=%s: %v", e.Name, e.Stage, e.Err)
}

// 保留底层错误，使 Is 和 As 可以继续分类。
func (e *AssetError) Unwrap() error { return e.Err }

func load(name string) (*template.Template, error) {
    if !fs.ValidPath(name) {
        // 由应用明确标记路径不合法，不混同资源不存在。
        return nil, &AssetError{"path", name, fs.ErrInvalid}
    }
    data, err := resources.ReadFile(name)
    if err != nil {
        return nil, &AssetError{"read", name, err}
    }
    t, err := template.New(name).Parse(string(data))
    if err != nil {
        return nil, &AssetError{"parse", name, err}
    }
    return t, nil
}

func main() {
    names := []string{
        "/templates/card.tmpl",
        "templates/missing.tmpl",
        "templates/broken.tmpl",
        "templates/card.tmpl",
    }
    for _, name := range names {
        _, err := load(name)
        if err == nil {
            fmt.Printf("%q 加载并解析成功\n", name)
            continue
        }

        // 再加一层业务上下文，仍用 %w 保留错误链。
        err = fmt.Errorf("初始化卡片模板: %w", err)
        var assetErr *AssetError
        if errors.As(err, &assetErr) {
            fmt.Printf("stage=%s name=%q\n", assetErr.Stage, assetErr.Name)
        }
        switch {
        case errors.Is(err, fs.ErrInvalid):
            fmt.Println("分类：路径形式不合法")
        case errors.Is(err, fs.ErrNotExist):
            fmt.Println("分类：内嵌资源不存在")
        case assetErr != nil && assetErr.Stage == "parse":
            fmt.Println("分类：模板解析错误")
        default:
            fmt.Println("分类：其他加载错误")
        }
        var pathErr *fs.PathError
        if errors.As(err, &pathErr) {
            // 只读底层字段，不靠解析错误字符串提取路径。
            fmt.Printf("op=%q path=%q\n", pathErr.Op, pathErr.Path)
        }
        fmt.Println(err)
    }
}

fs.ValidPath 的结果不代表路径一定存在。绝对形式 /templates/card.tmpl 被这个应用主动归为 fs.ErrInvalid；合法但缺失的 templates/missing.tmpl 则保留 ReadFile 返回的底层错误。parse 阶段的错误原样放进 AssetError，调用方不会把所有加载失败都分类为缺失。

errors.As 的目标写法是先声明 var assetErr *AssetError 再传 &assetErr。只有匹配成功后才直接访问结构字段；这里对后续判断也做了 nil 检查。不要对原始 err 直接做类型断言，因为业务包装层可能已经在最外面。

运行时观察分类，不复制固定错误文字

# 在示例目录初始化模块，只需执行一次。
go mod init example.com/embed-context
# 两个模板文件准备好后，运行完整包。
go run .

命令供读者自行执行，本文没有运行示例或制作测试日志。按代码逻辑，四项分别应落到路径形式不合法、资源不存在、模板解析错误和加载解析成功。请观察 stage 与资源名是否保留，不必要求底层报错文字与本文某个固定字符串一致。

这个程序只加载与解析，不执行模板。成功解析并不保证后续 Execute 的数据符合预期；执行阶段若需要上下文，应另行记录，而不是归入 read 或 parse。示例中的多个错误用于展示分类，实际应用必须按资源是否必需决定终止启动还是使用明确的替代策略，不能只打印后假装初始化成功。

合法 FS 路径不等于磁盘路径，也不等于存在

FS 路径使用 / 分隔。空路径、前导或末尾 /、空路径段、. 或 .. 路径段都不符合一般有效路径形式；单独的 "." 是根目录特例。ValidPath 允许部分其他字符，例如反斜杠和冒号，但不能把它们当路径分隔符。因此 Windows 路径写法也不能直接当 embed 路径。

不要先无条件清理用户路径，把 "../templates/card.tmpl" 变成另一个合法名字，再声称原始输入有效。这里直接判断输入，方便保留真正失败的资源名。若业务要允许根目录、目录读取或别名转换，需要在自己的 API 中明确，而不是从 ValidPath=true 推导“这是可解析模板”。

embed.FS、资源名 与 fs.ValidPath 是读取边界；模板文本 与 Parse 是内容边界。部署后往磁盘 templates 目录添加文件，不会自动更新已构建的 embed 资源，修改资源需要重新构建相应程序。

几种容易丢失上下文的写法

用 ParseFS 就不需要包错误了吗？仍需保留业务上下文。ParseFS 使用文件匹配模式，匹配阶段错误与 ReadFile 单个路径错误不应混为一谈；本文主动分开读取与解析，让错误阶段更容易识别。

大小写不同的资源名能自动匹配吗？不要依靠部署文件系统的大小写行为，使用实际嵌入的精确逻辑名字。

需要把完整上下文返回网页用户吗？内部保留足够诊断字段，外部响应可按应用规则简化；不要为隐藏细节而在内部把底层错误链也一并丢弃。

这个小项目最终保留的是三个互补维度：调用场景、资源名与失败阶段，以及可解包的底层原因。资源缺失才去查构建输入和名字，解析错误才去查模板文本，这比统一输出一个“加载失败”更有行动价值。