Go embed 模式匹配不到文件为什么为空

Go 的 go:embed 读不到文件时，先不要把“空”都归因于模式语法。最常见的原因有三类：embed.FS 根本没有被指令初始化；模式是相对包含指令的 Go 源文件所在包目录解析的；目录递归默认排除名称以 . 或 _ 开头的文件。官方文档还规定，每个模式至少要匹配一个文件或非空目录，因此真正的“完全不匹配”通常会在构建阶段直接失败，而不是悄悄返回空集合。

官方地址：https://pkg.go.dev/embed

先分清“空 FS”和“模式不匹配”

下面两种情况的表现容易混在一起。第一种是变量声明为 embed.FS，但上面没有紧邻的 //go:embed 指令；官方定义是它保持为空。第二种是指令确实存在，但模式没有命中目标资源。后者如果是一个明确的文件模式，通常会让构建失败，因为编译器要求每个模式至少命中一个文件或非空目录。

package main

import (
    "embed"
    "fmt"
)

// assets 只有在紧邻的 go:embed 指令匹配到资源后才会包含文件。
//go:embed assets
var assets embed.FS

func main() {
    // 根目录读取用于观察当前嵌入集合，不代表磁盘目录。
    entries, err := assets.ReadDir(".")
    if err != nil {
        // 先打印错误，避免把“读取失败”误判为“没有文件”。
        panic(err)
    }
    fmt.Println("嵌入条目数量:", len(entries))
}

如果只看到数量为零，优先检查是否把 embed.FS 当成了磁盘目录，或者声明时漏掉了指令。若构建阶段提示模式没有匹配项，则应回到文件树和包目录检查，而不是在运行时追加路径。

模式要从声明文件所在包目录开始计算

//go:embed 的模式不是相对于命令执行目录，也不是相对于模块根目录，而是相对于包含这条指令的 Go 源文件所在包目录。假设目录如下：

project/
├── go.mod
└── internal/site/
    ├── embed.go
    └── assets/
        └── index.html

此时 embed.go 中应该写 assets/index.html 或 assets。如果把它写成 internal/site/assets/index.html，就等于从 internal/site 再向下寻找同名层级，路径自然不对。路径分隔符统一使用正斜杠，不能用运行平台的磁盘路径习惯替换。

package site

import (
    "embed"
    "fmt"
)

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

func main() {
    // ReadFile 的名字同样相对嵌入文件系统根目录。
    data, err := files.ReadFile("assets/index.html")
    if err != nil {
        // 嵌入路径和磁盘路径是两套命名空间，错误要单独处理。
        panic(err)
    }
    fmt.Println("HTML 字节数:", len(data))
}

读取时也不要把本机绝对路径传给 ReadFile。它接收的是嵌入集合内的斜杠路径；即使真实文件位于某个磁盘目录，运行时也不再按那个绝对路径打开。

检查指令位置、变量类型和目录边界

指令必须紧邻一个包级变量声明，中间只能有空行或普通 // 注释；不能放在函数内部，也不能让一条指令跨过其他声明。变量类型必须是 string、[]byte 或 embed.FS（及其别名）。单文件模式用于字符串或字节切片时只能匹配一个文件，目录树则使用 embed.FS。

package config

import _ "embed"

//go:embed defaults.json
var defaults []byte

// 读取配置时使用独立副本，调用方可以按自己的生命周期处理数据。
func defaultConfig() []byte {
    return append([]byte(nil), defaults...)
}

另一个容易忽略的边界是目录里的隐藏文件。直接写 assets 时，目录递归会排除名称以点号或下划线开头的文件；assets/* 与目录模式的规则也不完全相同，不能用一个通配符替代所有场景。需要把这些文件也纳入时，可写成 all:assets，但仍要保证它们在当前包和模块允许的范围内。

用目录模式和 go list 判断实际匹配结果

把排查拆成两个问题会更快：模式选择了哪些资源，运行时代码又从哪个嵌入路径读取。前者可以让 Go 工具列出 EmbedPatterns；后者用 ReadDir、ReadFile 的返回值和错误做判断。不要先运行程序，再根据当前工作目录猜测嵌入来源。

# 在模块根目录查看包识别到的 embed 模式。
go list -json ./internal/site

# 只从输出中关注 EmbedPatterns、TestEmbedPatterns 等字段。
go list -json ./internal/site | grep -E 'EmbedPatterns|TestEmbedPatterns|XTestEmbedPatterns'

这里的命令输出是检查线索，不是把运行目录改成资源目录。若模式字段没有出现，回到包文件确认指令是否紧邻变量；若字段存在但读取失败，检查 ReadFile 使用的嵌入路径是否包含正确的相对目录。

常见问题

go:embed 模式完全不匹配时会静默返回空吗？

通常不会。每个模式必须至少匹配一个文件或非空目录，明显的不匹配应在构建阶段暴露。运行时看到空集合，更像是 FS 未被指令初始化，或目录规则排除了你关注的文件。

为什么把项目根目录写进模式后反而找不到文件？

因为模式从声明指令的源文件所在包目录开始解析。包目录已经是相对起点，再重复写上层目录名就会多出一层路径。

all: 能解决所有匹配问题吗？

不能。它只改变目录递归时对点号和下划线文件的包含规则，不能修复错误的包目录、变量类型、指令位置或 ReadFile 路径。