Go embed pattern 无匹配文件的目录修复

Go embed pattern 无匹配文件时，应先按包含指令的 Go 源文件所在包目录重新定位资源。确认真实产物在编译前已经到位，再判断模式是否覆盖这些文件。只新建空目录、改变程序运行目录，或把模式改成上级相对路径，通常不能解决问题。

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

模式命名：把静态资源交给所属包

我会把这种目录安排称为“包内资源契约”：哪个包声明嵌入资源，构建输入就由哪个包负责。假设项目将资源接口放在 internal/webassets/assets.go，首页产物就安排在 internal/webassets/dist/index.html。dist 是这个包的子目录，不是任意一个名为 dist 的仓库目录。

这是一个原创项目布局示例，并非本文工作目录的实际构建记录。采用这个模式的好处是审阅者只看资源包，就能理解二进制依赖哪些静态文件。相应代价是前端产物复制和生成位置也必须遵守同一约定。

适用压力：先找到模式的相对目录

embed 模式以源文件所属的包目录为基准，而不是执行 go build 的终端当前目录。因而在仓库根目录编译时，assets.go 里的 dist 仍然对应 internal/webassets/dist。

排查时先写出三个实际位置：指令文件、它所在的包、期望的产物。若前端工具输出到仓库根目录的 dist，Go 包却在 internal/webassets，两者就没有对齐。此时应选择把产物复制到资源包，或把资源声明移到合适的所属包，再由其他包调用其接口。

下面是阅读者可用于自己项目的查看与编译命令。路径来自上述示例，本文没有执行这些命令，也没有附运行输出。

# 从模块根目录查看资源所属包；按项目调整这个示例路径。
ls -la internal/webassets
ls -la internal/webassets/dist

# 资源恢复后编译所属包；这不是前端产物生成命令。
go build ./internal/webassets

典型实现：包内保留可匹配的真实资源

示例布局为：模块根目录有 go.mod；internal/webassets 下有 assets.go 与 dist/index.html。index.html 应是业务需要的真实首页或明确设计的最小首页，而不是为了让构建通过随意添加的占位文件。

package webassets

import (
    "embed"
    "fmt"
)

// 资源位于本文件所在包的 dist 目录，构建前必须已经存在。
//go:embed dist
var files embed.FS

// Index 读取嵌入文件系统内的路径，不访问运行目录的文件。
func Index() ([]byte, error) {
    data, err := files.ReadFile("dist/index.html")
    if err != nil {
        return nil, fmt.Errorf("读取内置首页: %w", err)
    }
    return data, nil
}

源码中的 dist 是编译时匹配模式，ReadFile 中的 dist/index.html 是嵌入文件系统内的读取路径。两者职责不同：模式成功并不意味着任意读取名称都存在。将声明从 dist 改成某个单文件路径时，也要重新核对调用方使用的名称。

示例只提供读取首页的包接口，没有建立 HTTP 服务，也没有声称前端资源已经可用。实际应用还应考虑脚本、样式、字体等依赖是否都由前端产物提供；能读首页不等于页面依赖齐全。

反例：空目录、隐藏文件和上级路径

每条模式都必须有有效匹配，空目录不会成为可嵌入内容。模式使用正斜杠，不能通过 .. 越过包目录；符号链接或独立模块也不能作为普通包内文件处理。这些约束下，应修复资源归属，而不是不断尝试更长的路径。

另一个容易混淆的点是目录遍历与通配符匹配。目录模式默认跳过点号或下划线开头的项，all: 可改变这项遍历规则；通配符直接匹配隐藏项的行为并不等同于目录模式。因此不能笼统地说“embed 永远忽略隐藏文件”。

如果只是 .gitkeep 留住目录，而真正的前端构建没有发生，修改匹配策略会把问题掩盖成“构建成功但缺少页面”。我更愿意让必要首页缺失直接暴露出来，而不是引入与产品无关的占位内容。这是对示例项目的设计取舍，不是 embed 强制所有项目采用的文件名规则。

后果：生成产物必须先于编译到位

嵌入的是编译时已有内容。前端生成器、产物复制规则、构建上下文与 Go 编译共同组成输入契约：前端生成器写出真实文件，复制规则将它们交给资源包，构建上下文必须包含该包和产物，Go 编译才有可用输入。

若使用 go generate 管理生成步骤，应显式运行它；go build 不会自动替你执行生成指令。对于由其他构建工具生成的 dist，也应在流水线里明确对应命令，不能假设某位开发者本地已有的目录会自然出现在干净环境。

以容器构建为例，仓库里存在文件仍不等于构建上下文中存在：复制规则和忽略配置可能让产物没有进入目标阶段。修复时要对照同一份目录契约，确认资源包收到的是本次预期产物，而不是上一次开发留下的文件。

如果业务要求资源在部署后独立更新，可以选择外部资源加载方案，并另行设计路径配置与缺失处理。embed 更适合希望资源随二进制一起发布的场景；不要为了消除一条构建错误而悄悄改变部署契约。

判断清单与相关问答

完成目录修复后，应能回答：指令属于哪个包，产物由谁生成，产物放在哪里，干净构建如何获得它，以及读取接口使用什么内部路径。把这些答案写入项目构建说明，可减少“本机有文件、流水线没有”的反复排障。

一个指令写了多个模式，其中一个没匹配能否忽略？

不能把另一模式的成功匹配当作补偿。逐条检查模式是否指向必要且存在的资源，删除确实已经取消的资源要求，而不是保留失效模式。

重新部署目录后，旧二进制会读到新文件吗？

本文接口读取内嵌内容。要更新这部分资源，需要生成包含新资源的二进制；外部目录变动不会改写已嵌入内容。

为什么本机成功而干净环境失败？

优先对比真实产物、复制规则与构建输入。尤其检查前端产物是否只存在于本机，以及忽略配置是否漏掉应交付的文件。

资料：embed 模式与目录规则；go generate 的显式执行规则。