Go embed 通配符为什么默认忽略点文件

Go 的 //go:embed 确实会在“按目录递归收集资源”时默认排除文件名以 . 或 _ 开头的文件，但这不等于所有带 * 的模式都会忽略点文件。官方文档明确给出一个容易被忽略的差别：image/* 可以匹配 image/.tempfile，而直接写目录名 image 不会；两者默认都不会收进更深层的 image/dir/.tempfile。

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

真正控制点文件的关键，是模式是否触发目录递归，以及是否带有 all: 前缀。需要递归包含点文件和下划线文件时使用 all:目录名；只需要一个确定的隐藏文件时，优先写精确路径，避免扩大打包范围。

先澄清：不是所有星号都会忽略点文件

//go:embed 的模式使用 path.Match 语法，并以声明指令的包目录为基准。它不是 Unix shell 的 glob 展开，所以不要套用“shell 通配符默认不匹配点文件”的直觉。Go 文档描述的是另一条规则：当模式命中一个目录并遍历其子树时，遍历会排除名字以点号或下划线开头的文件。

这条规则同时覆盖两类经常被叫作“隐藏资源”的名字：

• .well-known、.nojekyll、.env.example 这类以点号开头的文件或目录；
• _redirects、_headers、_internal 这类以下划线开头的文件或目录。

默认排除它们的好处很实际：资源目录里常混有编辑器配置、构建缓存、临时文件和部署元数据。如果仅仅写一个目录名，Go 不会把这些内容不加区分地打进最终二进制。代价是某些框架确实需要的 _redirects 或站点验证目录，也可能一起被省略。

用一个最小目录看清三种写法

假设包目录中有以下资源。这里把层级写成普通文本，只用于说明输入结构：

assets/
├── index.html
├── app.css
├── .nojekyll
├── _redirects
└── nested/
    ├── page.html
    ├── .meta
    └── _headers

先看最常见的目录模式：

package site

import "embed"

// 目录模式会递归嵌入普通文件，但默认排除点号和下划线开头的名字。
//go:embed assets
var Assets embed.FS

这时 index.html、app.css 和 nested/page.html 会进入 Assets；四个隐藏或下划线资源不会进入。它适合普通静态站点资源，也能降低误打包临时文件的概率。

再看当前层通配符：

package site

import "embed"

// 星号直接匹配 assets 当前层条目，因此当前层点文件也可能被匹配。
//go:embed assets/*
var TopLevel embed.FS

根据官方示例的规则，assets/* 能匹配当前层的 assets/.nojekyll。但当它命中 assets/nested 这个目录并继续处理目录内容时，嵌套的 .meta 与 _headers 仍受目录遍历过滤影响。也就是说，“在某一层用星号”并不是“整个子树包含所有隐藏文件”。

三种写法放在一起比较

这张表里最值得记住的是：all: 改变的是“遍历目录时是否排除点号和下划线开头名字”的规则，并不会让模式突破模块边界，也不会把无关路径自动变成合法匹配。

需要隐藏资源时，优先在两种方案中选择

方案一：精确写出需要的文件

如果只缺一个 .nojekyll 或 _redirects，精确路径最清楚：

package site

import "embed"

// 普通目录继续使用安全的默认过滤。
//go:embed assets
// 只额外加入部署所需的两个特殊文件。
//go:embed assets/.nojekyll assets/_redirects
var Assets embed.FS

同一个变量可以使用多条 //go:embed 指令。这样既保留目录模式的默认过滤，又明确记录为什么某些隐藏资源必须进入二进制。代码审查时也容易发现新增的打包内容。

方案二：用 all: 包含完整子树

如果站点生成器或前端框架在多个层级都依赖点文件、下划线文件，可以改为：

package site

import "embed"

// all: 关闭目录遍历中的点号/下划线排除规则。
//go:embed all:assets
var Assets embed.FS

all: 是 embed 模式前缀，不是磁盘上的目录名。它会让 assets/.nojekyll、assets/_redirects、assets/nested/.meta 和 assets/nested/_headers 都具备被嵌入的条件。选择它之前，应先确认资源树里没有密钥、私有配置、缓存或不应分发的文件。

读取时怎么确认资源真的进入了 embed.FS

embed.FS 是只读文件系统，并实现 io/fs.FS。可以通过 fs.ReadDir 查看目录项，再用 ReadFile 检查指定资源。下面的函数把“目录不存在”和“文件未嵌入”作为正常错误返回给调用方，不使用 panic 隐藏问题。

package site

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

//go:embed all:assets
var Assets embed.FS

func CheckEmbeddedFiles() error {
    // 读取目录用于确认当前层有哪些条目进入只读文件系统。
    entries, err := fs.ReadDir(Assets, "assets")
    if err != nil {
        return fmt.Errorf("读取嵌入目录失败: %w", err)
    }
    for _, entry := range entries {
        fmt.Printf("%s\n", entry.Name())
    }

    // 精确读取关键部署文件，比只看目录列表更适合验收。
    if _, err := Assets.ReadFile("assets/.nojekyll"); err != nil {
        return fmt.Errorf(".nojekyll 未嵌入: %w", err)
    }
    if _, err := Assets.ReadFile("assets/nested/_headers"); err != nil {
        return fmt.Errorf("_headers 未嵌入: %w", err)
    }
    return nil
}

如果需要在自动构建里快速检查，可以写一个很小的 Go 测试，而不是依赖开发者目测二进制大小：

package site

import "testing"

func TestHiddenAssetsEmbedded(t *testing.T) {
    // 测试只验证业务必需文件，不要求把所有隐藏文件都打包。
    required := []string{
        "assets/.nojekyll",
        "assets/nested/_headers",
    }
    for _, name := range required {
        if _, err := Assets.ReadFile(name); err != nil {
            t.Fatalf("缺少嵌入资源 %s: %v", name, err)
        }
    }
}

# 运行包测试，确认声明的关键隐藏资源可以读取
go test ./...

这个检查点比“构建成功”更有意义。构建成功只说明每个模式至少匹配到了合法内容，不代表你期望的每个隐藏文件都一定在结果中。

all: 不会解除其他构建限制

all: 只改变点号与下划线名字的目录遍历规则，以下限制仍然存在：

• 模式相对于当前包目录，路径分隔符始终使用正斜杠，即使在 Windows 上也是如此；
• 模式不能包含作为独立路径元素的 .、.. 或空元素，也不能以斜杠开头或结尾；
• 不能匹配包所属模块之外的文件，也不能通过符号链接跨出去；
• 不能嵌入 .git/*、vendor/ 或包含另一个 go.mod 的独立模块目录；
• 每个模式必须匹配至少一个文件或非空目录，否则构建会失败；空目录会被忽略；
• string 或 []byte 变量只能对应一个模式，并且该模式只能匹配一个文件；资源树应使用 embed.FS。

因此，发现点文件缺失时，不要立刻把所有模式都改成 all:。先确认缺的是直接文件还是嵌套资源，再看精确路径是否足够。只有业务明确需要完整隐藏资源树时，才扩大到 all:目录。

常见问题

为什么 //go:embed assets/* 能包含直接点文件？

因为 embed 模式使用 path.Match 语法，星号直接匹配当前层条目；它不是 shell 对点文件的特殊过滤。官方文档明确以 image/* 可以嵌入 image/.tempfile 为例。

为什么 assets/* 仍然漏掉子目录里的点文件？

星号匹配到子目录后，对该目录内容的递归收集仍应用默认排除规则，所以更深层以点号或下划线开头的名字不会自动进入。要递归包含它们，应使用 all:assets，或逐个写精确路径。

all: 会把 .git 一起嵌入吗？

不会。.git/* 本身属于禁止匹配范围；all: 不会绕过模块和构建系统的其他限制。

为什么模式没有匹配文件时直接构建失败？

这是 Go 构建系统的显式约束：每个 //go:embed 模式都必须匹配至少一个文件或非空目录。它能尽早暴露路径写错、资源未生成或目录为空的问题。

结论

Go embed “默认忽略点文件”说的是目录递归时对 . 和 _ 前缀名称的过滤，不是所有通配符都具备相同的隐藏文件语义。直接写目录名最安全，当前层星号可以命中直接点文件，all: 才会递归包含隐藏资源。工程上优先精确列出业务必需文件，只有资源树确实需要完整保留时才使用 all:目录，并用测试确认关键文件已经进入 embed.FS。