Go 文件权限 umask 与 Chmod 结果的关系

在 Unix 类系统中，Go 创建文件或目录时，传入的 perm 是“应用 umask 之前”的权限；最终权限可理解为 perm &^ umask。os.Chmod 处理的是已经存在的文件，它直接设置支持的权限位，不会再把 umask 套一遍。因此，OpenFile(..., 0666) 在 umask 为 0022 时通常得到 0644，随后执行 os.Chmod(path, 0666) 则会把它改成 0666。

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

一、先划清目标：创建权限和修改权限是两个阶段

我见过最容易混淆的场景是：代码把创建权限写成 0666，落盘后却看到 0644；开发者接着怀疑 Go 忽略了参数。其实 0666 只是创建请求，进程的 umask 会清除其中不允许的位。这个规则只参与新对象创建，不是一个永久附着在文件上的过滤器。

完整判断可以先分成两条：

• 新建文件或目录：os.OpenFile、os.WriteFile、os.Mkdir 等函数的 perm 会受 umask 影响。
• 修改已有对象：os.Chmod 或 File.Chmod 直接修改当前文件模式，umask 不参与。

如果 OpenFile 打开的文件已经存在，perm 参数不会重设原权限；它只有在 O_CREATE 真正创建新文件时才有作用。这也是“同一段代码第一次和第二次结果不同”的常见原因。

二、用一个公式看懂创建权限

对普通 Unix 权限位，可以用下面的按位关系预测结果：

最终权限 = 请求权限 &^ umask

&^ 是 Go 的按位清除运算：umask 中为 1 的位会从请求权限中移除。例如，请求权限 0666 配合 umask 0022，组和其他用户的写位被清除，得到 0644；请求目录权限 0777 配合同一 umask，则得到 0755。

umask 只能清除创建请求中的位，不能凭空增加权限。若代码请求 0600，一个常见的 0022 umask 不会把组或其他用户的读取权限加回来。

三、创建阶段：哪些 Go API 会受 umask 影响

Go 的 os 文档会明确标注 perm (before umask)。常见入口包括 OpenFile 在带 O_CREATE 且文件不存在时、WriteFile 创建新文件时，以及 Mkdir、MkdirAll 创建目录时。os.Create 创建新文件使用 0666，同样先经过 umask。

package main

import (
    "fmt"
    "os"
)

func main() {
    // 0666 是创建请求；Unix 最终权限还要清除进程 umask 指定的位。
    f, err := os.OpenFile("report.txt", os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o666)
    if err != nil {
        panic(err)
    }

    // 先关闭文件再读取元数据，避免遗漏写入或关闭错误。
    if _, err := f.WriteString("ready\n"); err != nil {
        _ = f.Close()
        panic(err)
    }
    if err := f.Close(); err != nil {
        panic(err)
    }

    info, err := os.Stat("report.txt")
    if err != nil {
        panic(err)
    }
    // Perm 只保留九个基础权限位，便于用八进制核对。
    fmt.Printf("%04o\n", info.Mode().Perm())
}

O_EXCL 与 O_CREATE 一起使用，可以确保示例确实走“新建”分支；如果文件已经存在，调用会返回错误，而不是让旧权限干扰判断。业务代码是否需要 O_EXCL 取决于覆盖策略，但排查权限时它很有价值。

os.WriteFile 也有同样的边界：文件不存在时用传入的 perm 创建；文件已经存在时会截断并写入，但不会修改原权限。想重设已有文件权限，必须显式调用 Chmod。

四、Chmod 属于修改阶段

os.Chmod(name, mode) 把已有文件的模式改为 mode。在 Unix 上，基础权限位以及受支持的 setuid、setgid、sticky 位会按参数处理，umask 不会重新过滤。若路径是符号链接，os.Chmod 修改的是链接目标，而不是链接本身。

package main

import (
    "fmt"
    "os"
)

func main() {
    // 先创建一个仅所有者可访问的敏感文件。
    if err := os.WriteFile("secret.txt", []byte("token-placeholder\n"), 0o600); err != nil {
        panic(err)
    }

    // Chmod 修改已有文件；Unix 下不会再套用进程 umask。
    if err := os.Chmod("secret.txt", 0o640); err != nil {
        panic(err)
    }

    info, err := os.Stat("secret.txt")
    if err != nil {
        panic(err)
    }
    // 预期 Unix 权限为 0640：所有者读写，组只读。
    fmt.Printf("%04o\n", info.Mode().Perm())
}

这也解释了一个反直觉现象：进程 umask 是 0077 时，os.WriteFile(path, data, 0666) 新建结果通常是 0600；但紧接着 os.Chmod(path, 0644) 后，其他用户读取位会被显式打开。不要把严格 umask 当成后续 Chmod 的安全兜底。

五、推荐流程：先以最小权限创建，再按需要放宽

如果内容敏感，最稳妥的策略不是“按最终宽权限创建，然后立刻收紧”，因为创建和 Chmod 之间存在短暂暴露窗口。更好的顺序是先用 0600 创建、写入并关闭；只有业务确实需要组读取时，再显式改为 0640。即使 Chmod 失败，文件也会停留在更严格的状态。

package securefile

import "os"

func WriteThenPublish(path string, data []byte, finalMode os.FileMode) error {
    // O_EXCL 防止覆盖已有文件；0600 保证创建阶段默认最小暴露。
    f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
    if err != nil {
        return err
    }

    if _, err := f.Write(data); err != nil {
        _ = f.Close()
        _ = os.Remove(path) // 写入失败时删除不完整文件。
        return err
    }
    if err := f.Close(); err != nil {
        _ = os.Remove(path) // 关闭失败也不发布残缺文件。
        return err
    }

    // 写入完整后再放宽权限；失败时文件仍保持创建时的严格权限。
    return os.Chmod(path, finalMode)
}

生产代码还要根据覆盖语义决定是否采用临时文件加原子重命名。无论采用哪种方式，权限检查点都应包括：创建请求、当前进程 umask、目标是否已存在、Chmod 错误，以及最终 Stat 结果。

六、常见误区与平台差异

误区一：给 OpenFile 传 0777，普通文件就会自动可执行

技术上可以请求执行位，但普通数据文件通常不需要可执行权限。文件常用 0600、0640 或 0644，目录才需要执行位来进入和访问其中的条目。不要用 0777 回避权限设计。

误区二：修改进程 umask 只影响当前 goroutine

umask 是进程级状态，不是 goroutine 局部变量。在并发服务里临时切换 umask，其他 goroutine 同时创建的文件也可能受到影响。更可控的做法是传入保守的创建权限，并在单个文件上调用 Chmod。

误区三：跨平台把 Unix 八进制位当成完全一致

Go 文档明确说明，各操作系统使用的模式位子集不同。在 Windows 上，os.Chmod 当前主要使用 0o200（所有者可写）来控制只读属性，其他 Unix 权限位不具备相同含义。因此，依赖 0640、setgid 或 sticky 位的逻辑应限制在相应 Unix 构建目标，并为 Windows 单独定义行为。

七、权限排查速查表

八、相关问题

1. os.Create 为什么通常得到 0644？

os.Create 在文件不存在时以 0666 创建，若进程 umask 为 0022，最终就是 0644。

2. os.Mkdir(path, 0755) 也会受 umask 影响吗？

会。文档中的 perm 同样是应用 umask 前的权限；例如 umask 0027 会把请求的 0755 收紧为 0750。

3. 如何确认 Go 看到的最终权限？

调用 os.Stat，再读取 info.Mode().Perm() 并用八进制输出。不要只看创建参数推测，因为环境 umask、文件是否已存在和后续 Chmod 都会改变判断。

4. Chmod 失败后应该继续使用文件吗？

如果目标权限是安全或共享契约的一部分，就不应静默忽略错误。创建时先采用更严格权限，可以让失败结果保持“拒绝更多访问”，然后由调用方决定删除、重试或报警。