Go 用 embed 与 io/fs 把模板、配置和静态资源打进单一二进制：部署从此只拷一个文件

为什么要把资源嵌进二进制

Go 服务上线时，最烦心的往往不是代码，而是那一堆散在磁盘上的 HTML 模板、配置文件、图片和前端静态包。少拷一个目录，服务就起不来。Go 1.16 引入的 embed 包让“把资源编译进二进制”成为一行注释的事。

嵌入单个文件与目录

用 //go:embed 指令配合 embed.FS 类型即可。注意指令和变量之间不能有空行。

package main

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

//go:embed templates/index.html
var indexHTML embed.FS

//go:embed assets static
var content embed.FS

func main() {
    data, _ := indexHTML.ReadFile("templates/index.html")
    _ = data

    // 把整个 static 目录挂成 HTTP 静态服务
    sub, _ := fs.Sub(content, "static")
    http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(sub))))
    http.ListenAndServe(":8080", nil)
}

结合 text/template 渲染页面

嵌入的模板可以直接用 template.ParseFS 解析，不再依赖运行时文件路径。

func render(w http.ResponseWriter, name string, data any) {
    tpl, err := template.ParseFS(content, "templates/*.html")
    if err != nil {
        http.Error(w, err.Error(), 500)
        return
    }
    _ = tpl.ExecuteTemplate(w, name, data)
}

嵌入配置与多环境

把默认配置嵌进去，再用环境变量覆盖，既能保证“开箱即用”，又不失灵活性。

//go:embed config/default.yaml
var defaultConfig embed.FS

func loadConfig() []byte {
    b, _ := defaultConfig.ReadFile("config/default.yaml")
    if override := os.Getenv("CONFIG_YAML"); override != "" {
        return []byte(override)
    }
    return b
}

实践要点

• embed 的路径是相对于当前源文件的，且不能引用父目录（..），这既是安全限制也逼你规整项目结构。
• 嵌入大文件会显著增大二进制体积，几百 KB 到几 MB 通常无感，几十 MB 的要权衡是否值得。
• 改了被嵌入的资源后必须重新编译才会生效，开发期可加一个“从磁盘读取优先”的开关提升迭代速度。
• fs.FS 接口让嵌入资源与真实文件系统、测试数据可以互换，单元测试里直接用 fstest.MapFS 即可。

把资源嵌进二进制后，CI 产物就是一个可执行文件，scp 到服务器直接跑，告别“到底漏拷了哪个目录”的线上事故。