Go go:embed 怎样嵌入目录树

嵌入一棵目录树，通常使用包级 embed.FS 变量，并在它上方写 //go:embed assets。目录模式会递归纳入符合规则的文件；程序通过 ReadFile、ReadDir 或 io/fs 接口读取构建时资源，不再依赖运行目录中的同名文件。

需要特别留意三点：模式相对于声明所在包目录；嵌入名称通常保留 assets 前缀；目录递归默认排除名称以点号或下划线开头的项。下面以随命令行程序分发的帮助资料和公开默认值为例，说明范围与读取方式，不把机密配置装进二进制。本例未执行构建或运行。

把需要随程序发布的资源放在包内

假设部署后程序找不到帮助文件，原因是资源曾通过相对磁盘路径读取。若这些资源本就应随程序版本一起更新，可以改为构建时嵌入；若它们需要运维人员独立修改，则不应直接换成 embed。先确定资源生命周期，才能决定目录布局。

下面是可供读者创建的示例目录，不是本机文件清单。main.go 和 assets 位于同一个包目录；intro.txt 放普通帮助文字，reader.json 放公开默认值，另外两项仅用于理解匹配范围，不应存放真实秘密。

demo/
  go.mod
  main.go
  assets/
    help/
      intro.txt
    defaults/
      reader.json
    .draft.txt
    _scratch.txt

空目录不会被当成可嵌入资源保留下来。帮助正文或默认值更新后，要重新构建并分发程序，运行时修改源码目录里的文件不会自动改变已构建资源。

用目录模式明确嵌入范围

目录树对应 embed.FS，而不是 string 或 []byte；后两种变量适合一个文件。指令需要位于包级单变量声明之前，并且该源文件需要导入 embed。模式分隔符统一用正斜杠，不使用 Windows 反斜杠或包外父目录引用。

对本例选择 assets 目录模式，正常资源包括 help/intro.txt 和 defaults/reader.json。模式使用 assets 时，递归扫描排除点号或下划线开头的项；不要把 assets/* 误认为完全相同的写法，星号直接匹配到的顶层隐藏文件可能进入集合。需要确实包含这些项时才考虑 all:assets，不要为了省事扩大范围。

上面的差异属于 Go 官方 embed 模式规则。模式或匹配不合法时会导致构建失败；它不是运行时去磁盘找文件的通配查询。符号链接也不能作为普通资源捷径来依赖。

通过 embed.FS 和 fs.Sub 统一读取根

嵌入目录不等于自动去掉目录名。对原始 assets 变量读取时，名称是 assets/help/intro.txt；通过 fs.Sub 建立以 assets 为根的子树视图后，才改用 help/intro.txt。下面给出完整 main.go，所需资源按前述布局创建：

package main

import (
    "embed"
    "fmt"
    "io/fs"
    "log"
)

// assets 是构建时装入的只读资源，不包含运行期私密配置。
//go:embed assets
var assets embed.FS

func run() error {
    // 原始 embed.FS 保留 assets 这一层名称。
    intro, err := assets.ReadFile("assets/help/intro.txt")
    if err != nil {
        return fmt.Errorf("读取入门说明: %w", err)
    }
    fmt.Print(string(intro))

    // 建立子树视图后，名称从 assets 内部开始。
    content, err := fs.Sub(assets, "assets")
    if err != nil {
        return fmt.Errorf("建立资源子树: %w", err)
    }
    if _, err := fs.ReadFile(content, "help/intro.txt"); err != nil {
        return fmt.Errorf("读取子树文件: %w", err)
    }

    // 列举嵌入的文件名，先处理访问错误再使用目录项。
    return fs.WalkDir(content, ".", func(name string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if !d.IsDir() {
            fmt.Println("资源:", name)
        }
        return nil
    })
}

func main() {
    // 读取错误明确终止本例，避免悄悄换成磁盘上的同名文件。
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

代码中的 assets.ReadFile 使用原始嵌入名称；content 是 fs.Sub 返回的 fs.FS 子树视图；fs.ReadFile 与 fs.WalkDir 则只面向这个接口。这里不需要把内嵌数据先解压到临时磁盘目录，也不需要切换进程工作目录。

fs.Sub 改变的是文件系统视图根，并不单独保证相应目录存在，所以仍要处理后续读取错误。WalkDir 列出的是子树视图内名称，根使用点号。它的回调先检查 err 再访问目录项，避免错误情况下使用空目录项。接口细节见 io/fs 官方文档。

把只读资源和敏感配置分开

embed.FS 是只读资源集合，适合公开帮助文本和默认模板，但“写不进去”不意味着“外部看不到”。分发程序就应把嵌入内容视为随产物交付，不能存密码、私钥或环境专用凭据。机密和可变配置使用独立机制管理，不靠隐藏文件名保护。

默认跳过某些名称也不是完整的敏感文件过滤器。一个普通名称的内部草稿仍可能被目录模式纳入；比起把整个项目根交给星号，更容易控制的做法是建立专门资源目录，并明确哪些内容允许进入发布物。

fs.FS 表示可供接口读取的文件系统，不自动等于公开网络目录。本篇只讲嵌入与读取，没有启动 HTTP 服务，也没有把全部资源暴露给客户端。若后续增加公开访问，需要重新决定可见集合，不能因资源已嵌入就默认全部公开。

记录资源清单并处理构建与读取错误

构建问题与运行期名称问题分开处理：构建阶段没有匹配项时检查源码包位置与模式；程序读取失败时检查当前拿到的是原始集合还是子树视图，以及调用使用的名称。不要在失败时默默回退到磁盘同名文件，否则部署机器上的意外文件可能改变内容来源。

读者可以利用示例中的 WalkDir 记录资源名称，检查列表是否符合预期；通常只需文件名和构建版本，不必把资源正文全部写入日志。这是接入建议，不是本文已经执行的审查报告。

• 只分发公开且版本固定的资源。
• 模式从包目录解释，资源在构建前准备完毕。
• 使用同一个视图根解释所有读取名称。
• 错误通过错误链返回，不用空内容冒充成功。
• 变更资源后重新构建发布，不期待磁盘热更新。

为什么 ReadFile("intro.txt") 找不到文件？

示例资源处在两层目录下。原始集合用 assets/help/intro.txt，子树视图用 help/intro.txt，两者都不是 intro.txt。

assets/* 会不会递归？

直接匹配到目录后，目录中的文件仍按目录递归规则纳入；但它与直接写 assets 在顶层隐藏文件选择上不同，不要混为一谈。

运行时能修改内嵌默认值吗？

不能通过 embed.FS 写回资源。需要修改时，将数据交给另外的可写存储管理，内嵌版本仍是构建时集合。

嵌入目录树的核心是把资源范围固定在构建时，再用明确根名称的只读接口访问。目录模式、视图根与配置生命周期这三件事分清，才能减少部署后缺文件和读错路径的问题。