Go os.CopyFS 怎样把嵌入文件系统复制到磁盘处理空输入并保留错误边界

把内置资源释放到磁盘时，最容易混在一起的是三个问题：复制源到底是整个 embed.FS 还是其中一个子目录；空目录是不是业务异常；目标文件已经存在时，调用方能不能分辨出“不可覆盖”。这篇用 os.CopyFS 把这三层拆开。

官方文档：https://pkg.go.dev/os#CopyFS

实用写法是先用 fs.Sub 选定嵌入目录，再按业务需要检查空输入，最后直接保留 os.CopyFS 返回的错误。fs.ErrExist 用 errors.Is 判断，其他错误不要改写成一个笼统的“复制失败”。

先确认复制对象是 fs.FS 的哪一层

os.CopyFS(dir, fsys) 复制的是 fsys 看到的文件树。嵌入文件通常有一个外层目录，例如 assets。如果直接把整个 embed.FS 传进去，目标目录下面会多一层 assets；如果希望目标目录直接得到资源文件，就先用 fs.Sub 取出这棵子树。

下面的函数把资源目录复制到磁盘，同时保留错误类型。示例假定项目中存在 assets/default.conf：

package main

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

//go:embed assets
var embedded embed.FS

func copyEmbeddedAssets(dst string) error {
	// 只把 assets 子树交给复制函数，避免目标目录多出一层 assets。
	source, err := fs.Sub(embedded, "assets")
	if err != nil {
		return fmt.Errorf("选择嵌入资源目录: %w", err)
	}

	// 先读取根目录，给“没有资源”留下明确的业务分支。
	entries, err := fs.ReadDir(source, ".")
	if err != nil {
		return fmt.Errorf("读取嵌入资源目录: %w", err)
	}
	if len(entries) == 0 {
		return fmt.Errorf("嵌入资源目录为空")
	}

	// CopyFS 会创建目标目录，但不会覆盖其中已有的同名文件。
	if err := os.CopyFS(dst, source); err != nil {
		return fmt.Errorf("复制嵌入资源到 %q: %w", dst, err)
	}
	return nil
}

func main() {
	if err := copyEmbeddedAssets("./runtime-assets"); err != nil {
		// 调用方可以继续用 errors.Is / errors.As 判断原始错误。
		fmt.Println(err)
		return
	}
	fmt.Println("资源复制请求已完成")
}

这里的 fs.Sub 只改变复制视角，不会把文件从二进制中“搬走”。目标目录是否已经存在、是否可写，仍然由操作系统和 CopyFS 的文件创建过程决定。

把空输入、已存在文件和底层错误分开

空输入和复制失败不是同一件事。按照 CopyFS 的 API 语义，空的 fs.FS 没有要复制的文件；是否把它视为错误，应由业务决定。上面的 fs.ReadDir 检查就是一个显式策略：资源包为空时提前返回业务错误，避免上线后才发现打包阶段漏了文件。

相反，目标中已经有同名文件属于复制过程的明确边界。CopyFS 不会覆盖已有文件，并会返回一个能被 errors.Is(err, fs.ErrExist) 识别的错误。权限不足、目标路径被阻塞或源文件读取失败，则保留为底层错误。

func classifyCopyError(err error) string {
	// 先判断目标文件已存在，避免把可处理的重复部署误报成未知故障。
	if errors.Is(err, fs.ErrExist) {
		return "目标文件已存在"
	}

	var pathErr *os.PathError
	if errors.As(err, &pathErr) {
		// PathError 保留了操作名和路径，日志中应继续输出这些上下文。
		return fmt.Sprintf("路径操作失败: op=%s path=%s", pathErr.Op, pathErr.Path)
	}
	return "其他复制错误"
}

包装错误时使用 %w，调用方才能继续用 errors.Is 和 errors.As 追溯原因。若直接用 %v 拼成字符串，错误分类信息就会丢失。

重复部署时为什么不能先 RemoveAll

有些初始化代码会在复制前调用 os.RemoveAll(dst)，这样确实能绕过“文件已存在”，但也把目标目录中不属于本次资源包的文件一并删除了。对于配置、模板或静态资源部署，更稳妥的选择通常是保留 fs.ErrExist，让调用方决定是否备份、人工确认或切换到一个新的版本目录。

如果业务明确要求“同名文件允许更新”，CopyFS 就不是完整的覆盖策略。可以先复制到临时目录，再由部署层做目录切换；也可以按文件逐个读取并采用明确的覆盖标志。不要把删除旧目录作为通用补丁。

几个容易误判的边界

另外，目标目录中的符号链接会被跟随；这意味着不能把 CopyFS 当成额外的路径隔离机制。需要严格限制访问范围时，应先确认源文件和目标目录的权限、链接布局以及部署账户的能力。

最后用一张清单收口

• 复制嵌入目录中的内容时，先用 fs.Sub 取出正确子树。
• 把空输入当作业务策略处理，不把它和 fs.ErrExist、权限错误混为一谈。
• 用 errors.Is 识别不可覆盖，用 errors.As 保留 PathError 上下文。
• 重复部署不要默认 RemoveAll；需要覆盖时，把覆盖策略放到更明确的部署层。
• 将嵌入资源视为固定输入，提前确认符号链接和目标目录权限。

相关问题

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

官方文档将它标记为 Go 1.23.0 新增。使用更早版本的项目需要继续采用手动遍历、读取和创建文件的方案，不能只改 import 就获得这个 API。

os.CopyFS 会覆盖目标目录中的同名文件吗？

不会。已有文件会形成可用 errors.Is(err, fs.ErrExist) 判断的错误，调用方应按幂等部署、备份或版本切换策略处理。

为什么要保留 %w 包装？

因为 fs.ErrExist 和 *os.PathError 都是调用方做稳定分支判断的重要信息。使用 %w 可以在增加上下文的同时保留这条错误链。