Go io/fs区分文件不存在与读取失败的排查指南

用 Go 的 io/fs 读取文件时，不能只比较 err.Error() 是否包含“no such file or directory”。稳定的判断方式是先用 errors.Is(err, fs.ErrNotExist) 识别“目标不存在”，再用 errors.Is 判断权限或路径错误；需要记录操作名和路径时，再用 errors.As 取出 *fs.PathError。这样，缺失文件可以按业务兜底，权限、非法路径和其他 I/O 失败仍会被如实暴露。

Go io/fs 的错误分类先看匹配关系

io/fs 约定文件系统错误可以通过 errors.Is 与 fs.ErrNotExist、fs.ErrPermission、fs.ErrInvalid 等哨兵错误比较。底层通常会返回 *fs.PathError，它携带 Op、Path 和底层 Err；因此不要用字符串前缀代替错误匹配。

package main

import (
	"errors"
	"fmt"
	"io/fs"
)

func classify(err error) string {
	// 先匹配稳定的哨兵错误，避免依赖不同文件系统的字符串格式。
	switch {
	case err == nil:
		return "成功"
	case errors.Is(err, fs.ErrNotExist):
		return "文件不存在，可按业务兜底"
	case errors.Is(err, fs.ErrPermission):
		return "权限不足，应保留错误并检查运行身份"
	case errors.Is(err, fs.ErrInvalid):
		return "路径或参数非法，应修正调用方"
	default:
		var pathErr *fs.PathError
		// As 用于取出操作名和路径；取不到时仍返回原始错误类别。
		if errors.As(err, &pathErr) {
			return fmt.Sprintf("其他文件系统错误：%s %s", pathErr.Op, pathErr.Path)
		}
		return "其他读取失败"
	}
}

这里的关键顺序是“先判定错误语义，再提取上下文”。errors.Is 会沿着错误的 Unwrap 链查找，所以即使 PathError 外面又包了一层业务错误，也不会误把缺失文件归为普通失败。

ReadFile 读取失败的判断顺序

fs.ReadFile(fsys, name) 负责读取完整文件。只要读取成功，返回的错误就是 nil；文件内容为空并不等于文件不存在。对配置覆盖、模板加载这类“文件可选”的场景，可以只对 fs.ErrNotExist 做默认值处理，其余错误直接返回。

func loadConfig(fsys fs.FS, name string) ([]byte, error) {
	data, err := fs.ReadFile(fsys, name)
	if err == nil {
		// 空文件也是合法结果，是否允许由上层格式校验决定。
		return data, nil
	}
	if errors.Is(err, fs.ErrNotExist) {
		// 缺失是可选配置的业务分支，不掩盖权限和 I/O 错误。
		return []byte("{}"), nil
	}
	// 保留 PathError 链，调用方还能通过 errors.As 取得具体路径。
	return nil, fmt.Errorf("读取配置 %q 失败: %w", name, err)
}

常见误区有两个：第一，先调用 fs.ValidPath 检查输入，避免把 "/etc/app.conf"、"a/../b" 之类主机路径写法传给 fs.FS；第二，不要为了“兼容”而对所有错误返回默认配置，否则权限变更、挂载失效和介质读取错误都会被静默吞掉。

WalkDir 回调中的 err 要结合 d 判断

fs.WalkDir 会把访问过程中的错误交给回调。根目录初始 Stat 失败时，回调里的 d 为 nil；某个目录的 ReadDir 失败时，d 仍描述该目录，回调会收到非空 err。两种情况都不能简单地用“遇到错误就跳过”处理，否则根目录拼错也可能被伪装成空目录。

func scan(fsys fs.FS, root string) error {
	return fs.WalkDir(fsys, root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			// d 为 nil 多见于根目录 Stat 失败，默认让错误返回给上层。
			if d == nil {
				return fmt.Errorf("访问根路径 %q 失败: %w", path, err)
			}
			if errors.Is(err, fs.ErrPermission) {
				// 子目录无权限时跳过该目录，但继续扫描其他兄弟目录。
				return fs.SkipDir
			}
			return err
		}
		if d.IsDir() {
			return nil
		}
		return handleFile(path)
	})
}

若业务允许某个子目录暂时不可读，可以按目录范围返回 fs.SkipDir；若要停止整个遍历，则返回 fs.SkipAll。这两个值是给回调的控制信号，不是用来判断“文件不存在”的错误。根目录是否可选，也应在 d == nil 的分支中明确决定。

路径合法性与自定义 FS 的排查清单

如果自己实现 fs.FS，Open 出错时应返回带有 Op="open"、Path=name 的 *fs.PathError，底层原因放在 Err 中。这样上层才能用统一的 errors.Is 和 errors.As 排查。最后用 testing/fstest.TestFS 检查实现是否满足文件系统接口约定，能比人工比对错误字符串更早发现兼容问题。

相关问题

空文件应该算文件不存在吗？

不应该。空文件读取成功时 err == nil，应把“内容是否满足格式”交给后续解析或业务校验。

为什么不用 strings.Contains 判断错误文本？

不同文件系统和包装层的文本可能不同；errors.Is 依赖错误语义，errors.As 负责提取结构化上下文。

WalkDir 遇到权限错误一定要终止吗？

不一定。若扫描允许部分结果，可对具体子目录返回 fs.SkipDir；根目录失败通常应直接返回，避免把扫描失败误报为成功。