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 读取并返回指定名称文件的内容。