一个日志导入功能上线后,运营反馈三件事:中文全是「锟斤拷」;明明文件里有一千行,导进去只有九百九十九行;某些行末尾还带一个方框。开发把文件下载下来用编辑器打开,一切正常。于是判断是代码逻辑问题,改了两天,最后发现三件事分别是三个不同的原因:文件是 GBK 编码、最后一行没有换行符、Windows 的 CRLF 被原样保留。
文件读写看起来是最简单的一类代码,实际上坑特别密集。编码、换行符、BOM、缓冲区大小、路径分隔符、错误类型,每一个都可能让程序「读到了但读错」,而且大多数不会报错,只是数据悄悄变了。这篇按「打开、读取、解码、拼路径、判断错误」的顺序讲一遍,重点放在会出错的地方。
先搞清文件里到底是字节还是文字
Go 的文件 API 处理的是字节,不是文字。打开文件得到的 []byte 里没有「编码」这个概念,只有在把字节解释成字符串时,才需要知道它是什么编码。UTF-8、GBK、GB18030、Latin-1 都是字节到字符的映射规则,规则用错,就会看到乱码。
一个最小的验证办法是判断字节序列是不是合法的 UTF-8:
gbk := []byte{0xC4, 0xE3, 0xBF, 0x48}
fmt.Println("GBK 字节是否合法 UTF-8:", utf8.Valid(gbk))
fmt.Println("按 UTF-8 强转后:", string(gbk))
本机 go1.27.3 的实际输出:
GBK 字节是否合法 UTF-8: false
按 UTF-8 强转后: ��H
非法字节被替换成 U+FFFD 这个「替换字符」,显示出来就是菱形问号。注意这个替换是不可逆的:string(bytes) 一旦把非法序列换成替换字符,再转回字节也拿不到原数据了。所以「先读成 string 再想办法转码」是错误顺序,必须先按正确编码解码,或者保留原始字节。
标准库不内置 GBK 解码,需要额外的 golang.org/x/text/encoding/simplifiedchinese 包。这不是 Go 偷懒,而是把「非 Unicode 编码」放进了扩展库,避免标准库背上庞大的编码表。如果项目不能引入外部依赖,另一个办法是要求上游统一导出 UTF-8,从源头解决。
判断编码不能靠扩展名。.csv、.txt 只是命名习惯,内容可能是 GBK,也可能是带 BOM 的 UTF-8。可靠的线索只有字节本身:看开头有没有 BOM,看是否所有字节都能按 UTF-8 解码,看高位字节的分布是否符合双字节编码的特征。拿不准时,让上游明确给出编码,比在代码里猜要稳。
打开、读取,以及 Close 的错误
读文件有三条常见路径。os.ReadFile 一次把整个文件读进内存,返回 []byte,代码最短;os.Open 加 io.ReadAll 效果一样,但可以自己控制关闭时机;os.Open 加 bufio.Scanner 或 io.Copy 是流式处理,内存占用和文件大小无关。
raw, err := os.ReadFile("data.txt")
if err != nil {
return err
}
fmt.Println("字节数:", len(raw))
本机对一个内容为三行中文、使用 CRLF 的文件实测,字节数是 33,其中 CRLF 出现 3 次。这个数字说明两件事:len 算的是字节不是字符;文件里的 \r\n 原样存在,读取阶段不会自动转换。
选哪种方式,取决于文件大小和用途。配置文件、几 KB 的 JSON、一次性读取的小文本,ReadFile 最省事。日志、导出文件、几百 MB 的 CSV,必须流式读,否则光是那一块内存就可能触发 OOM,而且 GC 要花时间回收。判断标准不是「文件多大」,而是「峰值内存能不能接受」。
关闭文件通常写 defer f.Close()。读文件时忽略 Close 的错误一般没事,写文件时不行:Close 可能负责把缓冲区刷到磁盘,失败了你却以为写成功了。正确做法是显式关闭并检查,或者用命名返回值在 defer 里合并错误。
func writeAll(path string, data []byte) (err error) {
f, err := os.Create(path)
if err != nil {
return err
}
defer func() {
if cerr := f.Close(); cerr != nil && err == nil {
err = cerr
}
}()
_, err = f.Write(data)
return err
}
os.Create 会截断已有文件。只想在末尾追加,用 os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)。权限位在 Windows 上不完全生效,但跨平台代码仍应按 Unix 习惯写,部署到 Linux 时才不会突然不可读。
复制文件或把响应写进文件时,优先用 io.Copy。它会自己循环读写,内部用一块固定大小的缓冲区,直到源读完或出错,返回复制的字节数。比起手写 Read 加 Write,它少了两处容易写错的边界:读到 0 字节算结束,写了一半要接着写剩下的。需要控制缓冲区大小时,用 io.CopyBuffer 传入自己的切片。
Scanner 的 64KB 上限,以及出错后的第二次 Scan
bufio.Scanner 是按行读取最常用的工具:for scanner.Scan() { line := scanner.Text() },循环结束再看 scanner.Err()。它默认的单行上限是 64KB,超过就停止,并返回 bufio.Scanner: token too long。
big := filepath.Join(dir, "big.txt")
os.WriteFile(big, []byte(strings.Repeat("A", 70000)+"\n"), 0o644)
bsc := bufio.NewScanner(bf)
first := bsc.Scan()
fmt.Println("第一次 Scan:", first, "错误:", bsc.Err())
second := bsc.Scan()
fmt.Println("第二次 Scan:", second, "错误:", bsc.Err())
本机实际输出:
第一次 Scan: false 错误: bufio.Scanner: token too long
第二次 Scan: true 错误: bufio.Scanner: token too long
第二次拿到的长度: 65536
第一次返回 false,错误是 token too long,符合预期。第二次却返回 true,拿到了 65536 字节的截断数据,而错误仍然是 token too long。原因是出错之后缓冲区里还留着已读到的半行,再次调用时扫描器把它当成文件末尾的最后一行交了出来。这个行为意味着:for scanner.Scan() 循环退出后,如果你只检查 Err(),能发现错误;但如果你在循环里对每次 Scan() 的返回值不敏感,可能会把截断数据当成完整一行处理。
处理办法有两种。知道单行可能很长时,用 scanner.Buffer(make([]byte, 0, 1<<20), 1<<20) 把上限提高到 1MB;更稳妥的是改用 bufio.Reader 的 ReadString('\n'),它没有固定上限,会按需增长,但要自己处理 io.EOF 和最后一行没有换行的情况。
io.ReadFull 或按固定块读,超大行用 Reader 加长度保护,别让一行数据把内存吃光。如果只需要逐行处理、又不想被 64KB 限制,bufio.Reader 是更通用的选择。ReadString('\n') 返回包含分隔符的字符串,ReadLine 返回不含分隔符的字节切片,ReadBytes 按字节返回。它们都可能在最后一次同时返回数据和 io.EOF,所以错误判断的顺序必须和数据判断绑在一起,不能看到错误就丢数据。
BOM、CRLF 和最后一行
Windows 记事本保存的 UTF-8 文件,开头常常带三个字节 EF BB BF,叫 BOM(字节序标记)。它不是一个可见字符,但按 UTF-8 解码后会在字符串开头留下一个 U+FEFF。本机实测:
BOM 文件前 6 字节: ef bb bf e4 bd a0
BOM 文件首字符: "\ufeff", 长度 1
后果是:按行读取时第一行的第一个字段前面多了这个字符,用 == 比较字段名会失败,用 strconv.Atoi 解析数字会报错,而且肉眼几乎看不出来。处理方式是在读取后去掉它:strings.TrimPrefix(s, "\ufeff")。但更根本的做法是要求文件不带 BOM,或者在解码层统一剥掉,别让每个字段解析函数都各自处理。
CRLF 是 Windows 的换行习惯。Scanner 的 ScanLines 会自动去掉行尾的 \r,所以用 Scanner 读出来是干净的;但如果用 ReadString('\n') 或自己按字节切分,行尾就会保留 \r。本机用 Scanner 读一个 CRLF 文件,三行输出都是 "第一行"、"第二行"、"第三行",没有多余字符,说明 \r 被去掉了。
最后一行没有换行符是另一个经典问题。Scanner 在文件结束时会把剩余内容作为最后一行返回,所以它不会丢;但自己写 ReadString 循环时,最后一次可能返回数据和 io.EOF 同时出现,只判断 err != nil 就 break,数据就丢了。正确写法是先处理返回的数据,再判断错误。
如果文件是 CSV,BOM 往往出现在表头第一列。此时不是「少一个字段」,而是第一列的名字前面多了不可见字符,按列名查找会失败。排查时把表头每个字段用 %q 打印出来,BOM 会显示成 "\ufeff" 开头,比肉眼盯屏幕可靠。
for {
line, err := reader.ReadString('\n')
if len(line) > 0 {
process(strings.TrimRight(line, "\r\n"))
}
if err != nil {
if err != io.EOF {
return err
}
break
}
}
这段代码同时处理了 CRLF 和「最后一行没有换行」两种情况。注意 TrimRight 会去掉所有结尾的 \r 和 \n,如果数据本身允许以这两个字符结尾,要改用 TrimSuffix 精确去掉一个。
路径:Join 只负责拼接和清理
filepath 处理的是本地文件系统路径,path 处理的是斜杠分隔的通用路径(比如 URL)。在 Windows 上,filepath.Join 用反斜杠拼接,并会清理多余的 . 和 ..。本机实测:
p := filepath.Join("data", "..", "..", "etc", "passwd")
fmt.Println("Join 后:", p)
fmt.Println("Base:", filepath.Base("/a/b/c.txt"), " Ext:", filepath.Ext("archive.tar.gz"))
Join 后: ..\etc\passwd
Base: c.txt Ext: .gz
Join 把 data/../../etc/passwd 清理成了 ..\etc\passwd,它做的是规范化,不是安全校验。如果这个路径来自用户输入,清理之后仍然可能指向上级目录,这就是路径穿越。正确的防御是:把相对路径转成绝对路径,再确认它落在允许的根目录之内,而不是简单地检查字符串里有没有 ..(各种编码、符号链接都能绕过)。
另外几个常用函数:Base 取最后一段,Dir 取目录,Ext 取扩展名(archive.tar.gz 得到 .gz,不是 .tar.gz),Clean 只做规范化,Abs 转绝对路径,Rel 求相对路径。跨平台拼路径一律用 filepath.Join,不要用字符串加 "/",否则在 Windows 上会混出两种分隔符。
遍历目录用 filepath.WalkDir,它比旧的 Walk 更省内存,回调里拿到的是 DirEntry,需要文件信息时再调用 Info()。遍历时如果遇到不需要进入的目录,返回 filepath.SkipDir 可以剪枝。注意遍历顺序也不保证稳定,需要排序时自己收集后排序。
大小写在 Windows 上不敏感,在 Linux 上敏感。代码里不要把路径转成小写来做比较,也不要用字符串截取判断「是不是同一个目录」。判断两个路径是否指向同一位置,应该先 filepath.Abs 再 filepath.Clean,必要时用 EvalSymlinks 解析符号链接;后者会真正访问文件系统,路径不存在时返回错误,不能无脑调用。
写配置文件这类「要么完整、要么保持原样」的场景,不要直接覆盖目标文件。先写到同目录下的临时文件,写完并 Close 成功,再用 os.Rename 替换目标。同一分区内的重命名是原子的,读者不会看到写了一半的文件。临时文件要放在目标目录里,放到系统临时目录再重命名,跨分区时可能退化成复制加删除,失去原子性。
错误:用 errors.Is 判断,不要比字符串
文件操作失败时,返回的通常是 *fs.PathError,里面包含操作名、路径和底层错误。本机打开一个不存在的文件,实际输出是:
err: open 不存在的文件.txt: The system cannot find the file specified.
errors.Is(err, fs.ErrNotExist): true
errors.As(err, &pe): true
Op: open Path: 不存在的文件.txt
错误文本在不同操作系统、不同语言环境下不一样,所以绝对不能拿字符串包含「not exist」来判断。标准做法是 errors.Is(err, fs.ErrNotExist) 判断类别,errors.As 取出 *fs.PathError 拿到具体路径。权限不足用 fs.ErrPermission,文件已存在用 fs.ErrExist。
注意 os.IsNotExist 这类旧函数仍然可用,但它只看最外层的错误,遇到包装过的错误会判断失败。新代码统一用 errors.Is,旧代码迁移时顺手改掉。
写文件时还要区分「目录不存在」和「没有权限」。前者通常应该自动创建目录,后者应该直接报错给用户。用 errors.Is 分开处理,比统一返回「保存失败」有用得多。
往上传递时,用 fmt.Errorf("读取 %s: %w", path, err) 把路径带上,同时保留原始错误链。不要只写 fmt.Errorf("读取失败"),那会把「哪个文件、什么原因」全丢掉;也不要只返回原始错误,上层不知道是哪个文件出的问题。
出问题时先看哪里
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 中文全是乱码或问号 | 文件不是 UTF-8,却按 UTF-8 解码 | 取前几个字节看编码特征;用 utf8.Valid 判断;确认上游导出编码 |
| 第一行开头多一个看不见的字符 | UTF-8 BOM 被当成正文 | 看文件前 3 字节是否 EF BB BF;读取后 TrimPrefix |
每行末尾多一个方框或 \r | CRLF 没有被去掉 | 确认用的是 Scanner 还是 ReadString;后者要手动 Trim |
| 最后一行数据丢失 | 文件末尾没有换行,代码见 EOF 就丢弃了返回数据 | 检查 ReadString 循环是否先处理数据再判断错误 |
| 读取到一半停止,报 token too long | 单行超过 Scanner 默认 64KB 上限 | 调大 Scanner.Buffer,或改用 bufio.Reader |
| 文件句柄越来越多,最后打不开新文件 | 循环里 defer Close,全部堆到函数返回 | 把循环体拆成函数,或显式关闭 |
| 写文件返回成功,内容却是空的 | Close 或 Flush 失败,返回值被忽略 | 显式检查 Close;必要时调用 Sync |
| 路径拼接后访问到了别的目录 | Join 只清理不校验,输入里带 .. | 转绝对路径并校验是否在允许目录内,不要只查字符串 |
| Windows 上删除或重命名失败 | 文件句柄仍被当前进程或其他进程占用 | 确认所有 Open 都已 Close;用工具查占用进程 |
排查文件问题有个通用方法:先用十六进制看前几十个字节,确认 BOM、换行和编码;再用最小代码只读一行,打印字节和字符串两种形式;最后才去看业务逻辑。绝大多数「读错」在第一步就能定性。
边界与代价
- ReadFile 简单但有内存上限:它把整个文件放进内存,还要再复制一份给字符串或解码器。文件大小乘以并发数,很容易超过容器内存限制。
- Scanner 方便但不万能:默认 64KB 上限、只适合文本、出错后的行为容易误判。大文件、长行、二进制都要换工具。
- 编码转换要引入依赖:标准库只保证 UTF-8,GBK、Shift-JIS 需要扩展包。引入依赖意味着构建体积和供应链风险,能用 UTF-8 统一就别增加这一层。
- 路径是字符串,不是安全边界:
filepath.Join、Clean都不会阻止路径穿越。真正的边界是「解析后的绝对路径位于允许根目录内」。 - 文件系统行为因平台而异:Windows 的路径大小写不敏感、文件占用会导致删除失败、权限位语义不同。跨平台代码要在目标系统上跑过,不能只在开发机上验证。
- fs 抽象适合测试:
io/fs和testing/fstest.MapFS可以在内存里模拟文件系统,避免单测依赖真实磁盘。生产代码接收fs.FS而不是硬编码路径,会更容易测试。 - 原子替换有前提:临时文件和目标文件必须在同一分区,重命名才是原子的;Windows 上目标文件被占用时,重命名会失败,需要重试或先关闭占用它的句柄。
文件 I/O 的性能往往不在「读得多快」,而在「读了多少次」。小文件逐行打开、每次读一个字节、频繁 Seek,都会让系统调用成为瓶颈。用缓冲、批量读、必要时用 io.Copy 让内核直接搬运,通常比调大单次读取更有效。想理解背后的系统调用和页缓存,可以看 操作系统:文件系统 那一篇。
当天能自己验证的练习
- 用 PowerShell 的
[IO.File]::WriteAllBytes写一个带 BOM 的 UTF-8 文件,用 Go 读取并打印前三个字节和首字符,确认看到\ufeff;再用TrimPrefix去掉。 - 写一个 CRLF 换行的文件,分别用 Scanner 和
ReadString('\n')读取,打印每行的%q,对比\r是否保留。 - 生成一个 70000 字节的单行文件,用默认 Scanner 读,打印
Scan返回值和Err();再调用一次Scan,观察截断数据。 - 用
os.Open打开不存在的文件,打印err、errors.Is(err, fs.ErrNotExist)和errors.As取出的PathError字段。 - 用
filepath.Join拼接一段带..的路径,打印结果;再用filepath.Abs转绝对路径,确认它是否仍在预期目录下。
小结
三句话收一下:文件 API 读的是字节,编码错了要在解码层解决,不能先转成字符串再补救;读大文件用流式,Scanner 有 64KB 单行上限且出错后的行为需要留意,最后一行没有换行时不要丢掉数据;路径拼接不等于安全校验,判断文件错误用 errors.Is 和 errors.As,不要比较错误文本。
下一篇进入网络。文件是本地资源,网络是「可能永远等不到结果的资源」:连接可能建不上、对方可能不响应、响应体可能忘了关。今天学的 io.Copy 和 Close 会直接用在 HTTP 响应上,而 net/http 的默认超时是「不超时」,这一点会让不少服务在故障时挂住。