Go os.ReadDir 配合 fs.ValidPath 构建目录索引

用 Go 构建目录索引时，可以让 os.ReadDir 读取本机目录，再用 fs.ValidPath 检查要保存的相对索引名称。两者处理的是不同层面的路径：读取目录使用操作系统路径，索引名称采用 io/fs 的斜杠分隔约定。

下面先做一个单层索引，只保存目录项名称和是否为目录。它不会递归读取子目录，也不会把名称格式检查当成文件存在、访问权限或目录隔离的证明。

官方文档：https://pkg.go.dev/os#ReadDir；名称规则：https://pkg.go.dev/io/fs#ValidPath。本文解释索引设计约定，不涉及某个新提案或版本变更。

先把读取路径与索引名称分开

一种容易混淆的写法，是先把根目录和文件名拼成本机完整路径，再将它交给 ValidPath。若根目录是绝对路径，这个字符串可能完全适合 os.ReadDir 或 os.Open，却不符合 io/fs 相对名称的用途。

更清楚的约定是保留两个变量：root 代表要读取的本机目录，name 代表根目录下的索引项名称。持久化索引时不用把某台机器的目录前缀写进每条记录，展示时也更容易得到简洁名称。

索引名称采用io/fs的相对路径规则

io/fs 路径统一使用正斜杠分隔，普通路径元素不能是空串、点或双点；根目录名称有一个特殊情况，单独的点是有效名称。索引项目如果只存根目录的孩子，应自行排除这个根标记。

ValidPath 不会检查名称对应的文件是否存在。它也不是“禁止所有特殊字符”的过滤器：反斜杠、冒号可以通过其名称规则，但 io/fs 实现不能把这些字符解释成路径分隔符。涉及系统路径转换时要另看目标平台的表示能力。

用ReadDir构建单层目录索引

将下面原创示例保存为 main.go，可在读者自己的目录中使用。示例处理本地受控目录，先完成全部读取和名称检查，再返回索引；遇到错误直接返回，避免调用方误把部分结果当成完整清单。

package main

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

type Entry struct {
    Name  string
    IsDir bool
}

func BuildIndex(root string) ([]Entry, error) {
    entries, err := os.ReadDir(root)
    if err != nil {
        // 即使已读取部分目录项，也不把它当成一次完整索引。
        return nil, fmt.Errorf("读取目录 %q: %w", root, err)
    }

    result := make([]Entry, 0, len(entries))
    for _, entry := range entries {
        name := entry.Name()
        // 单层索引使用目录项原名；拒绝不满足io/fs约定的名称。
        if !fs.ValidPath(name) || name == "." {
            return nil, fmt.Errorf("名称不能作为索引项: %q", name)
        }
        result = append(result, Entry{Name: name, IsDir: entry.IsDir()})
    }
    return result, nil
}

func main() {
    // root是本机路径，不作为io/fs名称交给ValidPath。
    index, err := BuildIndex(".")
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    for _, entry := range index {
        // 使用带引号的名称展示，避免特殊字符混入普通文本。
        fmt.Printf("%q directory=%t\n", entry.Name, entry.IsDir)
    }
}

os.ReadDir 按文件名排序返回目录项，因此这个示例追加记录时沿用该顺序；它不是按修改时间、大小或自然数字顺序排列。若需要其他次序，应在索引层明确增加字段与排序规则。

IsDir 为 false 不等于“确定是普通文件”，例如符号链接也不能仅靠这个布尔值归类为普通文件。若业务需要文件类型、大小或修改时间，应另行获取适合的元数据并处理相关错误。

需要嵌套目录或系统路径时怎样扩展

要加入子目录时，需要显式递归或换成合适的遍历方式。递归索引应分别维护“用于读取的本机路径”和“用于保存的斜杠相对名”，不要在两个命名空间里混用拼接函数。

如果已经有一个符合 io/fs 规则的名字，需要把它转换成本机路径，可以考虑 filepath.Localize。该函数从 Go 1.23 提供，转换时还会判断名称能否在当前操作系统表示；例如反斜杠在 Windows 上的含义与普通 io/fs 名称字符不同。

这并不意味着应在所有索引写入时立即转换。索引若按 io/fs 约定保存，保留正斜杠名称即可；真正操作本机文件时，再在适当边界做转换并处理错误。较旧工具链不能直接使用 Localize，应按项目支持版本设计适配。

名称检查只判断词法形式，不能解决符号链接指向、并发目录变化或授权范围问题。对于会被其他进程修改的目录，索引也只是某次读取观察到的清单，不能承诺目录在之后仍保持相同状态。

读取失败、特殊名称与常见问题

为什么明明已有部分记录，却还返回错误？ os.ReadDir 可能同时返回已读到的目录项和读取错误。本文代码有意放弃部分结果；如果业务允许部分索引，应设计明确的“未完成”状态，而不是悄悄忽略错误。

文件名无法通过ValidPath时，能先清理再保存吗？ 不应随意把实际名称改成另一个名称，否则索引可能无法准确对应原始对象，还可能出现重名。可以明确拒绝、记录异常，或另行设计可逆的名称映射；不要用清理操作掩盖输入差异。

为什么没有读取子目录里的文件？ os.ReadDir 读取的是指定目录的直接目录项。本例的 IsDir 字段只是分类信息，没有触发递归。

怎样使用这段示例？ 在自己的 Go 环境中执行下面命令，观察带引号的名称与 directory 标记；实际结果取决于该目录内容。本文未执行示例，不提供伪造的清单输出。

# 在保存main.go的目录中运行，读取当前目录的直接目录项。
go run main.go

参考：os.ReadDir 文档；io/fs 名称规则；filepath.Localize 文档。