Go os.OpenFile 的 O_EXCL 如何避免覆盖已有文件

如果文件名必须“只成功占一个”，不要先 os.Stat 再 os.Create。这两个调用之间可能被另一个进程插入。Go 的正确组合是 os.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)：目标不存在时创建，目标已存在时直接失败，原文件不会因为打开动作被截断。

官方地址：https://pkg.go.dev/os

O_EXCL 不是单独的“防覆盖开关”，必须和 O_CREATE 一起使用。成功看返回的文件句柄，已存在看 errors.Is(err, fs.ErrExist)，其他错误则按权限、目录或路径问题继续处理。

一、O_CREATE 和 O_EXCL 必须一起出现

OpenFile 的第一个参数是路径，第二个参数是打开模式，第三个参数是创建时权限。O_CREATE 负责“没有就创建”，O_EXCL 负责把“已经存在”变成失败条件；两者缺一不可。权限 0600 表示创建者可读写，实际权限还会受系统 umask 影响。

package main

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

func createOnce(path string, data []byte) error {
	// O_EXCL 必须和 O_CREATE 组合，避免已存在文件被打开后覆盖。
	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
	if err != nil {
		// 用标准错误分类识别“文件已存在”，不要依赖英文错误文本。
		if errors.Is(err, fs.ErrExist) {
			return fmt.Errorf("文件已存在: %w", err)
		}
		return fmt.Errorf("创建文件失败: %w", err)
	}

	// 只有拿到新文件句柄后才写入，并把关闭错误返回给调用方。
	if _, err = f.Write(data); err != nil {
		_ = f.Close() // 写入失败时尽力释放句柄，保留原始写入错误。
		return fmt.Errorf("写入失败: %w", err)
	}
	if err = f.Close(); err != nil {
		return fmt.Errorf("关闭文件失败: %w", err)
	}
	return nil
}

二、别用字符串比较错误

文件已存在时，返回值通常会包在 *os.PathError 中。错误文本可能因操作系统、路径和语言环境变化，直接写 err.Error() == "file exists" 很脆弱。errors.Is 会沿着包装链判断它是否属于 fs.ErrExist，既能保留上下文，也能稳定分支。

这里的判断顺序也有实际价值：已存在是可预期的竞争结果，可以转成“跳过、换名或读取已有文件”的业务分支；权限不足、父目录不存在、路径是目录等情况则应保留为真正的失败。

三、写入与关闭要和创建语义分开核对

拿到句柄只说明“创建动作成功”，不等于业务数据已经安全落盘。写入返回值要检查，Close 也可能报告缓冲或文件系统错误。创建唯一文件时通常不需要 O_TRUNC；把它加进去会让代码意图混乱，而且它解决的是“打开后清空”，不是“禁止已有文件被打开”。

四、用三项指标验收并发语义

不必把“没有覆盖”写成口号，可以把验收指标固定下来：对同一路径发起 N 次独占创建，成功数应为 1；其余调用中，预期的已存在错误数应为 N-1；最后读取原文件，字节内容必须和第一次写入完全一致。若出现权限错误或目录错误，应单独统计，不能混进已存在数量。

这组指标比先检查文件是否存在更可靠，因为判断和创建由同一次系统调用完成。需要跨平台部署时，还要以目标系统对文件标志的实现为准；Go 文档也提醒，并非所有标志在每个平台都一定实现。

相关问题

O_EXCL 单独使用能防止覆盖吗？

不要这样设计。它的文档语义是与 O_CREATE 一起使用，目标文件必须不存在；代码应明确写出二者的组合。

为什么不推荐比较 err.Error()？

因为错误文本包含操作和路径，且平台实现不同。用 errors.Is(err, fs.ErrExist) 判断类别，再保留原错误上下文更稳妥。