Go embed 怎样把模板放进二进制

我在把 Go 服务交付给别人运行时，最容易踩到的坑不是编译，而是模板目录：程序在本机能打开 templates/index.html，换到容器或别的工作目录后就找不到了。Go 1.16 引入的 //go:embed 可以在编译期把文件放进程序，模板运行时从只读的 embed.FS 读取，最终交付一个不依赖外置模板目录的二进制。

先判断模板该用哪种嵌入类型

如果只有一个固定文本文件，string 适合直接读取内容，[]byte 适合交给需要字节切片的 API。模板通常不止一个文件，还会有布局、局部片段和静态资源，这时用 embed.FS 更自然：它实现了 io/fs.FS，可以交给 html/template、text/template 或 net/http 这类理解文件系统接口的包。

用 go:embed 把 templates 目录放进程序

先按下面的结构放文件，main.go 与 templates 同属一个包目录：

app/
├── go.mod
├── main.go
└── templates/
    └── index.html

然后在包级变量上声明嵌入模式。注意指令必须紧挨变量声明，不能写在函数内部；目录名使用正斜杠，模式匹配范围不能越出当前模块。

package main

import (
    "embed"
    "html/template"
    "log"
    "net/http"
)

// templateFS 保存编译期嵌入的模板目录，运行时只读。
//go:embed templates/*.html
var templateFS embed.FS

func main() {
    // ParseFS 使用嵌入后的路径，而不是本机磁盘路径。
    tmpl := template.Must(template.ParseFS(templateFS, "templates/*.html"))

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // 用结构体提供模板数据，后续可以安全扩展字段。
        data := struct {
            Title string
        }{Title: "嵌入式模板"}

        // 渲染失败时返回服务端错误，避免把内部错误直接写给客户端。
        if err := tmpl.ExecuteTemplate(w, "index.html", data); err != nil {
            http.Error(w, "模板渲染失败", http.StatusInternalServerError)
            return
        }
    })

    // 监听地址属于运行配置，不应和模板一起硬编码进嵌入资源。
    log.Fatal(http.ListenAndServe(":8080", nil))
}

这里用的是 templates/*.html，因此 ParseFS 也要使用带目录前缀的模式。若改成 //go:embed templates，匹配范围会更宽，但目录中以点号或下划线开头的文件默认不会被包含；确实需要它们时才考虑 all:templates。

用 ParseFS 读取模板，部署时不再依赖工作目录

embed.FS 里的文件名是编译期确定的逻辑路径。程序从任意工作目录启动时，ParseFS 仍然会读取同一个嵌入对象，因此不需要拼接 os.Getwd() 或猜测当前目录。模板内容变更后必须重新编译；嵌入的文件系统是只读的，不能把它当成运行时缓存或上传目录。

如果服务还要提供 CSS、JavaScript 等静态文件，可以把多个目录嵌入到一个 FS，再通过 http.FS 交给文件服务器。模板渲染与静态文件服务共享同一个 FS 时，路径规划要保持清楚，避免把仅供模板解析的文件意外暴露。

几个容易误判的边界

我的经验是：把“随程序发布的稳定资源”和“部署后会改变的数据”分开。模板、默认 CSS、内置帮助页适合 embed；环境变量、密钥、租户配置和用户生成文件不适合 embed。这样单文件交付解决了路径问题，也不会把运行时配置锁死在编译产物里。

常见问题

Go embed 从哪个版本开始支持？

embed 包和 //go:embed 指令从 Go 1.16 开始提供。项目应使用不低于该版本的工具链，并在模块和构建环境中保持一致。

为什么必须导入 embed？

即使变量类型是 string 或 []byte，也需要导入 embed 才能让构建系统识别指令；不用包名时可以写成空白导入 _ "embed"。使用 embed.FS 时则直接导入并引用类型。

模板文件能否在运行时覆盖？

不能直接覆盖嵌入资源。若需要热更新，应把模板放在外部文件系统并设计明确的加载与回滚策略；embed 更适合稳定、随版本发布的资源。