Go 的 os.Stat 返回的文件名总是与传入路径一致，无法反映磁盘上实际的大小写形式；要获取真实文件名，需遍历父目录并匹配 inode 或路径，本文详解实现方法与跨平台注意事项。
go 的 `os.stat` 返回的文件名总是与传入路径一致，无法反映磁盘上实际的大小写形式；要获取真实文件名，需遍历父目录并匹配 inode 或路径，本文详解实现方法与跨平台注意事项。
在开发 lint 工具（如强制要求资源文件名为全小写）时，一个常见误区是依赖 os.Stat("path/FILE.PNG").Name() 获取磁盘上的真实文件名——但该方法永远返回你传入的字符串，而非文件系统中实际存储的大小写形式。这是因为 os.FileInfo.Name() 仅是 API 层面的便捷字段，并不查询目录项；底层系统调用（如 POSIX stat() 或 Windows GetFileAttributesEx）本身不携带“真实文件名”信息。
✅ 正确方案：通过父目录枚举匹配
真实文件名存在于父目录的目录项（directory entry）中。因此，需：
- 解析目标路径的父目录和基础名（不区分大小写）；
- 读取父目录所有条目；
- 找到与目标文件逻辑等价（相同 inode 或相同路径）的条目，并提取其原始大小写名称。
以下是跨平台安全的实现示例：
package main
import (
"os"
"path/filepath"
"strings"
)
// GetActualFilename 返回磁盘上文件的真实大小写敏感名称（不含路径）
// 若文件不存在或权限不足，返回空字符串和 error
func GetActualFilename(path string) (string, error) {
dir := filepath.Dir(path)
base := filepath.Base(path)
// 读取父目录所有条目
entries, err := os.ReadDir(dir)
if err != nil {
return "", err
}
// 不区分大小写匹配（适用于大多数场景）
for _, ent := range entries {
if strings.EqualFold(ent.Name(), base) {
return ent.Name(), nil
}
}
return "", os.ErrNotExist
}
// 使用示例
func main() {
actual, err := GetActualFilename("some/asset.PNG")
if err != nil {
panic(err)
}
if strings.ToLower(actual) != actual {
println("❌ 文件名含大写字母:", actual)
} else {
println("✅ 符合规范:", actual)
}
}⚠️ 注意事项与进阶建议
- 大小写敏感性取决于文件系统：Linux ext4 默认大小写敏感，macOS APFS（默认启用 Case-insensitive）和 Windows NTFS 通常大小写不敏感 —— 因此 strings.EqualFold 是合理且兼容的匹配方式。
- 硬链接与多路径问题：单个 inode 可能对应多个不同大小写的路径（如通过 ln 创建）。本方案只返回目录中首个匹配项，符合 lint 场景需求；如需精确 inode 匹配，可结合 ent.Sys().(*syscall.Stat_t).Ino（Unix）或 ent.Sys().(*syscall.Win32FileAttributeData)（Windows）进一步校验。
- 性能考量：对单个文件检查，目录遍历开销极小；若需批量校验，建议缓存目录内容或使用 filepath.WalkDir 预扫描整个目录树。
- 符号链接处理：os.ReadDir 默认解析符号链接的目标目录；如需保留链接路径语义，请先用 os.Lstat 判断并跳过。
总之，os.Stat().Name() 不是“真实文件名”的来源——它只是一个输入回显。真正可靠的方式始终是向父目录索要它所记录的原始名称。这一原则不仅适用于 Go，也是理解现代文件系统抽象的关键。
