Go os.Rename 跨文件系统为什么失败：临时文件提交与回退复制策略

把上传文件先写到临时目录，再用 os.Rename 改成正式文件名，是 Go 服务里很常见的提交方式。它在临时目录和目标目录属于同一文件系统时通常很稳；一旦两个目录挂载在不同文件系统上，重命名可能返回 invalid cross-device link，而临时文件仍留在原处。

先把“同盘改名”和“跨盘搬运”分开判断：同一文件系统用 os.Rename 做提交，跨文件系统则复制到目标目录、校验写入结果，再删除临时文件。

问题现场：临时文件写好了，改名却失败

假设服务把大文件写入 /var/tmp/upload-123.part，完成后准备提交到 /srv/data/report.csv：

if err := os.Rename(tmpName, finalName); err != nil {
    return fmt.Errorf("commit file: %w", err)
}

日志里出现 rename /var/tmp/upload-123.part /srv/data/report.csv: invalid cross-device link 时，不要先把它改成无条件复制。这个错误说明重命名的两个路径不在同一文件系统，原子改名这条路径本身不成立。

先确认失败发生在哪一步

把保存流程拆成“临时文件”“写入完成”“提交改名”“清理源文件”四个节点，排查时先看错误究竟来自 os.Rename 还是前面的写入。最重要的核对点是：正式文件 不应在提交前出现，临时文件 即使残留也不能被当成下载资源。

可以在部署机器上分别查看两个目录的挂载信息，并确认应用用户对目标目录有写权限。若权限错误，通常会看到 permission denied；若是跨文件系统，才进入回退策略。不要用“复制成功过一次”替代这次运行的结果检查。

同一文件系统：让临时文件直接待在目标目录

最简单的改进不是增加重试，而是把临时文件创建在最终目录中。这样临时文件和正式文件天然共享同一文件系统，写入完成后只需要调用 os.Rename：

f, err := os.CreateTemp(targetDir, ".report-*.part")
if err != nil {
    return err
}
tmpName := f.Name()
defer os.Remove(tmpName)

if _, err := io.Copy(f, src); err != nil {
    _ = f.Close()
    return err
}
if err := f.Close(); err != nil {
    return err
}
if err := os.Rename(tmpName, finalName); err != nil {
    return fmt.Errorf("commit file: %w", err)
}

这里的关键不是临时文件名长什么样，而是 os.CreateTemp 的目录参数。io.Copy 返回成功且文件已关闭后，os.Rename 才有资格成为最后一步；defer os.Remove 则负责异常分支的残留清理。

跨文件系统的安全回退

如果业务必须从一个挂载点读入、另一个挂载点落盘，就不能把 os.Rename 当作搬运工具。回退流程是在目标目录创建新的临时文件，复制完成后关闭它，再改名为正式文件；只有所有步骤成功，才删除源临时文件：

func commitAcrossFilesystems(srcName, targetDir, finalName string) error {
    in, err := os.Open(srcName)
    if err != nil {
        return err
    }
    defer in.Close()

    out, err := os.CreateTemp(targetDir, ".report-*.part")
    if err != nil {
        return err
    }
    partName := out.Name()
    keepPart := true
    defer func() {
        if keepPart {
            _ = os.Remove(partName)
        }
    }()

    if _, err := io.Copy(out, in); err != nil {
        _ = out.Close()
        return err
    }
    if err := out.Close(); err != nil {
        return err
    }
    if err := os.Rename(partName, finalName); err != nil {
        return err
    }
    keepPart = false
    return os.Remove(srcName)
}

这段代码把 os.CreateTemp、io.Copy、os.Rename 和 os.Remove 串成一条有边界的提交链。复制中断时只留下目标目录的 .part；改名成功后才清理源文件。若清理源文件失败，应记录告警并保留正式文件的校验信息，避免为了“回收干净”而删除唯一可用副本。

验证结果：检查正式文件和残留文件

测试不能只断言函数返回 nil。至少覆盖三种结果：同一文件系统下正式文件出现且临时文件消失；复制中途失败时正式文件不存在且目标临时文件可清理；跨文件系统提交成功后正式文件内容与源文件一致。

生产日志建议记录源路径、目标路径、复制字节数和最终错误，但不要把用户上传内容或凭据写入日志。对于同名覆盖，还要先明确业务是否允许覆盖；若不允许，应在提交前用独立的命名或占用检查策略解决，而不是依赖 os.Rename 的平台差异。

常见问题

为什么重试 os.Rename 通常没有用？

跨文件系统是路径所属存储边界造成的，重试不会让两个路径进入同一文件系统。应改为目标目录临时文件加复制回退。

可以先复制再删除源文件吗？

可以，但删除必须放在目标文件成功关闭并完成改名之后；任何复制或提交错误都要保留源文件，方便恢复。

临时文件一定要用 .part 后缀吗？

不是必须。后缀只是帮助下载接口和清理任务识别未提交文件，真正的安全边界是临时文件不进入正式文件路径。

小结

os.Rename 适合在同一文件系统内完成最后一步提交，不适合承担跨挂载点搬运。把临时文件放到目标目录是首选；无法做到时，用目标侧临时文件承接 io.Copy，关闭后再 os.Rename，最后才 os.Remove 源文件，才能把失败留在临时区而不是正式文件区。