Go 怎么把 HTML 和静态文件打包进可执行程序

如果 Go 服务需要把一个小型前端一起交付，最省心的办法通常是使用标准库 embed：在编译时把 web 目录放进二进制，运行时再通过 net/http 提供。这样部署时只需要复制一个可执行文件，不必再担心 HTML、CSS 和 JavaScript 目录是否漏传。

整棵静态目录用 embed.FS，再用 fs.Sub 去掉 URL 中的目录前缀，交给 http.FileServer(http.FS(...)) 即可。资源修改不会自动反映到已经编译的程序，必须重新构建。

为什么 embed.FS 适合打包整棵静态目录

先准备一个最小目录。这里把 main.go 与 web 放在同一个包目录下：

demo/
├── go.mod
├── main.go
└── web/
    ├── index.html
    ├── app.js
    └── styles.css

embed 包会在编译阶段读取匹配的文件。目录模式匹配的是一棵文件树，但以点号或下划线开头的文件默认会被排除；如果确实需要它们，可以使用 all: 前缀。模式不能通过 .. 逃到包外，也不能指向另一个模块。

用一段 Go 代码把 web 目录编译进去

在 main.go 中声明包级变量。//go:embed 必须紧挨变量声明，中间最多放空行或普通注释：

package main

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

//go:embed web
var webFiles embed.FS

func main() {
    site, err := fs.Sub(webFiles, "web")
    if err != nil {
        log.Fatal(err)
    }

    mux := http.NewServeMux()
    mux.Handle("/", http.FileServer(http.FS(site)))

    log.Println("listen on http://127.0.0.1:8080")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

这里的 webFiles 仍然保留了 web/index.html 这样的内部路径。fs.Sub 返回一棵从 web 目录开始的新文件系统，交给 http.FS 后，浏览器访问根路径时就能对应到 index.html，URL 不需要暴露内部目录名。

单文件、模板和静态目录该怎么选

不要为了所有资源都声明成 embed.FS。选择类型时可以按下面的边界判断：

embed.FS 实现了 io/fs.FS，因此不仅能给 HTTP 文件服务使用，也能交给 html/template 或 text/template。需要模板时，可直接使用：

tpl, err := template.ParseFS(webFiles, "web/*.html")
if err != nil {
    log.Fatal(err)
}
_ = tpl

模板文件中的动态数据仍由服务端执行时传入；embed 只负责把模板文件本身打包进去，不会把模板渲染成固定 HTML。

构建成功后还要留意哪些发布限制

执行 go build -o demo-server . 后，生成的程序会携带匹配到的资源。可以把运行目录换到没有 web 文件夹的环境中，二进制仍可提供页面；但这并不意味着资源从此可以在线修改。

第一，改了 index.html、CSS 或 JavaScript 后必须再次构建并替换程序。第二，嵌入文件系统是只读的，不能把用户上传内容写回 embed.FS。第三，目录模式若没有匹配到文件或目录，构建会失败，这通常比部署后才发现缺文件更容易排查。生产项目可以把内置资源作为稳定的默认页面，把上传文件、主题配置和热更新内容放到对象存储或外部目录。

最后做一次最小检查：确认 //go:embed 的路径相对 main.go 所在包、检查 fs.Sub 的目录名与模式一致，再执行 go build。如果访问根路径出现目录列表而不是页面，先检查 web/index.html 是否存在，以及 FileServer 使用的是 site 还是原始的 webFiles。

常见问题

Go 的 embed 能不能把上级目录的 HTML 打包进来？

不能用 .. 穿越到上级目录；把资源移动到当前包目录，或单独建立负责嵌入资源的 Go 包。

为什么改完 HTML 后运行中的页面没有变化？

因为文件内容已经在编译时写入旧二进制。重新执行 go build 并重启新程序即可。

静态文件和模板能同时使用吗？

可以。用同一个 embed.FS 给 template.ParseFS 和 http.FileServer，按目录或文件模式区分用途即可。

官方参考：embed 包文档、Go 1.16 发布说明中的 Embedding Files。