Go os 怎样复制 fs.FS 的目录树到磁盘

如果手里已经有一个 fs.FS，想把它完整落到磁盘，Go 1.23 起可以直接调用 os.CopyFS(dir, fsys)。它会在目标目录不存在时创建目录，复制源文件系统中的目录和文件；但目标中已经存在同名文件时不会覆盖，而是返回可用 errors.Is(err, fs.ErrExist) 判断的错误。

这篇只解决一个问题：如何把 os.DirFS 或 embed.FS 变成磁盘目录。排查顺序按“根路径是否正确、目标是否冲突、错误是否可分类”展开。

• 最低版本：Go 1.23，因为 os.CopyFS 在该版本加入。
• 根路径：fsys 提供的是目录树视图，复制到目标目录后不会自动再包一层源目录名。
• 覆盖策略：已有文件不会被覆盖；复制遇到的第一个错误会结束本次复制。

先确认 fs.FS 的根和目标目录

最容易看错的是“源目录名是否会跟着复制”。例如 os.DirFS("assets") 的根就是 assets 目录内部，fsys.Open("logo.svg") 实际对应磁盘上的 assets/logo.svg。把它复制到 build/assets 时，目标文件会是 build/assets/logo.svg，而不是 build/assets/assets/logo.svg。

如果源是嵌入文件，也要先决定根。embed.FS 可能包含一个 static 顶层目录；用 fs.Sub 取出它后，复制出来的就是 static 内部内容。

用 os.CopyFS 复制目录树

本地目录场景只需要把目录包装成 fs.FS，再交给 os.CopyFS：

package main

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

func main() {
	// DirFS 的根指向 assets 内部，目标只接收这棵树的内容。
	source := os.DirFS("assets")
	if err := os.CopyFS("build/assets", source); err != nil {
		// CopyFS 可能返回已存在文件、路径或权限错误，先保留原错误。
		fmt.Printf("复制失败: %v\n", err)
		return
	}

	// 用 Stat 检查目标目录是否已经成为可访问的文件系统根。
	if _, err := fs.Stat(os.DirFS("build/assets"), "."); err != nil {
		fmt.Printf("目标检查失败: %v\n", err)
		return
	}
	fmt.Println("目录树复制完成")
}

这里的 fs.Stat 只用于说明复制后的目标根可以再次作为 fs.FS 访问，并不是 CopyFS 的额外必需步骤。目标目录不存在时，CopyFS 会创建它；文件模式按文档规则创建，目录权限会受到当前系统 umask 影响。

嵌入文件要先处理顶层目录

发布程序常见的另一种来源是 embed.FS。如果直接复制包含 static 的嵌入文件系统，目标会保留这个顶层目录；如果希望把它的内容直接放入 public，先用 fs.Sub 调整根：

package main

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

//go:embed static
var embedded embed.FS

func main() {
	// 只取 static 目录，避免目标目录多出一层 static。
	staticFS, err := fs.Sub(embedded, "static")
	if err != nil {
		fmt.Printf("嵌入目录不存在: %v\n", err)
		return
	}
	if err := os.CopyFS("public", staticFS); err != nil {
		// CopyFS 不覆盖已有文件，部署前要明确目标是否为空。
		fmt.Printf("写入 public 失败: %v\n", err)
		return
	}
	fmt.Println("嵌入资源已复制")
}

这个示例要求项目中存在 static 目录。fs.Sub 返回的文件系统根变成该目录，所以 static/index.html 会落到 public/index.html。

按错误边界排查失败原因

复制失败时先不要把所有错误都归结为权限问题。最常见的判断是目标冲突：

package main

import (
	"errors"
	"fmt"
	"io/fs"
	"os"
)

func copyTree(target string, source fs.FS) error {
	// 保留 CopyFS 的原始错误，便于调用方区分冲突和其他失败。
	if err := os.CopyFS(target, source); err != nil {
		if errors.Is(err, fs.ErrExist) {
			return fmt.Errorf("目标文件已存在，请清理或换目录: %w", err)
		}
		return fmt.Errorf("复制目录树失败: %w", err)
	}
	return nil
}

如果 errors.Is(err, fs.ErrExist) 为真，说明目标中已有相同文件名；不要期待 CopyFS 自动覆盖。其他错误再检查源文件系统是否能按合法相对路径打开、目标父级是否可写以及路径上的软链接是否符合预期。官方文档还说明，目标目录中的软链接会被跟随；复制过程中源文件系统新增的文件不保证一定被复制。

复制前后的反向检查清单

把 os.CopyFS 接到构建、解包或部署流程前，可以按下面顺序做一次轻量检查：

1. 确认运行环境至少是 Go 1.23，并确认编译使用的标准库版本。
2. 用一个具体相对路径确认 fsys 的根，尤其检查 embed.FS 是否需要 fs.Sub。
3. 明确目标目录是否允许非空；不允许覆盖时，把 fs.ErrExist 当成可处理结果。
4. 确认目标父目录的写权限、软链接行为和 umask，不要用“复制完成”代替错误处理。
5. 如果源目录在复制期间会变化，不要把结果当成一致快照；先准备稳定的源文件系统。

一句话总结：os.CopyFS 负责把一个 fs.FS 视图落到磁盘，真正决定结果的是源根路径、目标是否已有文件，以及你是否按 fs.ErrExist 和其他原始错误分别处理。

常见问题

os.CopyFS 会覆盖目标文件吗？

不会。目标中已有同名文件时会返回错误，并且可以用 errors.Is(err, fs.ErrExist) 判断。

os.CopyFS 从哪个版本开始提供？

官方文档标注它从 Go 1.23.0 加入。使用更早版本时需要改用其他文件遍历与写入方案。

为什么复制后多了一层 static？

通常是因为直接复制了包含 static 顶层目录的 embed.FS。用 fs.Sub(embedded, "static") 调整根后再复制即可。