Go os.CopyFS 复制嵌入文件时如何处理目录权限

用 embed.FS 发布模板、静态资源或默认配置时，os.CopyFS 的目录权限不能按源目录权限直接理解。它会把目录按 0o777 创建，再交给系统 umask 处理；普通文件按 0o666 创建，只额外保留源文件的执行位。官方文档：https://pkg.go.dev/os#CopyFS。

先分清源权限与目标目录权限

CopyFS 复制的是一个 fs.FS 的目录树，不是把 Unix 文件属性原封不动打包到目标目录。它用 fs.WalkDir 遍历源文件系统，遇到目录时按目录模式创建，遇到普通文件时使用固定读写基线并叠加源文件的执行位。

这意味着嵌入资源即使来自一个权限看起来很严格的目录，复制后的普通文件也不会自动继承源文件的所有者、组、读写位或特殊位。生产环境真正要关心的是目标进程的 umask、父目录可写性，以及复制完成后是否需要额外调用 os.Chmod。

用 embed.FS 复制资源并保留执行位

下面的例子把 public 目录嵌入二进制，再复制到发布目录。这里先用 os.Stat 判断目标是否已存在，避免把“目标目录已经有旧文件”误认为权限问题；目录不存在时才交给 CopyFS 创建。

package main

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

//go:embed public
var assets embed.FS

func installAssets(dst string) error {
    // 目标目录已存在时仍允许复制，但 CopyFS 不会覆盖其中的同名文件。
    if info, err := os.Stat(dst); err == nil && !info.IsDir() {
        return fmt.Errorf("目标不是目录: %s", dst)
    } else if err != nil && !errors.Is(err, os.ErrNotExist) {
        return fmt.Errorf("检查目标目录失败: %w", err)
    }

    // CopyFS 负责创建缺失目录；其目录模式还会受到 umask 影响。
    if err := os.CopyFS(dst, assets); err != nil {
        if errors.Is(err, fs.ErrExist) {
            return fmt.Errorf("资源已存在，拒绝覆盖: %w", err)
        }
        return fmt.Errorf("复制嵌入资源失败: %w", err)
    }
    return nil
}

func main() {
    // 生产代码中把目标路径放到配置里，并记录失败原因即可。
    if err := installAssets("./release"); err != nil {
        fmt.Println(err)
    }
}

示例中的“保留执行位”是指源文件的执行位会进入新文件模式，不代表复制后一定可执行。目标文件还要满足解释器、 shebang、挂载选项和运行用户等条件；如果只是 HTML、JSON 或模板，通常不应该人为给它加执行权限。

把权限检查放在 CopyFS 返回之后

权限检查要看目标路径的实际状态，而不是把传给创建函数的模式当成最终结果。Unix 下可以读取 FileMode.Perm()，但最终值已经经过 umask；跨平台代码则应把“必须可读”“必须可写”“脚本必须可执行”作为业务条件，而不是只比较一串八进制数字。

func checkCopiedPath(path string, wantExec bool) error {
    info, err := os.Stat(path)
    if err != nil {
        return fmt.Errorf("读取复制结果失败: %w", err)
    }
    if info.IsDir() {
        // 目录需要进入和读取能力，具体模式由平台与 umask 决定。
        if info.Mode().Perm()&0o700 == 0 {
            return fmt.Errorf("目录缺少所有者访问权限: %s", path)
        }
        return nil
    }
    if info.Mode().Perm()&0o400 == 0 {
        return fmt.Errorf("文件不可读: %s", path)
    }
    if wantExec && info.Mode()&0o111 == 0 {
        return fmt.Errorf("文件缺少执行位: %s", path)
    }
    return nil
}

更稳妥的做法是只检查应用真正依赖的能力：配置文件检查可读，静态目录检查能遍历，脚本文件才检查执行位。不要因为看到目录不是 0777 就直接失败，那样会把正常的最小权限部署和错误配置混在一起。

处理已有文件、失败回滚与跨平台差异

CopyFS 使用排他创建语义，发现同名文件就返回可识别为 fs.ErrExist 的错误。因此它适合“只安装缺失资源”的初始化流程，不适合直接承担覆盖式升级。要做升级，建议先复制到新目录，完成检查后再用平台合适的原子切换方案替换目录。

复制过程中如果中途遇到权限不足，目标目录可能已经留下前面成功写入的文件。CopyFS 不承诺事务回滚，调用方应把临时目录清理或隔离作为发布策略的一部分；不要收到一个错误后继续把同一目录当成干净目标重试。

• 目录创建失败：优先检查父目录的写入和执行权限、运行用户以及挂载选项。
• fs.ErrExist：说明目标存在同名文件，先决定保留、备份还是切换目录，不要盲目修改权限。
• Windows：Unix 的所有者/组权限位不具备同样含义，业务检查应围绕可读、可写和可执行结果。
• 需要更严格边界时：复制后显式 Chmod，并把目标目录权限检查纳入部署日志。

相关问题

os.CopyFS 会完整保留 embed.FS 中的文件权限吗？

不会。普通文件以 0o666 为基线，只保留源文件的执行位；目录按 0o777 创建并受 umask 影响。

为什么 CopyFS 复制第二次会报文件已存在？

它不会覆盖已有文件，错误可以用 errors.Is(err, fs.ErrExist) 判断。需要覆盖式发布时应更换目标目录或自行设计替换策略。

怎么确认复制后的目录权限？

在复制成功后对目标路径调用 os.Stat，读取 Mode().Perm()，并按应用实际需要检查可读、可写、可遍历或执行能力。