Go 嵌入静态资源后为什么 os.Stat 找不到它

如果资源已经通过 //go:embed 编进程序，os.Stat("static/index.html") 仍然可能返回“文件不存在”。原因通常不是资源没有打进二进制，而是 os.Stat 查询的是当前工作目录对应的磁盘文件系统；嵌入资源属于另一个只读的 embed.FS。把访问入口和路径层级改对即可。

先分清磁盘路径和嵌入文件系统

os.Stat 的接收者是操作系统文件系统，它会把传入字符串交给当前进程所在环境解析。程序从项目根目录启动时，os.Stat("static/index.html") 可能成功；换成容器、服务管理器或另一个工作目录后，它就会失败。//go:embed 的文件则在编译阶段写入程序，运行时应通过实现了 fs.FS 的变量访问。

package main

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

// assets 保存编译时嵌入的静态目录，运行时不再依赖磁盘目录。
//go:embed static
var assets embed.FS

func main() {
    const name = "static/index.html" // 路径相对于嵌入文件系统根目录。

    if _, err := fs.Stat(assets, name); err != nil {
        fmt.Println("嵌入资源不存在:", err)
    }
    if _, err := os.Stat(name); err != nil {
        fmt.Println("磁盘路径不存在:", err)
    }
}

上面两次检查不是同一件事。第一处检查二进制里的只读资源，第二处检查运行目录中的真实文件。生产程序只需要前者时，删掉第二处可以避免把“本地目录存在”误当成部署条件。

fs.ValidPath 为什么决定能不能读到文件

io/fs 使用统一的斜线路径表示文件名。fs.ValidPath 可以先拦截几类高频错误：空字符串、以斜杠开头的绝对形式、含有反斜杠的 Windows 写法，以及把目录名遗漏或重复拼接。嵌入目录为 static 时，正确名称一般是 static/index.html，而不是磁盘语义里的 /static/index.html。

func readEmbedded(fsys fs.FS, name string) ([]byte, error) {
    // 先检查 FS 约定的路径格式，再执行读取。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("无效的嵌入路径 %q", name)
    }
    // ReadFile 读取的是 fs.FS 中的逻辑名称，不是当前目录文件。
    return fs.ReadFile(fsys, name)
}

os.Stat 找不到时按三层路径排查

先看编译声明：//go:embed 的模式相对于声明它的包目录，不能越过模块边界；模式没有匹配到文件时，构建阶段就会报错。再看 FS 内部名称：嵌入一个目录通常会保留目录这一层，所以要用 static/index.html。最后看调用入口：传给 fs.Stat 的是 FS 和逻辑名称，传给 os.Stat 的只有磁盘路径。

可以把路径常量集中管理，避免 HTTP 路由、模板解析和文件读取各自拼出不同名称：

const indexPath = "static/index.html"

func hasIndex(fsys fs.FS) error {
    // 统一使用一个逻辑路径，避免路由前缀混入 FS 名称。
    info, err := fs.Stat(fsys, indexPath)
    if err != nil {
        return fmt.Errorf("检查嵌入入口: %w", err)
    }
    if info.IsDir() {
        return fmt.Errorf("嵌入入口是目录: %s", indexPath)
    }
    return nil
}

这段判断只说明“FS 中存在一个非目录节点”，并不替代模板语法或 HTTP 返回内容的检查。它的价值是先把路径边界固定下来，让后续错误不再混入工作目录差异。

发布包和测试环境该怎么保持一致

如果目标是单文件发布，启动脚本、容器工作目录和部署机器上都不应再准备一份同名静态目录。将资源随 Go 包编译后，程序通过 http.FS(assets)、template.ParseFS 或 fs.ReadFile 消费它们，发布包就不依赖外部目录。

测试时也要区分两种契约：路径解析测试可以使用 embed.FS 验证逻辑名称；需要验证磁盘文件时才使用 os.DirFS。不要因为本地测试目录存在，就把生产代码改回 os.Stat。

常见问题

为什么给 os.Stat 加上绝对路径还是不行？

绝对路径只会更明确地查询磁盘，不能访问二进制里的 embed.FS。应把资源名称传给 fs.Stat 或 fs.ReadFile。

embed.FS 读取时能不能使用反斜杠？

不要这样做。fs.FS 的路径按斜杠分隔，跨平台代码也应统一写成 dir/file.ext，并先用 fs.ValidPath 检查。

嵌入目录后为什么少写一层目录反而找不到？

目录名通常会成为 FS 的顶层节点。若模式是 static，读取名应先尝试 static/index.html；只有改变嵌入布局或显式使用子 FS 后，名称才会相应变短。

相关事实可对照 Go 官方的 embed 包文档、io/fs.ValidPath 以及 io/fs 包说明。记住一句话：os.Stat 查磁盘，fs.Stat 查 FS；先确认对象，再确认路径。