Go os.OpenFile 怎样在文件已存在时拒绝覆盖

我在做一次性生成文件时，最容易踩到的坑不是写入，而是“文件已经存在时到底要不要碰它”。如果需求是“没有就创建，有就立即失败”，Go 里不要先调用 os.Stat 再调用 os.Create，而应该把 os.O_CREATE 和 os.O_EXCL 一起传给 os.OpenFile。

最小写法是：

package main

import (
    "errors"
    "fmt"
    "os"
)

func createOnce(path string) error {
    // O_CREATE 负责“没有就创建”，O_EXCL 让已有路径直接失败。
    file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
    if err != nil {
        // ErrExist 只表示目标已存在，其他错误仍要交给调用方处理。
        if errors.Is(err, os.ErrExist) {
            return fmt.Errorf("文件已存在：%s", path)
        }
        return fmt.Errorf("排他创建失败：%w", err)
    }
    // 创建成功后立刻登记关闭责任，避免句柄泄漏。
    defer file.Close()

    // 这里可以继续写入；本例只演示排他创建，不覆盖已有内容。
    return nil
}

这段代码的关键不是 0o644，而是三个标志的组合：O_CREATE 允许创建新文件，O_EXCL 在它与 O_CREATE 同时出现时要求目标不能已经存在。成功时拿到的是新文件句柄；目标存在时则会得到可用 errors.Is(err, os.ErrExist) 识别的错误。

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

真正拒绝覆盖，靠的是两个标志一起出现

我第一次只看到 O_EXCL 时，也容易把它理解成“独立的禁止覆盖开关”。实际使用时应把它和 O_CREATE 看成一个组合：

• os.O_CREATE：路径不存在时创建文件；路径已经存在时并不会自动拒绝打开。
• os.O_EXCL：与 os.O_CREATE 一起使用时，要求创建动作具有排他性。
• os.O_TRUNC：打开成功后把文件长度截断为零。在“不允许覆盖”的需求里不要顺手加上它。

所以，锁文件、一次性导出文件、只允许首个任务生成的标记文件，通常从下面这一组开始：

flags := os.O_WRONLY | os.O_CREATE | os.O_EXCL
// 权限只在创建新文件时参与初始模式设置；已有文件不会被这次调用改写。
file, err := os.OpenFile("job.ready", flags, 0o644)

这里没有加入 O_APPEND 或 O_TRUNC，因为文章讨论的是“只创建一次”，不是追加写或覆盖写。

文件已存在时，应该怎样识别这个结果

工程代码不要只比较错误字符串。文件已存在只是其中一种失败原因，目录无权限、父目录不存在、路径指向目录等情况都可能返回别的错误。用 errors.Is 判断 os.ErrExist，既能保留包装错误的信息，也不会把所有打开失败都误报成“已经生成”。

func openMarker(path string) (*os.File, error) {
    // O_EXCL 让第一个成功创建者拿到句柄，后来的调用收到 ErrExist。
    file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
    if err == nil {
        return file, nil
    }

    // 用 errors.Is 识别语义，不依赖平台错误文本的具体写法。
    if errors.Is(err, os.ErrExist) {
        return nil, fmt.Errorf("跳过重复任务：%w", err)
    }
    return nil, fmt.Errorf("无法创建标记文件：%w", err)
}

0o600 适合只让当前用户读取或写入的标记文件；它不是排他性的来源。排他性来自 O_CREATE|O_EXCL，权限模式只决定新文件创建时的访问位。

为什么不推荐先 Stat 再 Create

“先检查，不存在再创建”看起来直观，但两个系统调用之间有窗口：

// 这段写法有竞态：两个进程可能同时看到不存在，然后同时尝试创建。
if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) {
    // 在这里到 os.Create 之间，另一个进程可能已经占用了 path。
    file, createErr := os.Create(path)
    if createErr != nil {
        return createErr
    }
    defer file.Close()
}

即使 Stat 的结果准确，也只能说明检查那一刻的状态，不能替你保留后续创建的独占权。对一次性资源来说，检查和创建应该合并到一次 OpenFile 请求里，让操作系统在创建条件不满足时直接返回错误。

写入成功后别忘了关闭句柄

排他创建成功只代表句柄已经打开，不代表后续写入、同步和关闭都自动完成。需要写内容时，可以把写入错误和关闭错误分开处理；如果只是创建一个占位标记，也至少要用 defer file.Close() 释放句柄。

func writeOnce(path string, data []byte) error {
    // 只允许不存在的路径创建，避免误清空旧文件。
    file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640)
    if err != nil {
        return err
    }
    defer file.Close()

    // 写入失败必须返回，不能因为文件已经创建就当作任务成功。
    if _, err := file.Write(data); err != nil {
        return fmt.Errorf("写入新文件失败：%w", err)
    }
    return nil
}

如果业务把“文件创建成功”视为资源占用凭证，那么写入失败后的清理策略要由业务决定：有的任务保留半成品供恢复，有的任务会在确认句柄关闭后删除它。这里不额外引入临时文件命名流程，避免把“拒绝覆盖”的问题和“如何原子替换最终文件”混在一起。

按文件状态选择最小配置

我现在会把这张表当作代码审查时的快速检查：只要需求写的是“第一个任务成功，后续任务跳过”，就优先看有没有 O_CREATE|O_EXCL，再看调用方是否把 os.ErrExist 当成可预期分支处理。

最后记住这几个边界

1. O_EXCL 不应脱离 O_CREATE 被当成独立的排他创建方案。
2. O_CREATE 单独使用不会拒绝打开已有文件，和 O_TRUNC 组合时还可能清空内容。
3. 不要用 Stat 与后续创建的串联结果替代一次排他打开请求。
4. 用 errors.Is(err, os.ErrExist) 识别已存在，其余错误继续向上返回。
5. 创建成功后及时关闭句柄，并根据业务决定写入失败后的残留文件处理方式。

相关问题

os.Create 为什么不能用来拒绝覆盖？

os.Create 是便捷的创建或截断打开方式，适合明确要重写文件的场景；它没有表达“已有路径必须失败”的 O_EXCL 组合。

文件已经存在时能不能继续追加？

可以，但那是另一个需求。使用 O_APPEND 表达追加写，并接受已有文件被打开；不要把追加写和排他创建混为一谈。

权限值会让 O_EXCL 失效吗？

不会。权限值主要影响新文件创建时的初始访问位，排他创建是否成立取决于 O_CREATE|O_EXCL 的组合和底层文件系统对该请求的处理。