Go os.Rename 跨文件系统失败时该用什么方案

把上传临时目录里的文件移动到数据盘时，os.Rename 可能返回 invalid cross-device link。这不是把路径写错了，而是一次 Rename 不能直接跨越两个文件系统。稳妥方案是：先在目标目录创建临时文件，用 io.Copy 把内容复制过去，确认写入完成后，再用目标目录内的 os.Rename 切换，最后才删除源文件。

跨文件系统移动不能靠反复重试 Rename 解决；把“跨设备复制”和“目标目录内切换”拆开，才能避免半个文件被当成正式结果。

为什么跨文件系统时 Rename 会失败

Go 文档把 os.Rename(oldpath, newpath) 定义为重命名或移动，并明确提示不同目录可能存在操作系统限制；出错时返回 *LinkError。在 Unix 场景中，源路径和目标路径属于不同挂载点时，底层常见错误就是 EXDEV。它表达的是文件系统边界不允许这次原子移动，不是 Go API 少传了某个参数。

先看错误类型，再决定方案：

复制完成后怎样安全替换目标文件

关键是临时文件必须由 os.CreateTemp(filepath.Dir(dst), ".move-*") 在目标目录创建。这样，复制虽然跨越文件系统，但最后的 Rename 只发生在目标文件系统内部。下面的函数还保留了源文件权限，并把临时文件清理放进失败分支。

package filemove

import (
    "fmt"
    "io"
    "os"
    "path/filepath"
)

func MoveAcrossFilesystems(src, dst string) error {
    // 读取源文件的权限，避免目标文件意外使用过宽权限。
    info, err := os.Stat(src)
    if err != nil {
        return fmt.Errorf("stat source: %w", err)
    }

    dir := filepath.Dir(dst)
    tmp, err := os.CreateTemp(dir, ".move-*")
    if err != nil {
        return fmt.Errorf("create target temp: %w", err)
    }
    tmpName := tmp.Name()
    committed := false
    defer func() {
        // 只有切换成功，临时文件才已经变成正式目标。
        if !committed {
            _ = os.Remove(tmpName)
        }
    }()

    in, err := os.Open(src)
    if err != nil {
        _ = tmp.Close()
        return fmt.Errorf("open source: %w", err)
    }
    _, copyErr := io.Copy(tmp, in)
    closeInErr := in.Close()
    if copyErr != nil {
        _ = tmp.Close()
        return fmt.Errorf("copy source: %w", copyErr)
    }
    if closeInErr != nil {
        _ = tmp.Close()
        return fmt.Errorf("close source: %w", closeInErr)
    }

    if err := tmp.Chmod(info.Mode().Perm()); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("preserve mode: %w", err)
    }
    if err := tmp.Sync(); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("sync target temp: %w", err)
    }
    if err := tmp.Close(); err != nil {
        return fmt.Errorf("close target temp: %w", err)
    }
    if err := os.Rename(tmpName, dst); err != nil {
        return fmt.Errorf("replace target: %w", err)
    }
    committed = true
    if err := os.Remove(src); err != nil {
        return fmt.Errorf("remove source after commit: %w", err)
    }
    return nil
}

这里的提交点是目标目录内的 os.Rename(tmpName, dst)。如果复制或同步失败，正式目标不会被半成品覆盖；如果切换成功但删除源文件失败，函数会返回错误，但目标文件已经存在，此时重试前应先确认源文件是否仍然存在，避免把一次“清理失败”误判成“移动未发生”。

覆盖文件、权限和恢复怎么取舍

os.Rename 在目标已存在且不是目录时，文档描述为替换目标；但不同平台仍有差异，尤其是 Windows 上目标文件被其他进程打开时可能无法替换。生产代码不要把“Rename 成功”扩展成“所有元数据都已复制”：示例只保留权限位，属主、ACL、扩展属性和时间戳要按业务需要单独处理。

如果目标文件特别重要，可以把目标目录权限、剩余空间、目标是否为目录纳入前置检查；把临时文件名前缀固定在目标目录，便于进程重启后清理遗留文件。若要求更强的断电持久性，Sync 能让文件内容先完成同步，但目录项持久化还要结合具体操作系统和文件系统评估，不能把它宣传成跨平台事务。

两个容易混淆的边界

为什么不直接复制到 dst？ 直接写正式目标会让读者或下游进程看到半个文件。目标目录临时文件配合最后一次 Rename，能把“写入中”和“可读取”分开。

为什么不在 Rename 失败后继续重试？ 跨设备限制是路径拓扑决定的，重试不会改变文件系统边界；只有在确认错误是瞬时占用、权限或目标状态变化时，重试才可能有意义。

相关官方说明可参考 os.Rename、io.Copy 和 os.CreateTemp。把复制、提交、清理三个动作分别记录日志，排查时就能知道失败发生在数据传输、目标切换还是源文件回收。