为前端资源建立开发期本地读取与发布期嵌入切换

开发 Go Web 服务时，前端文件放在项目目录里最方便修改；到了发布阶段，又希望只交付一个二进制，避免额外的静态目录丢失或路径配置漂移。比较稳妥的做法不是在处理请求时到处写“开发模式/生产模式”分支，而是让 HTTP 层只依赖 fs.FS：开发期传入 os.DirFS("web")，发布期传入 embed.FS。两者对上层提供同一套只读文件接口。

先把服务依赖收窄到 fs.FS

资源处理器只需要打开文件，并不需要知道文件系统的实现。把这层边界固定下来，后面切换来源就只改装配代码。下面的示例把 web 目录作为文件系统根，并用 fs.Sub 去掉目录前缀，避免请求 /static/app.js 时又去寻找 web/web/static/app.js。

package main

import (
    "io/fs"
    "net/http"
)

// newStaticHandler 只依赖 fs.FS，磁盘和嵌入文件都能复用这段逻辑。
func newStaticHandler(files fs.FS) (http.Handler, error) {
    // URL 使用 /static/，文件系统内部只保留相对路径。
    staticFS, err := fs.Sub(files, "static")
    if err != nil {
        return nil, err
    }

    // StripPrefix 后，FileServer 收到的是 app.js 而不是 /static/app.js。
    return http.StripPrefix("/static/", http.FileServer(http.FS(staticFS))), nil
}

这里的关键不是 http.FileServer 本身，而是它接受了 http.FS 包装后的 fs.FS。模板解析也能沿用同样的边界，例如用 template.ParseFS(files, "*.tmpl") 读取嵌入模板。接口统一后，业务代码不会因为资源来源不同而分裂。

发布期用 embed.FS 绑定前端目录

//go:embed 必须紧挨着包级变量声明，模式相对于声明所在的 Go 源文件。发布资源建议放到专用目录，避免把测试数据、隐藏文件或本地构建产物一起匹配进去。

package main

import (
    "embed"
    "io/fs"
    "log"
    "net/http"
)

//go:embed web
var releaseFiles embed.FS

func main() {
    // 把源码目录前缀裁掉，让后续处理器只看到 web 下的相对路径。
    webFiles, err := fs.Sub(releaseFiles, "web")
    if err != nil {
        log.Fatal(err)
    }
    staticHandler, err := newStaticHandler(webFiles)
    if err != nil {
        // 目录名写错属于构建配置错误，启动时直接终止比静默返回 404 更容易排查。
        log.Fatal(err)
    }

    mux := http.NewServeMux()
    mux.Handle("/static/", staticHandler)
    mux.Handle("/", http.FileServer(http.FS(webFiles)))
    log.Fatal(http.ListenAndServe(":8080", mux))
}

如果只使用 string 或 []byte 嵌入单个文件，可以使用空白导入 _ "embed"；需要目录、模板或多种静态资源时，embed.FS 更适合。匹配模式没有命中文件、包含非法路径，都会在构建阶段暴露出来，这正是发布期嵌入的价值。

开发期切换本地目录，别把模式判断塞进请求处理

开发时把同一个处理器接到 os.DirFS("web") 即可。目录中的 static/app.js 会在保存后直接生效，发布时再替换为上面的 releaseFiles。建议只在启动装配处选择文件系统，避免每个请求读取环境变量或判断编译标签。

package main

import (
    "io/fs"
    "os"
)

func loadFiles(dev bool) (fs.FS, error) {
    if dev {
        // 开发期保持热更新；路径相对于进程工作目录，启动脚本应固定它。
        return os.DirFS("web"), nil
    }
    // 发布构建裁掉源码前缀，生产环境不依赖外部目录。
    return fs.Sub(releaseFiles, "web")
}

上例的生产分支假设 releaseFiles 与 loadFiles 位于同一个包；如果项目拆成多个包，应把资源文件系统作为显式参数传给创建路由的函数，而不是依赖全局变量。这样测试可以传入内存文件系统或临时目录。

路径、缓存和测试要一起收口

嵌入文件系统使用斜杠分隔的相对路径，不能把操作系统绝对路径直接拼到请求中。对于带目录的资源，先用固定前缀路由，再交给 fs.Sub；不要用字符串替换模拟路径清洗。入口 HTML 与带内容哈希的 JS/CSS 也应区别对待：入口通常需要较短缓存，指纹资源才适合长缓存。

最小测试不需要启动完整服务，可以直接把处理器挂到请求上，分别传入本地目录和嵌入文件系统，检查入口与一个静态文件的状态码。测试关注的是“同一 URL 在两种来源下都能读到”，而不是检查某个具体部署目录。

常见问题

为什么 embed.FS 读取路径经常多一层目录？

因为模式相对于 Go 源文件，而请求路径还带着 URL 前缀。把资源根交给 fs.Sub，再用 StripPrefix 处理 URL，两个前缀各自只处理一次。

开发期一定要重新编译才能看到 CSS 修改吗？

不需要。开发装配使用 os.DirFS 就能直接读取目录；只有切换到 embed.FS 的发布构建，资源才会在编译时固定下来。

embed.FS 能否运行时写入新文件？

不能把它当作可写磁盘。它是只读文件系统；上传、用户生成内容或运行时缓存应放在独立的对象存储、数据库或磁盘目录中。