Go embed 怎样处理嵌入文件不存在的错误

我第一次把静态模板放进 Go 程序时，把“嵌入文件不存在”和“运行时读取路径不存在”当成了同一种错误，结果一直在代码里补 if err != nil，却解决不了构建阶段的失败。Go embed 的边界其实很清楚：//go:embed 的模式匹配不到文件，会让构建直接失败；只有已经成功嵌入到 embed.FS 后，再读取一个不存在的路径，才会返回运行期错误。

本文只讨论这个边界，以及可选资源怎样组织。官方文档：https://pkg.go.dev/embed、https://pkg.go.dev/io/fs。

先看错误发生在哪个阶段：构建日志里的 pattern ...: no matching files found 不能在运行时捕获；应用运行后读取缺失路径，则用 errors.Is(err, fs.ErrNotExist) 处理。

先分清构建期和运行期的不存在

这两个场景的处理入口完全不同。//go:embed 在编译时读取包目录下的文件，并把结果写入包级变量；每个模式至少要匹配一个文件或非空目录。匹配为空时，程序还没有生成可运行的二进制，自然也没有机会执行错误处理代码。

另一种情况是模式本身匹配成功，例如嵌入了 assets/*，但业务随后请求 assets/theme.css，而这个具体文件并不在嵌入集合中。这时 embed.FS.ReadFile 才会返回一个可判断的文件系统错误。

为什么 //go:embed 的缺失文件不能用 error 接住

我排查这类问题时会先检查三件事：源文件和资源目录是否属于同一个包目录、模式是否使用了相对路径、模式是否真的能匹配至少一个文件。模式不能写成以斜杠开头的绝对路径，也不能通过 .. 走出包目录；目录模式还会排除以点号或下划线开头的文件。

下面的声明只要 assets/index.html 不存在，失败点就在构建阶段，main 中的任何分支都不会运行：

package main

import _ "embed"

// 页面文件必须在编译时存在，否则 go build 直接失败。
//go:embed assets/index.html
var indexHTML []byte

func main() {
	// 这里不会处理嵌入失败；成功构建后 indexHTML 已经是内置内容。
	_ = indexHTML
}

如果资源是必需文件，这种失败反而是有价值的：它能在发布前暴露打包遗漏。若资源是可选的，就不要把“可能不存在的单个文件”直接写成唯一嵌入目标，而应让嵌入集合有一个稳定的基础文件，再把具体可选路径留给运行期判断。

用 embed.FS 处理运行期缺失路径

embed.FS 实现了 io/fs.FS，可以把一组静态文件作为只读文件系统交给代码。读取失败时不要比较错误字符串；用 errors.Is 判断 fs.ErrNotExist，并把其他错误继续返回，避免把路径错误、非法路径或未来的 I/O 问题都误当成“可选文件没有配置”。

package main

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

// 目录中至少放一个稳定文件，确保 embed 模式始终有匹配结果。
//go:embed assets/*
var assets embed.FS

// readOptional 读取可选资源；缺失时交给上层决定是否使用回退内容。
func readOptional(name string) ([]byte, bool, error) {
	data, err := assets.ReadFile(name)
	if err == nil {
		return data, true, nil
	}
	if errors.Is(err, fs.ErrNotExist) {
		// 这是预期的“没有该可选文件”，不是程序崩溃条件。
		return nil, false, nil
	}
	// 其他错误仍要保留，不能用字符串比较把它们吞掉。
	return nil, false, fmt.Errorf("读取嵌入资源 %q：%w", name, err)
}

调用方拿到三个结果后，可以明确区分“读到了内容”“文件不在嵌入集合”和“出现了其他错误”。这里的 name 应使用 fs.FS 约定的斜线路径，例如 assets/theme.css，不要混入磁盘上的绝对路径。

让可选资源不阻塞构建

一个比较稳的目录组织方式是保留一个必需的基础资源，例如 assets/default.txt，再把真正可选的主题文件放在同一个目录中。这样 assets/* 至少会命中基础文件；主题文件是否存在，交给运行期的 ReadFile 判断。

package main

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

// default.txt 是构建时保证存在的基础资源，theme.css 可以按部署内容选择是否提供。
//go:embed assets/*
var resources embed.FS

func loadTheme() ([]byte, error) {
	data, err := fs.ReadFile(resources, "assets/theme.css")
	if err == nil {
		return data, nil
	}
	if errors.Is(err, fs.ErrNotExist) {
		// 缺少主题时回到基础内容，业务仍可继续启动。
		return resources.ReadFile("assets/default.txt")
	}
	return nil, fmt.Errorf("加载主题失败：%w", err)
}

这个方案的重点不是“把所有缺失都忽略”，而是把必需资源和可选资源分开：基础文件缺失时让构建尽早失败，主题文件缺失时才使用明确的回退策略。这样既不会让线上请求因为一次可选读取而崩溃，也不会把真正的打包错误静默掉。

结论与常见问题

Go embed 的不存在错误可以按阶段记：模式匹配失败是构建配置问题，修改资源目录或 //go:embed 模式；embed.FS 读取缺失路径是运行期数据问题，用 errors.Is(err, fs.ErrNotExist) 分支处理。可选资源最好和一个保证存在的基础文件一起嵌入，再在读取层决定是否回退。

为什么给 //go:embed 加 error 变量没有用？

因为指令初始化发生在构建阶段，不是一个返回 error 的函数调用。模式没有匹配项时，构建工具会直接报错；只有构建成功后访问 embed.FS 中不存在的具体路径，才有运行期错误可处理。

读取不存在路径时为什么用 errors.Is？

文件系统通常返回带路径信息的错误包装，直接比较错误文本不稳定。errors.Is(err, fs.ErrNotExist) 保留了标准错误语义，也不会误吞其他错误。

目录里只有隐藏文件，为什么模式仍可能匹配不到？

普通目录模式会排除点号或下划线开头的文件。不要把隐藏占位文件当成唯一匹配项；放入一个明确的基础资源，或者按官方规则选择合适的 all: 前缀，并确认它确实属于你要发布的内容。