Go 文件跨盘迁移采用临时文件加校验的实现方案

跨盘迁移文件时，不要直接把 os.Rename(src, dst) 当成万能移动操作。源文件和目标文件位于不同文件系统时，Rename 可能失败；更稳妥的做法是在目标目录创建临时文件，复制并校验内容，关闭文件后再把临时文件改名为目标路径。只有最后一步成功，才删除源文件。

核心顺序是：目标目录临时文件 → 复制并计算摘要 → 重新读取临时文件校验 → 同步并关闭 → Rename 替换目标 → 成功后删除源文件。

下面的示例只演示文件级迁移，不处理目录树、权限继承或源文件在迁移期间被其他进程修改的情况。事实依据来自 Go 标准库的 os、io、crypto/sha256 和 path/filepath 文档。

先把跨盘限制放在设计前面

os.Rename 更适合在同一文件系统内完成路径切换。跨盘时，真正需要搬运数据的是复制过程；而最终的 Rename 应发生在目标目录内部，让临时文件和正式目标共享同一个文件系统。这样即使复制中途失败，旧目标文件也不会被半成品覆盖。

临时文件名要由 os.CreateTemp(filepath.Dir(dst), ".migrate-*") 生成，而不是放在系统临时目录。若临时文件在另一个挂载点，最后一步又会回到跨盘 Rename，设计就失去意义。

复制阶段同时保留摘要

复制时可以让一个读取器同时写入临时文件和 SHA-256 哈希。这里的摘要代表本次从源文件读到的字节；复制结束后，还要重新打开临时文件再算一次摘要，避免把“写入调用返回成功”误当成“目标内容已确认一致”。

package migrate

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

// MoveAcrossFilesystems 先在目标目录生成临时文件，校验后再替换目标。
func MoveAcrossFilesystems(src, dst string) error {
    in, err := os.Open(src)
    if err != nil {
        return fmt.Errorf("打开源文件: %w", err)
    }
    defer in.Close() // 源文件只负责读取，函数退出时释放句柄。

    tmp, err := os.CreateTemp(filepath.Dir(dst), ".migrate-*")
    if err != nil {
        return fmt.Errorf("创建目标临时文件: %w", err)
    }
    tmpName := tmp.Name()
    keepTemp := true
    defer func() {
        if keepTemp {
            _ = os.Remove(tmpName) // 任何失败都清理半成品。
        }
    }()

    sourceHash := sha256.New()
    if _, err := io.Copy(tmp, io.TeeReader(in, sourceHash)); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("复制文件内容: %w", err)
    }
    if err := tmp.Sync(); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("同步临时文件: %w", err)
    }
    if err := tmp.Close(); err != nil {
        return fmt.Errorf("关闭临时文件: %w", err)
    }

    targetHash, err := fileSHA256(tmpName)
    if err != nil {
        return fmt.Errorf("读取临时文件校验: %w", err)
    }
    if fmt.Sprintf("%x", sourceHash.Sum(nil)) != fmt.Sprintf("%x", targetHash) {
        return fmt.Errorf("源文件与临时文件摘要不一致")
    }
    if err := os.Rename(tmpName, dst); err != nil {
        return fmt.Errorf("替换目标文件: %w", err)
    }
    keepTemp = false
    return os.Remove(src) // 只有目标替换成功后才执行删除源文件。
}

func fileSHA256(name string) ([]byte, error) {
    f, err := os.Open(name)
    if err != nil {
        return nil, err
    }
    defer f.Close() // 校验读取完成后释放第二个文件句柄。
    h := sha256.New()
    if _, err := io.Copy(h, f); err != nil {
        return nil, err
    }
    return h.Sum(nil), nil
}

代码把临时文件放在目标目录，并用 keepTemp 兜住所有早退路径。tmp.Sync 只表示把文件数据交给操作系统的同步语义；如果业务还要求目录项在断电后的持久性，需要再结合目标系统的目录同步策略，不能把它泛化成跨平台保证。

校验通过后再切换目标路径

摘要相等后，临时文件才具备成为正式目标的资格。os.Rename 这一步应尽量短，不要在它之前删除旧目标，也不要在复制期间直接写入 dst。在 Unix 文件系统上，同一文件系统内的改名通常具有原子切换特征；Windows、权限、目标文件占用和网络文件系统则可能有不同限制，生产代码应把 Rename 错误作为可恢复失败处理。

示例末尾的 os.Remove(src) 是“移动”语义，而不是“复制”语义。如果源文件可能在复制期间被修改，摘要只证明本次读取与临时文件一致，不代表它是某个业务版本的快照；这时应先冻结写入、使用版本化源文件，或把变更检测纳入协议。

发布前的边界清单

最常见的错误有三个：临时文件建在系统临时目录、只检查 io.Copy 的返回值就替换目标、以及先删源文件再尝试 Rename。把这三点拆成独立检查，跨盘迁移就不会退化成“复制一半也算完成”。

几个容易混淆的问题

为什么不直接先删除目标文件？

删除会制造目标不存在的窗口，复制失败时还会丢掉原目标。让 Rename 负责最后切换，失败时至少还能保留旧目标或源文件。

摘要校验能保证源文件没有并发变化吗？

不能。它只保证本次读取到的字节与临时文件相同；要保证业务版本一致，仍需外部写入协调或版本快照。

复制成功后一定要删除源文件吗？

不一定。复制任务保留源文件，移动任务才在目标替换成功后删除，并应记录删除失败，避免把“已复制”误报成“已移动”。