Go io.NewOffsetWriter 的 SeekEnd 为什么不能使用

如果你把 io.NewOffsetWriter 当成“带起点的普通文件写入器”，很容易在定位文件尾部时写出 Seek(0, io.SeekEnd)。这个调用返回错误不是文件损坏，而是 OffsetWriter 的接口边界：它的 Seek 只处理 io.SeekStart 和 io.SeekCurrent，默认分支会返回非法 whence 错误。

官方地址：https://pkg.go.dev/io#OffsetWriter

影响面：SeekEnd 失败，但普通 Write 仍然可以工作

这个问题通常出现在分段文件、日志追加或预留头部的写入代码里。NewOffsetWriter(w, off) 接收的是 io.WriterAt，它把包装器的逻辑偏移映射到下层写入器；它不是把下层对象完整包装成一个支持所有 io.Seeker 语义的文件对象。

package main

import (
    "io"
    "os"
)

func wrongEndSeek(path string) error {
    // 以可读写方式打开文件；示例只展示定位边界，不负责创建父目录。
    file, err := os.OpenFile(path, os.O_RDWR, 0)
    if err != nil {
        return err
    }
    defer file.Close() // 退出函数时释放文件描述符。

    writer := io.NewOffsetWriter(file, 128)
    // SeekEnd 不是 OffsetWriter.Seek 支持的 whence，会返回错误。
    _, err = writer.Seek(0, io.SeekEnd)
    return err
}

这里的关键不是 os.File 本身是否支持 SeekEnd，而是调用已经落在了 *io.OffsetWriter 上。底层文件支持的能力不会自动扩展包装器的 Seek 分支。

时间线：一次 Seek 调用到底经过了哪些坐标

假设创建包装器时传入基准偏移 base=128。此时它内部的当前偏移也从 128 开始，但对外暴露的是相对坐标 0。调用 Seek(4, io.SeekStart) 后，对外位置是 4，底层位置是 132；调用 Seek(3, io.SeekCurrent) 后，对外位置变为 7，底层位置是 135。

触发条件：把文件末尾定位误写成包装器的 SeekEnd

OffsetWriter.Seek 的语义只有两个有效方向：从包装器基准起点算，或者从当前逻辑位置算。源码中的默认分支直接返回 whence 错误，因此 SeekEnd 没有“先到文件末尾再加基准”的隐含行为。

另外，WriteAt(p, off) 的 off 也是包装器相对偏移。比如基准是 128，调用 WriteAt(data, 12)，底层写入位置是 140；它不会改变包装器下次 Write 使用的当前偏移。这是顺序写和定点写并存时最容易混淆的地方。

根因修复：先取文件长度，再显式设置基准

需要从当前文件尾部继续写时，把“求末尾”和“偏移写入”拆开：对底层文件调用 Stat 读取长度，再用这个长度创建偏移包装器。这样没有依赖 OffsetWriter 不支持的 SeekEnd，也把定位依据留在了真正拥有文件元数据的对象上。

package main

import (
    "io"
    "os"
)

func appendWithOffsetWriter(path string, payload []byte) error {
    // 追加写需要读写权限；文件必须先存在，创建策略按业务决定。
    file, err := os.OpenFile(path, os.O_RDWR, 0)
    if err != nil {
        return err
    }
    defer file.Close() // 无论后续 Stat 或 Write 是否失败都关闭文件。

    info, err := file.Stat()
    if err != nil {
        return err
    }

    // 把文件当前长度作为基准，包装器内部的逻辑位置从 0 开始。
    writer := io.NewOffsetWriter(file, info.Size())
    if _, err := writer.Write(payload); err != nil {
        return err
    }
    return nil
}

如果业务需要的是固定区间而不是追加，直接传入区间起点即可，再用 SeekStart 或相对的 WriteAt 控制位置。若写入目标实现了 io.WriterAt 但不代表它能提供文件长度，长度仍需由业务元数据或底层对象另行给出。

防复发清单：把三种偏移语义分开

• 需要“文件末尾”时，先从底层文件或业务元数据取得绝对长度，不调用包装器的 SeekEnd。
• 需要顺序追加时使用 Write；它会推进包装器自己的当前偏移。
• 需要随机覆盖时使用 WriteAt，记住传入的是相对基准的偏移，不会推进 Write 的游标。
• 每次检查 Stat、Seek、Write 和 Close 的错误；静态配图只用于解释坐标关系，不替代这些错误处理。

常见问题

为什么底层 os.File 支持 SeekEnd，OffsetWriter 却不支持？

因为调用对象已经是 OffsetWriter。它只实现了自己定义的相对寻址规则，没有把底层文件的所有 Seek 模式透传出来。

用 SeekCurrent 能不能模拟 SeekEnd？

只有在你已经可靠知道当前逻辑位置与文件长度的关系时才可以。通用追加场景更清楚的做法是先 Stat，再以文件长度创建新的 OffsetWriter。

WriteAt 写完后，下一次 Write 会从哪里继续？

下一次 Write 仍从 OffsetWriter 自己的当前偏移继续；WriteAt 的相对定位不会自动推进这个顺序写位置。