Go Rename 为什么跨文件系统移动会失败

如果 os.Rename(src, dst) 在本机目录之间正常，换成挂载盘、容器卷、临时目录或网络文件系统后却失败，最常见的根因不是路径拼错，而是源和目标不在同一个文件系统。Rename 负责改变目录项名称或位置，并不负责把文件内容搬到另一套文件系统；在 Unix 上，这类失败通常会以 EXDEV 形式返回。

跨文件系统移动不能继续依赖一次性的 os.Rename。先用 errors.Is(err, syscall.EXDEV) 识别边界，再把临时文件放在目标目录中完成复制，最后根据业务接受的原子性决定是否删除源文件。

先确认失败是跨文件系统，而不是普通路径错误

Go 文档把 os.Rename 的错误包装为 *os.LinkError，而且明确提示不同目录可能存在操作系统限制。不要把所有错误都当成跨盘问题：权限不足、目标目录不存在、目标是非空目录、文件被占用，都需要不同的处理。

package main

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

func moveByRename(src, dst string) error {
    // Rename 只尝试一次目录项变更，不会偷偷复制大文件。
    if err := os.Rename(src, dst); err != nil {
        var linkErr *os.LinkError
        if errors.As(err, &linkErr) && errors.Is(err, syscall.EXDEV) {
            return fmt.Errorf("源和目标位于不同文件系统: %w", err)
        }
        // 保留原始错误，调用方才能区分权限、路径和目标类型问题。
        return fmt.Errorf("重命名 %s -> %s: %w", src, dst, err)
    }
    return nil
}

判断重点是 errors.Is，不是匹配“invalid cross-device link”这类字符串。字符串会随平台和语言环境变化，错误链才是 Go 代码可以依赖的接口。

为什么跨文件系统不能直接改名

同一文件系统内的 rename 可以只更新目录项，让文件内容留在原处，因此速度快，并且在 Unix 语义下通常具备较好的原子替换特性。跨文件系统时，源文件的 inode 或等价对象属于另一套命名空间，目标目录无法只靠一次目录项更新引用它，所以底层调用会拒绝这次操作。

这也解释了两个容易混淆的现象：

• 路径看起来都在同一台机器上，不代表它们属于同一个文件系统；挂载点、容器 bind mount、不同卷和某些网络文件系统都可能改变边界。
• 把 os.Rename 换成“重试几次”没有意义；文件系统关系没有变化时，重试只会重复得到同一类错误。

用目标目录内的临时文件完成复制后删除

如果业务允许“复制完成后再删除源文件”，临时文件必须创建在目标目录，而不是默认临时目录。这样最后一次 os.Rename(temp, dst) 仍然发生在同一个文件系统中，能够避免目标文件只写了一半就暴露出来。

package main

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

func copyThenRemove(src, dst string) (err error) {
    // 临时文件和最终文件同目录，确保收尾 Rename 不跨文件系统。
    dir := filepath.Dir(dst)
    tmp, err := os.CreateTemp(dir, ".move-*")
    if err != nil {
        return fmt.Errorf("创建目标临时文件: %w", err)
    }
    tmpName := tmp.Name()
    defer func() {
        // 任一步失败都清理残留临时文件，不删除源文件。
        _ = os.Remove(tmpName)
    }()

    in, err := os.Open(src)
    if err != nil {
        return fmt.Errorf("打开源文件: %w", err)
    }
    if _, err = io.Copy(tmp, in); err != nil {
        _ = in.Close()
        return fmt.Errorf("复制文件内容: %w", err)
    }
    if err = in.Close(); err != nil {
        return fmt.Errorf("关闭源文件: %w", err)
    }
    if err = tmp.Close(); err != nil {
        return fmt.Errorf("关闭目标临时文件: %w", err)
    }
    if err = os.Rename(tmpName, dst); err != nil {
        return fmt.Errorf("提交目标文件: %w", err)
    }
    // 只有目标文件已经在目标目录落地后，才删除源文件。
    if err = os.Remove(src); err != nil {
        return fmt.Errorf("删除源文件: %w", err)
    }
    return nil
}

示例展示的是普通文件迁移，不是通用目录搬运器。生产代码还要根据需求处理文件模式、所有者、扩展属性、符号链接、稀疏文件、校验和以及目标已存在时的覆盖策略。

上线前要把原子性和失败恢复写进方案

还要给复制阶段设置磁盘空间、权限和中断处理策略。进程在复制完成但删除源文件之前崩溃时，系统可能同时留下源文件和目标文件；这不是代码“重复移动”，而是复制后删除模型本身的可见结果，应该用任务状态或幂等键处理。

相关问题

为什么换成绝对路径仍然失败？绝对路径只消除了当前工作目录歧义，不会改变挂载点或文件系统归属。

能不能先判断两个路径是否同盘？可以通过 os.Stat 取得平台相关的文件信息，但判断结果仍可能受挂载、网络文件系统和并发变化影响；最稳妥的流程仍是处理 Rename 返回的真实错误。

复制后删除能叫“移动”吗？从用户业务动作看可以叫移动，但它不再具备一次 rename 的原子性，接口文档和失败补偿必须明确这一点。

参考资料：https://pkg.go.dev/os#Rename、https://go.dev/src/os/file.go、https://man7.org/linux/man-pages/man2/rename.2.html。