本文介绍如何在 Go 中高效、安全地遍历指定目录（如 project/）下的所有直接子文件和一级子目录中的文件，跳过深层嵌套目录，避免 filepath.Walk 误用导致的无限递归，并提供简洁可复用的实现方案。
本文介绍如何在 Go 中高效、安全地遍历指定目录（如 `project/`）下的所有**直接子文件**和**一级子目录中的文件**，跳过深层嵌套目录，避免 `filepath.Walk` 误用导致的无限递归，并提供简洁可复用的实现方案。
在 Go 开发中，常需对项目目录结构进行扁平化扫描——例如批量读取 docs/、templates/ 等一级子目录下的 HTML 或 Markdown 文件，但不进入 docs/api/v1/ 这类二级及更深路径。此时若错误混合使用 filepath.Walk 与手动递归（如原问题中在回调内再次调用 filepath.Walk），极易引发路径重复解析、无限循环或 panic。
核心原则是：“两层深度，非递归” —— 即仅处理：
- 当前目录（project/）下的所有条目；
- 若某条目为目录，则仅遍历其直接子项（即 project/docs/ 下的文件），不再向下深入。
以下为推荐实现（基于 os.ReadDir，自 Go 1.16 起推荐替代已弃用的 ioutil.ReadDir）：
package main
import (
"fmt"
"log"
"os"
"path/filepath"
)
func traverseTopTwoLevels(root string) error {
// 第一层：读取 root 目录下的所有条目
entries, err := os.ReadDir(root)
if err != nil {
return fmt.Errorf("failed to read root directory %q: %w", root, err)
}
for _, entry := range entries {
entryPath := filepath.Join(root, entry.Name())
if entry.IsDir() {
// 第二层：仅遍历该一级子目录下的文件（跳过其子目录）
subEntries, err := os.ReadDir(entryPath)
if err != nil {
log.Printf("warning: skipping subdirectory %q: %v", entryPath, err)
continue
}
for _, subEntry := range subEntries {
if !subEntry.IsDir() {
fullPath := filepath.Join(entryPath, subEntry.Name())
fmt.Printf("? File (in subdirectory): %s\n", fullPath)
// ✅ 此处可调用 processFile(fullPath) 进行内容读取等操作
}
}
} else {
// 第一层文件：直接处理
fmt.Printf("? File (in root): %s\n", entryPath)
// ✅ 此处可调用 processFile(entryPath) 进行内容读取等操作
}
}
return nil
}
func main() {
if err := traverseTopTwoLevels("project"); err != nil {
log.Fatal(err)
}
}✅ 关键优势说明：
- 无递归、无嵌套 Walk：彻底规避原问题中 filepath.Walk(file.Name(), traverse) 导致的路径错乱与无限循环；
- 路径安全：使用 filepath.Join 拼接路径，兼容 Windows/Linux/macOS；
- 错误隔离：子目录读取失败时仅警告并跳过，不影响其他路径处理；
- 清晰分层逻辑：外层循环处理 root → 内层循环处理 root/*/ → 严格限制深度为 2。
⚠️ 注意事项：
- 不要混用 filepath.Walk 与手动目录遍历逻辑，二者目标不同：Walk 是通用深度优先遍历，而本场景需精确控制层级；
- os.ReadDir 返回的是 fs.DirEntry（轻量、不包含完整 os.FileInfo），如需文件大小、修改时间等元信息，可调用 subEntry.Info()（会触发一次系统调用，按需使用）；
- 若需过滤特定扩展名（如 .html, .md），可在 if !subEntry.IsDir() 后添加 strings.HasSuffix(subEntry.Name(), ".html") 判断；
- 生产环境建议将 fmt.Printf 替换为结构化日志（如 zap），并为 processFile 添加错误处理与超时控制。
总结：面对“仅遍历当前目录 + 一级子目录文件”的明确需求，应放弃通用递归方案，转而采用两层 os.ReadDir 循环——代码更短、语义更清、性能更高、bug 更少。
