项目本地运行时，assets/templates/index.html 明明就躺在仓库目录里，打包后的 Go 服务却返回 open templates/index.html: file does not exist。这类问题基本不是文件没被打进二进制，而是把 embed.FS 的虚拟路径、fs.Sub 的新根目录和进程工作目录混成了同一个概念。

排查这类路径异常不用反复猜斜杠，先把三个根的边界理清，绝大多数情况一次就能定位到根源。

下面用一个只有几份模板的小实验把这三个边界拆开。先让错误复现，再用目录检查和单元测试把规则固定下来，排查时会比反复改相对路径快很多。

先准备一棵能复现问题的内嵌目录

在空目录中创建以下文件。为了让路径含义明显，模板故意放在两级目录下：

embed-demo/
├── main.go
└── assets/
    └── templates/
        └── index.html

assets/templates/index.html 的内容可以写得很简单：

embedded page

在 main.go 中声明内嵌目录，并先打印文件系统看到的路径：

package main

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

//go:embed assets
var embedded embed.FS

func main() {
    entries, err := fs.Glob(embedded, "assets/templates/*.html")
    if err != nil {
        panic(err)
    }
    fmt.Println(entries)
}

这里的 fs.Glob 只接受使用正斜杠的虚拟路径。即使在 Windows 上编译，assets\\templates\\*.html 也不是推荐写法。

为什么文件在二进制里，读取却仍然失败

最容易踩中的错误是先切了子文件系统，却仍然使用旧的完整路径：

package main

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

//go:embed assets
var embedded embed.FS

func readWrong() {
    templates, err := fs.Sub(embedded, "assets")
    if err != nil {
        panic(err)
    }

    // 错误：templates 的根已经是 assets。
    body, err := fs.ReadFile(templates, "assets/templates/index.html")
    fmt.Printf("body=%q err=%v\n", body, err)
}

fs.Sub 返回的是一个新的 fs.FS 视图。它把 assets 从可见路径中移走，所以正确路径是 templates/index.html：

func readRight() ([]byte, error) {
    templates, err := fs.Sub(embedded, "assets")
    if err != nil {
        return nil, err
    }
    return fs.ReadFile(templates, "templates/index.html")
}

这时别急着调整当前启动目录。embed.FS 里的文件已经编译进程序，os.Getwd() 只能说明进程从哪个文件夹启动，不能改变内嵌文件的虚拟根。

用一个检查表区分三种根目录

排查时可以把“磁盘目录”“完整内嵌路径”“子文件系统路径”并排对照：

如果日志只打印了 file does not exist，建议同时打印传给 fs.ReadFile 的路径和调用前后的文件系统变量名。很多时候，错误不在文件内容，而在这一步把两个根拼接了两次。

把读取逻辑固定成可测试的函数

生产代码通常不需要把整个 embed.FS 暴露出去。可以在初始化阶段完成一次 fs.Sub，后续只接受子根下的相对路径：

package page

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

//go:embed assets
var files embed.FS

var pages, _ = fs.Sub(files, "assets")

func ReadTemplate(name string) ([]byte, error) {
    if name == "" {
        return nil, fmt.Errorf("empty template name")
    }
    return fs.ReadFile(pages, name)
}

如果初始化错误不能被忽略，可以把 fs.Sub 放进 NewStore，返回错误后再启动 HTTP 服务。这里的关键不是封装形式，而是让“子根下的路径约定”只有一个统一入口。

运行检查：从仓库根目录和临时目录各跑一次

先在项目根目录执行：

go run .
go test ./...

然后把生成的程序复制到临时目录再启动。若代码走的是 embed.FS，读取结果不应因为当前目录改变而变化；若代码偷偷退回了 os.ReadFile，这一步通常会立刻暴露问题。

还可以给读取函数补一个最小测试：

func TestReadTemplate(t *testing.T) {
    got, err := ReadTemplate("templates/index.html")
    if err != nil {
        t.Fatal(err)
    }
    if !bytes.Contains(got, []byte("embedded page")) {
        t.Fatalf("unexpected template: %q", got)
    }
}

测试名称里直接写出 templates/index.html，以后有人调整 fs.Sub 的根时，失败信息会比“模板加载失败”更有指向性。

模板解析时别把 fs.FS 换回 os.File

如果使用 html/template，可以让模板包直接消费 fs.FS：

tmpl, err := template.ParseFS(pages, "templates/*.html")
if err != nil {
    return err
}
// 将 tmpl、w 和 data 交给项目现有的模板渲染封装。

这样模板匹配、嵌入路径和运行目录彼此独立。项目已有渲染封装时，把解析好的 tmpl 交给它即可。只有确实要读取用户上传的文件、热更新目录或运维挂载目录时，才使用 os.ReadFile；那是磁盘文件，不是 embed.FS 的替代入口。

常见问题

fs.Sub 找不到目录时，最先检查什么？

先用 fs.WalkDir 或 fs.Glob 打印原始 embed.FS 的路径，再确认 //go:embed 声明覆盖了目标目录。不要先改工作目录。

Windows 路径分隔符会影响 embed.FS 吗？

会。io/fs 的路径约定使用斜杠，代码和模板匹配表达式应写成 assets/templates/index.html，不要拼接系统文件分隔符。

为什么本地 go run 正常，部署后却失败？

常见原因是本地代码读取了磁盘模板，部署包里没有复制同一目录。把资源真正嵌入后，用“改变工作目录再启动”的方式做一次回归测试，能快速区分两种实现。

最后留一条路径约定

内嵌资源的排查顺序可以固定成一句话：先确认 //go:embed 覆盖范围，再确认当前 fs.FS 的根，最后检查传入的相对路径。只要 fs.Sub 后不重复拼接父目录，并且读取始终走 io/fs，这类“文件在项目里却找不到”的问题通常就能在几分钟内定位。