Go embed.FS 怎样把静态资源嵌入程序

做一个单文件发布的 Go 服务时，最容易被低估的不是 HTTP 路由，而是静态资源到底从哪里来。把 CSS、JavaScript 和模板留在磁盘上，部署时需要额外复制目录；把它们直接编译进程序，又不能把代码写成一堆手工读取字节的分支。

这类场景可以用 embed.FS 把资源目录变成只读文件系统，再交给 net/http 或模板包使用。本文只围绕这一条路径展开：目录怎么放、//go:embed 怎么写、URL 前缀怎么处理，以及哪些边界会让编译直接失败。

官方文档：https://pkg.go.dev/embed

先把资源目录和嵌入边界设计清楚

embed.FS 适合一棵资源树，而不是单个配置文件。Go 官方文档把 string、[]byte 和 FS 分成三种目标：单文件文本可以用字符串，单文件二进制可以用字节切片，多文件目录则用 FS 更自然。

假设服务的包目录如下，网页资源都放在声明变量的 Go 包下面：

webapp/
├── main.go
└── static/
    ├── index.html
    ├── css/app.css
    └── js/app.js

这里最重要的约束有两个：匹配模式相对于包含 Go 源文件的包目录解析，而且 //go:embed 只能初始化包级变量，不能放在函数内部临时声明。目录结构提前固定，后面的 HTTP 路径才不会在部署阶段临时拼接本地路径。

用包级声明把静态资源放进 embed.FS

声明一个文件系统变量时，需要导入 embed，并把指令紧贴在变量声明之前。下面的写法把 static 目录下的资源作为一棵只读文件树嵌入：

package main

import "embed"

// assets 保存编译时匹配到的静态资源，运行时只读。
//go:embed static/*
var assets embed.FS

static/* 和 static 不是完全相同的匹配表达式。目录递归匹配时，以点号或下划线开头的文件默认被排除；如果确实需要纳入这类文件，可以使用 all:static。生产资源一般不需要把临时文件、隐藏目录或编辑器备份文件一起塞进二进制，所以默认排除通常更安全。

指令还要求每个模式至少匹配一个文件或非空目录。模式不能用 .、..、绝对路径或越过模块边界的路径；匹配不到资源时，问题不是运行时 404，而是构建阶段就会失败。也就是说，资源清单的正确性要在编译前随目录一起维护。

把 embed.FS 接到 HTTP 路由

embed.FS 实现了 io/fs.FS，而 http.FS 可以把它适配为 HTTP 文件服务使用的文件系统。URL 中常见的 /static/ 前缀不应该直接传给嵌入文件树，否则查找的文件名会变成 static/css/app.css；如果文件树的根已经是 static，就需要先移除这个前缀。

package main

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

// assets 是只读的嵌入资源树，静态文件不再依赖工作目录。
//go:embed static/*
var assets embed.FS

func main() {
    mux := http.NewServeMux()

    // 先去掉 URL 前缀，再让 FileServer 在 embed.FS 根目录查找文件。
    fileHandler := http.FileServer(http.FS(assets))
    mux.Handle("/static/", http.StripPrefix("/static/", fileHandler))

    // 让根路径也有明确结果，避免把页面入口和静态目录混在一起。
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        if r.URL.Path != "/" {
            http.NotFound(w, r)
            return
        }
        // 读取嵌入的首页并处理读取错误，不向客户端输出半截内容。
        data, err := assets.ReadFile("static/index.html")
        if err != nil {
            http.Error(w, "index is unavailable", http.StatusInternalServerError)
            return
        }
        w.Header().Set("Content-Type", "text/html; charset=utf-8")
        _, _ = w.Write(data)
    })

    // ListenAndServe 返回错误时记录下来，便于区分启动失败和请求问题。
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

这里的关键不是把几个函数串起来，而是保持两边的命名一致：StripPrefix 负责 URL 适配，http.FS 负责接口适配，FileServer 负责文件查找与响应。三者少一个，都会让“磁盘路径”和“嵌入路径”之间出现错位。

几个容易把资源路径写错的边界

第一，嵌入路径和请求路径不是一回事。上面的模式是 static/*，所以嵌入树中通常可以读取 static/index.html。而 http.StripPrefix("/static/", ...) 会把请求 /static/css/app.css 变成文件服务看到的 css/app.css。如果希望文件服务的根直接对应 static 目录，需要把子目录作为嵌入入口，例如把模式改为 static 并结合实际目录结构重新确认读取路径，不能只改路由字符串。

第二，目录模式会影响隐藏文件。普通目录递归匹配不包含以 . 或 _ 开头的文件；all: 前缀才会改变这个行为。不要为了“保险”直接嵌入整个项目根目录，否则临时文件和不该发布的资源也可能进入二进制。

第三，资源是只读的。embed.FS 代表编译时收集的文件，不是可写的上传目录。用户上传头像、缓存文件或运行时生成的报表，仍然需要单独的持久化方案。把上传目录误认为嵌入目录，最终会表现为写入失败或重启后内容消失。

第四，错误要分成构建期和请求期。模式非法、越界或没有匹配项属于构建期错误；请求了不存在的文件则属于运行期 404。把两类问题混在一起，会导致开发者反复检查路由，却忽略资源根本没有被编译进程序。

发布前用一张清单判断是否适合

• 资源是否位于声明变量的 Go 包目录或其子目录中？
• //go:embed 是否紧贴包级 string、[]byte 或 embed.FS 变量？
• 每个 pattern 是否至少匹配一个真实文件，并且没有把临时目录一起带入？
• HTTP 请求前缀是否和 StripPrefix 的参数完全对应？
• 首页是通过 ReadFile 读取，还是由文件服务处理？两种路径是否只保留一种明确入口？
• 是否把需要运行时写入的内容误放进只读资源树？

如果答案都清楚，embed.FS 很适合小型前端、内置文档、默认模板和单文件交付的 Go 服务。它解决的是“资源随程序发布”的一致性问题，不会替代用户内容存储，也不会自动修复 URL 前缀设计。

相关问题

为什么 //go:embed 写在函数里不能用？

因为该指令只允许初始化包级变量，编译器需要在构建阶段收集资源并写入程序。函数内部变量属于运行时作用域，不满足这个资源收集模型。

embed.FS 能不能直接修改文件？

不能。它提供的是只读文件系统接口；需要运行时写入时，应把写入内容交给独立的磁盘目录、对象存储或数据库。