Go io.OffsetWriter Seek 后为什么写到了错误的文件位置

我第一次把 io.OffsetWriter 用在分段写文件时，也被 Seek 返回的数字迷惑过：明明调用了 Seek(8, io.SeekStart)，后面的数据却出现在文件的 108 字节附近。其实这不是写错位置，而是把逻辑偏移和底层文件偏移看成了同一个坐标。

结论很简单：io.NewOffsetWriter(w, base) 会把写入位置建立在 base 之上。Seek 返回的是相对于这段区域起点的逻辑位置；真正交给底层 WriterAt 的位置还要再加上 base。Write 会推进游标，WriteAt 只使用显式逻辑偏移，不会移动游标。

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

先把两套坐标分开

假设文件前 100 字节是公共头部，现在要把一个分片写到从 100 开始的区域，可以这样创建包装器：

package main

import (
	"io"
	"os"
)

func openSegment(path string) (*os.File, *io.OffsetWriter, error) {
	// 底层文件需要实现 io.WriterAt，OffsetWriter 才能按绝对位置写入。
	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o644)
	if err != nil {
		return nil, nil, err
	}
	// 逻辑区域从文件的第 100 字节开始，调用方只处理这段区域内的偏移。
	return f, io.NewOffsetWriter(f, 100), nil
}

这里有三个值需要同时记住：

• base=100：这段区域在底层文件中的起点。
• off：OffsetWriter 内部记录的底层当前位置，初始也是 100。
• 对外返回的逻辑位置：初始为 0，代表“当前分片的开头”。

Seek 返回 8，为什么底层却写到 108

当 base=100 时，下面的调用把逻辑游标放到分片内的第 8 个字节：

// segment 代表从文件偏移 100 开始的逻辑分片。
segment := io.NewOffsetWriter(file, 100)

// 返回值是分片内的逻辑偏移，不是文件绝对偏移。
logical, err := segment.Seek(8, io.SeekStart)
if err != nil {
	return err
}

// Write 使用 base + logical，也就是底层文件偏移 108。
if _, err := segment.Write([]byte("payload")); err != nil {
	return err
}

_ = logical // logical 为 8；真正的文件位置是 100 + 8。

SeekStart 会按照这段区域的起点计算，内部游标变成 base+8，但返回值会减去 base，所以调用方看到的是 8。后续 Write 从内部游标写入，并在成功写入后按实际字节数推进游标。

排查“写到了错误位置”时，先在日志里同时记录 base、逻辑偏移、写入长度和预期底层偏移。只记录 Seek 的返回值，很容易把 8 误当成文件绝对位置。

区分 Write、WriteAt 与 Seek

这三个方法都能影响分段写入，但坐标和游标规则不同。记住“Write 走游标，WriteAt 走显式位置，Seek 只改游标”基本就不会混淆。

// 先把游标放到分片内偏移 8，再连续写入两段数据。
if _, err := segment.Seek(8, io.SeekStart); err != nil {
	return err
}
if _, err := segment.Write([]byte("header")); err != nil {
	return err
}

// WriteAt 的 40 是分片内偏移，实际落点是 base + 40；游标保持在前一段之后。
if _, err := segment.WriteAt([]byte("index"), 40); err != nil {
	return err
}

如果代码一部分使用 Write，另一部分又使用 WriteAt，建议在接口层明确“所有显式偏移都是分片内坐标”。不要把从 os.File 日志里看到的绝对位置直接传给 WriteAt，否则会再次叠加 base。

几个容易误判的边界

SeekEnd 不是文件末尾快捷方式

当前 io.OffsetWriter.Seek 的实现只处理 io.SeekStart 和 io.SeekCurrent；传入 io.SeekEnd 会返回 whence 错误。它不像某些文件对象那样自动知道底层文件末尾，也不会替你把“分片末尾”换算出来。

如果业务确实知道分片长度，应自行计算目标逻辑偏移，再使用 SeekStart。不要把“底层文件已经有多大”与“当前分片允许写到哪里”混为一谈。

负偏移会被拒绝

无论是 Seek 后落到基准位置之前，还是给 WriteAt 传入负的逻辑偏移，都会返回错误。分片写入器不会因为偏移越界而自动扩展前缀，也不会把负数解释成从末尾倒数。

它不是并发协调器

Go 的 io 文档提醒，除非具体实现另有说明，I/O 原语不应默认认为可以并行安全使用。多个 goroutine 共享同一个 OffsetWriter 时，至少会争用同一个逻辑游标；即使改用 WriteAt，底层数据区域重叠也仍然需要业务层协调。

分段写入时怎样建立稳定约定

1. 创建包装器时记录 base 和分片长度，调用方只传分片内偏移。
2. 连续写入统一使用 Write，需要跳写或回填时统一使用 WriteAt。
3. 每次 Seek 都检查返回的逻辑位置和错误，不把返回值当成文件绝对位置。
4. 不要依赖 SeekEnd 推导分片末尾，把分片长度作为显式业务数据。
5. 并发场景为游标操作加锁，或为每个分片创建独立的 OffsetWriter，并保证区域不重叠。

我现在排查这类问题时，会先画出一行“分片逻辑坐标”和一行“文件绝对坐标”，然后把每个 Seek、Write、WriteAt 标到两条线上。只要发现某个调用把绝对偏移传进了 WriteAt，或者把 Seek 返回值直接当成文件位置，根因通常就找到了。

相关问题

• OffsetWriter 的 WriteAt 会改变游标吗？不会，它使用显式逻辑偏移写入，当前逻辑游标保持不变。
• 为什么 Seek(0, io.SeekStart) 不一定写文件开头？因为 0 是分片内起点，底层位置仍是创建 OffsetWriter 时传入的 base。
• 想写文件绝对位置怎么办？直接对实现了 WriterAt 的底层对象使用绝对偏移，或先把绝对位置减去 base 再传给 OffsetWriter。
• 多个 goroutine 可以共享一个 OffsetWriter 吗？不要默认可以；共享游标时应加锁，独立分片也要避免底层写入区域重叠。