Golang二进制写入详解：io.Write使用教程

本文深入解析了 Go 语言中安全、可靠写入二进制文件的三大核心方法：binary.Write（适用于固定结构体序列化，强调字段导出、字节序显式指定及类型限制）、io.Write（底层可控，必须严格检查返回值以应对部分写入）、以及手动编码变长数据（如带长度前缀的字符串），并直击实践中高频踩坑点——字节序不一致、非导出字段静默忽略、Write 未校验导致数据截断等，助你写出跨平台兼容、与 C/C++ 系统无缝对接的健壮二进制 I/O 代码。

Go 语言写入二进制文件，核心是避免用 fmt.Fprintf 或 strconv 转字符串，必须用 binary.Write、io.Write 原始字节流，或直接操作 []byte。

用 binary.Write 写结构体到二进制文件

适合固定格式的序列化（如网络协议头、自定义二进制格式），要求字段对齐、字节序明确。它不处理嵌套切片/指针，只支持基础类型和数组/结构体。

• 必须传入 io.Writer（如 *os.File），不能传字符串或缓冲区
• 字节序需显式指定：binary.LittleEndian 或 binary.BigEndian
• 结构体字段必须是可导出的（首字母大写），否则 binary.Write 会忽略
• 不支持 map、slice（除非长度固定且已知，用数组代替）

package main

import (
    "encoding/binary"
    "os"
)

type Header struct {
    Magic  uint32
    Length uint16
    Flags  byte
}

func main() {
    f, _ := os.Create("header.bin")
    defer f.Close()

    hdr := Header{Magic: 0x474f4c41, Length: 1024, Flags: 0x01}
    binary.Write(f, binary.LittleEndian, hdr) // 写入 7 字节：4+2+1
}

用 io.Write 直接写 []byte

最底层、最可控的方式，适用于已知原始字节序列的场景（如拼接协议帧、写图片头、加密后数据）。

• Write 返回实际写入字节数和可能的错误，必须检查是否写满（尤其在循环中）
• 不要假设 Write 一次写完全部数据；小文件通常没问题，但管道、网络或满磁盘时可能部分写入
• 若需多次写入，推荐用 bufio.Writer 减少系统调用，但要注意 Flush() 否则数据滞留

package main

import (
    "os"
)

func main() {
    f, _ := os.Create("raw.bin")
    defer f.Close()

    data := []byte{0x00, 0x01, 0x02, 0xff, 0xaa}
    n, err := f.Write(data)
    if err != nil || n != len(data) {
        panic("write failed or partial")
    }
}

写入非对齐或变长二进制数据（如字符串 + 长度前缀）

当需要混合类型或动态长度时，binary.Write 不够用，得手动编码字节布局。

• 字符串不能直接写——要先写长度（uint32），再写字节内容，否则读取端无法知道边界
• 注意大小端一致性：写用 LittleEndian，读也必须用同一个
• 用 append 拼接字节切片比多次 Write 更高效，也更容易控制顺序

package main

import (
    "encoding/binary"
    "os"
)

func writeStringWithLen(w *os.File, s string) {
    b := []byte(s)
    header := make([]byte, 4)
    binary.LittleEndian.PutUint32(header, uint32(len(b)))

    w.Write(header)
    w.Write(b)
}

func main() {
    f, _ := os.Create("str.bin")
    defer f.Close()

    writeStringWithLen(f, "hello世界")
}

二进制写入真正容易出错的地方，不是语法，而是字节序误配、结构体字段未导出、或对 Write 返回值视而不见——尤其在跨平台或对接 C/C++ 程序时，一个字节错位，整段数据就不可读。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~