Go os.WriteFile 的权限为什么和 0666 不一样：umask、创建与覆盖的边界

配置文件刚由 Go 服务写出来，团队用 0666 读取权限，却在机器上看到的却是 0644，甚至第二次部署后权限完全没有变化。这个现象通常不是 os.WriteFile 忽略了参数，而是“首次创建”和“覆盖已有文件”走了两条不同路径，Unix 的 umask 还会参与首次创建。

os.WriteFile 创建新文件时，传入的 perm 先经过进程 umask；文件已存在时，它会截断并重写内容，但不会替换原有权限。

先区分创建文件和覆盖文件

线上最常见的误判是把 perm 当成“每次写入后的权限设置”。实际上，os.WriteFile(name, data, perm) 只有在目标不存在时才用 perm 请求创建权限；目标存在时，文件先被截断，再写入新内容，原来的模式位保留下来。

path := "runtime/app.conf"
err := os.WriteFile(path, []byte("port=8080\n"), 0o666)
if err != nil {
    log.Fatal(err)
}

info, err := os.Stat(path)
if err != nil {
    log.Fatal(err)
}
fmt.Println(info.Mode().Perm())

因此，第一次启动可能得到一个受 umask 影响的模式；第二次启动即使把第三个参数改成 0o600，也不代表旧文件会自动收紧到 0600。这就是排查时必须先问“这个文件是不是已经存在”的原因。

创建路径：perm 还要经过 umask

在类 Unix 系统上，创建新文件的最终权限可以粗略理解为：请求权限和 umask 的反向掩码共同作用。比如请求 0666，当前 umask 若为 0022，常见结果就是 0644。这不是 Go 私自修改了八进制数字，而是操作系统的创建规则在生效。

下面的程序只负责观察文件模式，不在进程内修改 umask：

func writeAndInspect(path string) error {
    if err := os.WriteFile(path, []byte("secret=false\n"), 0o666); err != nil {
        return err
    }
    info, err := os.Stat(path)
    if err != nil {
        return err
    }
    fmt.Printf("%s: %04o\n", path, info.Mode().Perm())
    return nil
}

不要为了“读取 umask”而在业务 goroutine 中随意调用 syscall.Umask。它是进程级状态，临时修改会影响同一进程里的其他创建操作；更稳妥的做法是让启动环境明确设置策略，再通过一个全新的临时文件和 os.Stat 验证结果。

覆盖路径：改 perm 不会改原有权限

如果部署脚本先用较宽的权限创建了 app.conf，服务后来改成：

err := os.WriteFile("runtime/app.conf", []byte("port=9090\n"), 0o600)
if err != nil {
    return err
}

这次调用的主要效果是清空旧内容并写入新内容，已有文件的权限仍由原模式决定。想让已有文件也符合目标权限，需要把写入和权限收敛分开验收：

if err := os.WriteFile(path, data, 0o600); err != nil {
    return err
}
if err := os.Chmod(path, 0o600); err != nil {
    return err
}
info, err := os.Stat(path)
if err != nil {
    return err
}
if got := info.Mode().Perm(); got != 0o600 {
    return fmt.Errorf("unexpected mode: %04o", got)
}

这里的 os.Chmod 是明确的策略动作：它把文件收敛到预期的目标模式，不是对 WriteFile 参数的补注释。若多个进程同时写同一路径，还要把临时文件、重命名和权限策略一起设计，避免一个进程刚收紧权限，另一个进程又替换了文件。

一个可复现的现场检查顺序

1. 先把目标路径改成测试目录下的新文件，避免直接碰生产配置。
2. 用 os.Remove 确保第一次运行确实走创建路径，再调用 os.WriteFile 和 os.Stat 记录模式。
3. 第二次只修改 perm 后重写同一文件，观察模式是否保持不变。
4. 如果业务要求固定模式，调用 os.Chmod 后再次用 os.Stat 验证，而不是只看日志里的参数。

测试断言应关注两条事实：新文件的结果受创建环境影响，已有文件的结果受旧模式影响。这样才能把 Go 代码问题和部署用户的 umask 配置区分开。

几个容易被权限问题掩盖的风险

WriteFile 需要多个系统调用，写入中途失败时可能留下部分内容。权限检查通过，并不等于配置文件内容已经完整落盘；关键配置更适合写入临时文件、完成校验后再替换，并把恢复路径纳入部署脚本。

另外，0666 本身不包含执行位，目录权限也不由它决定。若父目录不存在，WriteFile 不会替你创建目录；如果错误是 no such file or directory，先检查目录链路，不要把它误诊为 umask。

常见问题

为什么我传了 0600，文件还是 0644？

最先检查文件是否在调用前已经存在。存在时 WriteFile 会保留原权限；如果必须统一成 0600，写入后显式执行 os.Chmod 并用 os.Stat 验证。

umask 是 Go 变量吗？

不是。它是操作系统层面的进程创建权限掩码，通常由启动环境或父进程设置。Go 的 os.WriteFile 遵循系统创建规则，不会把它变成函数参数。

覆盖文件会再次应用 umask 吗？

不会按新文件创建路径重新计算。覆盖已有文件时，内容被截断后写入，原有权限不因本次 perm 或 umask 自动改变。

小结

把 os.WriteFile 的权限问题拆成两条路径就清楚了：创建时看 perm 与 umask，覆盖时看原有模式。先用 os.Stat 证明文件状态，再决定是否用 os.Chmod 收敛权限，排查会比反复修改 0666 更快。