在 Go 中如何使用 go:embed 指令嵌入静态文件
有时候，将配置文件、模板甚至整个前端应用直接嵌入到 Go 二进制文件中，是一种提高应用部署效率和简化操作的有效方法。自从 Go 1.16 版本起，Go 语言官方引入了 //go:embed 指令，这使得嵌入静态资源变得异常简单而直接。本文将详细介绍如何在 Go 应用中使用这一强大的特性。
什么是 go:embed
//go:embed 是一个编译器指令，能够在程序编译时期将文件嵌入到 Go 的二进制文件中。它支持将文件或目录嵌入到三种类型的变量中：string、[]byte 和 embed.FS，适用于不同的场景：
string：嵌入单个文件的文本内容。[]byte：嵌入二进制文件，如图片或字体。embed.FS：嵌入多个文件或目录，形成只读虚拟文件系统。
示例代码
import "embed"
//go:embed hello.txt
var content string
//go:embed hello.txt
var contentBytes []byte
//go:embed hello.txt
var fileFS embed.FS
func main() {
fmt.Println(content)
}
//go:embed 的指令紧跟在变量声明之前，支持单个文件、目录或通配符匹配的方式。
快速开始
下面是一个完整的示例，演示如何使用 //go:embed 嵌入多个文件。
package main
import (
"embed"
"fmt"
"io/fs"
)
//go:embed hello.txt
var content string
//go:embed file
var fileFS embed.FS
func main() {
fmt.Printf("hello.txt content: %s\n", content)
helloBytes, _ := fileFS.ReadFile("file/hello1.txt")
fmt.Printf("file/hello1.txt content: %s\n", string(helloBytes))
dir, _ := fs.ReadDir(fileFS, "file")
for _, entry := range dir {
fmt.Println(entry.Name())
}
}
嵌入文件目录
如果需要嵌入目录中的所有文件，可以使用如下方式：
//go:embed file/*
var fileFS embed.FS
此方法会将 file 目录下的所有文件嵌入到 fileFS 中。
在 HTTP 服务器中使用 go:embed
使用 //go:embed 可以将静态资源嵌入到 Go 程序中，并直接通过 HTTP 提供服务：
package main
import (
"embed"
"net/http"
)
//go:embed static
var staticFS embed.FS
func main() {
http.Handle("/", http.FileServer(http.FS(staticFS)))
http.ListenAndServe(":8080", nil)
}
这样可以轻松实现静态资源的托管，而不再需要依赖外部文件系统。
单元测试中的 go:embed
在单元测试中使用 //go:embed 可以解决测试文件依赖问题：
package main
import (
_ "embed"
"testing"
)
//go:embed testdata/test.txt
var testF string
func TestEmbed(t *testing.T) {
t.Log(testF)
}
通过将测试文件嵌入到程序中，可以避免文件依赖问题，提高测试的可靠性。
嵌入父目录中的文件
//go:embed 只能嵌入当前目录中的文件，无法直接嵌入父目录的文件。但我们可以通过将文件拷贝到当前目录并嵌入，或在父目录中创建 Go 文件来解决这个问题。
解决方案
在父目录下创建一个 Go 文件来嵌入文件：
package template
import "embed"
//go:embed *
var TemplateFS embed.FS
然后在其他包中使用该嵌入变量即可。
注意事项
- 嵌入的文件只能是相对当前目录的路径，不能嵌入父目录中的文件。
- 文件路径不能包含特殊字符（如
*、?等），否则会报错。 - 嵌入的
embed.FS是只读的，不能对其内容进行修改。
总结
//go:embed 是 Go 1.16 引入的一个强大功能，它允许我们将静态文件嵌入到 Go 程序的二进制文件中，从而简化部署流程。它非常适合用于托管静态资源和解决测试文件依赖问题。
希望本文能帮助你更好地理解和使用 //go:embed。
延伸阅读：