Go fs.Sub 出错时怎么排查子路径

Go 里调用 fs.Sub(fsys, dir) 出错，第一步不是盲目改成绝对路径，而是看错误发生在哪一层：dir 不符合 io/fs 的路径规则时，fs.Sub 会立刻返回 ErrInvalid；目录不存在或实际不是目录时，默认实现通常要等到后续 Stat、ReadDir 或 Open 才暴露问题。把这两类情况分开，排查会快很多。

先把 fs.Sub 的报错分成入口和读取两类

fs.Sub 的参数 dir 遵循 io/fs 的统一路径语法，不是当前操作系统的文件路径语法。空字符串、..、以 / 开头、以 / 结尾、包含 // 或 ./ 的路径都不合法；assets/icons 和 . 才是典型写法。Windows 下也要用斜杠，不能把 \\ 当分隔符。

官方实现先调用 ValidPath(dir)。如果 dir == "."，直接返回原来的 fsys；如果底层实现了 fs.SubFS，则转交给它；否则创建一个包装器，把子 FS 中的 name 映射为底层的 path.Join(dir, name)。因此“fs.Sub 返回了对象”只能说明路径格式通过了入口检查，不能证明目录已经存在。

用 ValidPath 和 Stat 锁定真实原因

排查时可以把格式、存在性和类型检查写在同一个小函数里。下面的代码只展示诊断思路，示例不会把本机绝对路径塞进 fs.FS：

func checkedSub(fsys fs.FS, dir string) (fs.FS, error) {
    // FS 路径统一使用斜杠；先拦截空串、绝对路径和 ..。
    if !fs.ValidPath(dir) {
        return nil, fmt.Errorf("子路径 %q 非法: %w", dir, fs.ErrInvalid)
    }

    info, err := fs.Stat(fsys, dir)
    if err != nil {
        // 保留底层 PathError，调用方仍可用 errors.Is 判断 ErrNotExist。
        return nil, fmt.Errorf("子路径 %q 不可访问: %w", dir, err)
    }
    if !info.IsDir() {
        // 合法路径也可能指向普通文件，不能把它当目录继续使用。
        return nil, fmt.Errorf("子路径 %q 不是目录", dir)
    }

    sub, err := fs.Sub(fsys, dir)
    if err != nil {
        // 自定义 SubFS 可能在这里增加自己的检查，原样保留错误链。
        return nil, fmt.Errorf("创建子文件系统失败: %w", err)
    }
    return sub, nil
}

调用方可以进一步区分错误类型，而不依赖完整错误字符串：

sub, err := checkedSub(fsys, "assets/icons")
if err != nil {
    // 用 errors.Is 识别通用原因，用 errors.As 读取操作和路径。
    var pathErr *fs.PathError
    switch {
    case errors.Is(err, fs.ErrInvalid):
        log.Println("检查 dir 的 FS 路径格式")
    case errors.Is(err, fs.ErrNotExist):
        log.Println("检查嵌入目录是否真的叫 assets/icons")
    case errors.As(err, &pathErr):
        log.Printf("操作=%s 路径=%s", pathErr.Op, pathErr.Path)
    default:
        log.Printf("其他文件系统错误: %v", err)
    }
}
_ = sub

如果只是想验证返回的子 FS，继续对它调用 fs.ReadDir(sub, ".") 或 fs.Stat(sub, ".")，观察错误中的操作和路径即可。不要只打印 err.Error() 后凭关键词猜测；错误链和 PathError 才是可编程的判断依据。

检查根目录映射和 SubFS 的实现边界

很多“子路径不存在”其实是根目录理解错了。embed.FS、os.DirFS、fstest.MapFS 都把传入的路径解释为各自 FS 的根下路径：如果 FS 的根已经是 static，就不应再写 static/assets。先列出根目录，确认真实层级，再决定 dir。

还要留意底层是否实现了 fs.SubFS。普通 FS 会由标准库包装并按 path.Join 映射；实现了 SubFS 的类型则可以自定义子树创建和错误。若同一 dir 在两种 FS 上表现不一致，应先查接口实现，而不是给路径添加前缀或改用 filepath.Join。此外，fs.Sub 不是 chroot 式安全边界；涉及符号链接和目录访问约束时，应按具体文件系统的安全 API 另行设计。

常见问题

fs.Sub 返回 nil error，是否说明目录存在？

不说明。默认实现不会在创建子 FS 时检查目录当前是否存在，需用 fs.Stat 或对返回 FS 做一次读取验证。

dir 可以写成操作系统的绝对路径吗？

不能。fs.FS 使用无根、斜杠分隔的路径；先把磁盘目录绑定成 FS 的根，再传入根下的相对路径。

为什么 errors.Is 比字符串比较更可靠？

PathError 会包裹 ErrInvalid、ErrNotExist 等通用错误，errors.Is 能跨包装层判断，字符串则可能因实现和版本变化。

实际排查可以固定成一句话：先验 ValidPath，再验根下的 Stat 和目录类型，最后沿 PathError 看失败操作。这样既能处理标准库默认包装，也能给自定义 SubFS 留出明确的检查边界。