package embed
import "embed"
Package embed 提供对嵌入到运行中的 Go 程序内的文件的访问。
导入 "embed" 的 Go 源文件可以使用 //go:embed 指令, 用一个 string、[]byte 或 FS 类型的变量来初始化, 其内容为编译时从包目录或子目录读取到的文件内容。
例如,以下是将名为 hello.txt 的文件嵌入, 然后在运行时打印其内容的三种方式。
将单个文件嵌入到字符串中:
import _ "embed" //go:embed hello.txt var s string print(s)
将单个文件嵌入到字节切片中:
import _ "embed" //go:embed hello.txt var b []byte print(string(b))
将一个或多个文件嵌入到文件系统中:
import "embed"
//go:embed hello.txt
var f embed.FS
data, _ := f.ReadFile("hello.txt")
print(string(data))
指令
在变量声明上方的 //go:embed 指令使用一个或多个 path.Match 模式 来指定要嵌入哪些文件。
该指令必须紧接在包含单个变量声明的行之前。 指令与声明之间只允许有空行和 ‘//’ 行注释。
变量的类型必须是字符串类型、字节类型的切片, 或 FS(或 FS 的别名)。
例如:
package server import "embed" // content 保存我们静态 Web 服务器的内容。 //go:embed image/* template/* //go:embed html/index.html var content embed.FS
Go 构建系统会识别这些指令,并安排用文件系统中匹配的文件 填充所声明的变量(在上面的示例中为 content)。
//go:embed 指令为了简洁可以接受多个以空格分隔的模式, 但也可以重复使用,以便在模式很多时避免过长的行。 这些模式是相对于包含该源文件的包目录进行解释的。 路径分隔符为正斜杠,即使在 Windows 系统上也是如此。 模式不能包含 ‘.’ 或 ‘..’ 或空的路径元素,也不能以斜杠开头或结尾。 要匹配当前目录中的所有内容,请使用 ‘*’ 而不是 ‘.’。 为了允许文件名称中包含空格,模式可以写成 Go 的双引号或反引号字符串字面量。
如果某个模式指定了一个目录,则该目录为根的子目录树中的所有文件 都会被(递归地)嵌入,但名称以 ‘.’ 或 ‘_’ 开头的文件会被排除。 因此上面示例中的变量几乎等价于:
// content 是我们静态 Web 服务器的内容。 //go:embed image template html/index.html var content embed.FS
不同之处在于,‘image/*’ 会嵌入 ‘image/.tempfile’,而 ‘image’ 不会。 两者都不会嵌入 ‘image/dir/.tempfile’。
如果某个模式以前缀 ‘all:’ 开头,则遍历目录的规则会改变, 以包含那些以 ‘.’ 或 ‘_’ 开头的文件。例如,‘all:image’ 会同时嵌入 ‘image/.tempfile’ 和 ‘image/dir/.tempfile’。
//go:embed 指令既可以用于导出变量,也可以用于未导出变量, 取决于该包是否希望将数据提供给其他包使用。 它只能用于包作用域的变量,不能用于局部变量。
模式不得匹配包所在模块之外的文件,例如 ‘.git/*’、符号链接、 'vendor/',或任何包含 go.mod 的目录(这些是独立的模块)。 模式不得匹配名称中包含特殊标点字符 " * < > ? ` ' | / \ 和 : 的文件。 对空目录的匹配会被忽略。此后,//go:embed 行中的每个模式 都必须至少匹配一个文件或非空目录。
如果任何模式无效或匹配无效,构建将失败。
字符串与字节
类型为 string 或 []byte 的变量的 //go:embed 行只能有一个模式, 并且该模式只能匹配单个文件。该 string 或 []byte 会用 该文件的内容进行初始化。
即使使用 string 或 []byte,//go:embed 指令也要求导入 "embed"。 在不引用 embed.FS 的源文件中,请使用空白导入(import _ "embed")。
文件系统
对于嵌入单个文件,string 或 []byte 类型的变量通常是最佳选择。 FS 类型支持嵌入一棵文件树,例如一个包含静态 Web 服务器 内容的目录,如上面的示例所示。
FS 实现了 io/fs 包的 FS 接口,因此它可以与任何理解 文件系统的包一起使用,包括 net/http、text/template 和 html/template。
例如,给定上面示例中的 content 变量,我们可以写:
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(content))))
template.ParseFS(content, "*.tmpl")
工具
为了支持分析 Go 包的工具,//go:embed 行中出现的模式
可在 “go list” 输出中获得。参见 “go help list” 输出中的
EmbedPatterns、TestEmbedPatterns 和 XTestEmbedPatterns 字段。
Example
package main
import (
"embed"
"log"
"net/http"
)
//go:embed internal/embedtest/testdata/*.txt
var content embed.FS
func main() {
mux := http.NewServeMux()
mux.Handle("/", http.FileServer(http.FS(content)))
err := http.ListenAndServe(":8080", mux)
if err != nil {
log.Fatal(err)
}
}
Index
Examples
Types
type FS
type FS struct { // contains filtered or unexported fields }
FS 是一个只读的文件集合,通常使用 //go:embed 指令进行初始化。 当声明时没有 //go:embed 指令时,FS 是一个空文件系统。
FS 是一个只读值,因此可以安全地被多个 goroutine 同时使用, 也可以安全地将 FS 类型的值相互赋值。
FS 实现了 fs.FS,因此它可以与任何理解文件系统接口的包一起使用, 包括 net/http、text/template 和 html/template。
有关初始化 FS 的更多详细信息,请参阅包文档。
func (FS) Open
func (f FS) Open(name string) (fs.File, error)
Open 打开指定名称的文件以供读取,并将其作为 fs.File 返回。
当文件不是目录时,返回的文件实现了 io.Seeker 和 io.ReaderAt。
func (FS) ReadDir
func (f FS) ReadDir(name string) ([]fs.DirEntry, error)
ReadDir 读取并返回指定名称的整个目录。
func (FS) ReadFile
func (f FS) ReadFile(name string) ([]byte, error)
ReadFile 读取并返回指定名称文件的内容。