如何让ThinkPHP在处理文件时兼容不同操作系统的文件名大小写问题？

本文共计1097个文字，预计阅读时间需要5分钟。

ThinkPHP默认使用`$FILES['file']['name']`获取原始文件名，但Windows不区分大小写，用户上传的`Report.PDF`和`report.pdf`会被视为同一文件；而Linux文件系统区分大小写，一旦保存路径依赖原始大小写（如生成URL或数据库记录），后续按小写路径访问将导致404错误。

关键不是“怎么存”，而是“怎么保真”——必须在上传瞬间就提取并保留原始大小写信息，不能等后续逻辑再猜。

• 别用 pathinfo($file['name'], PATHINFO_FILENAME) 做二次解析，它在 Windows 下可能已失真
• 直接使用 $_FILES['file']['name'] 原始值，但需立即做标准化处理（如转小写存 DB、保留原值存文件系统）
• 若需 URL 可访问，建议统一转小写保存 + 建立大小写映射表，或用哈希名替代原始名（更安全）

ThinkPHP 6 的 File 类自动转换文件名大小写

TP6 的 think\File 在调用 move() 时，默认会调用 getSaveName()，而该方法内部用了 md5_file() + 时间戳生成文件名——看起来规避了问题，但如果你重写了 getSaveName() 并拼接了原始 $file->getClientOriginalName()，就又掉回坑里了。

常见错误是以为“用了 TP6 就自动兼容”，其实只要代码里出现 $file->getClientOriginalName() 或 $file->hashName() 以外的原始名拼接，风险仍在。

立即学习“PHP免费学习笔记（深入）”；

• $file->hashName() 是安全的，它只返回哈希值，不带原始名
• 如果业务强依赖原始文件名（如导出报表需保持 订单_202405.xlsx），必须手动校验：上传时立刻用 mb_strtolower($file->getClientOriginalName()) 存 DB，同时用原始名保存物理文件（注意 Linux 下确保目录可写）
• 不要在 move() 后再读取 $_FILES，PHP 上传临时文件销毁后，$_FILES 里的 name 字段只是字符串，不反映磁盘状态

Apache/Nginx 静态文件路由在 Linux 下因大小写 404

即使 ThinkPHP 正确保存了 IMG_001.JPEG，前端请求 /uploads/IMG_001.jpeg 仍会 404——这不是 PHP 问题，是 Web 服务器配置默认关闭大小写模糊匹配。

不建议改服务器配置来迁就不规范的请求，容易引发缓存混乱和 CDN 同步问题。应该让 PHP 层兜底拦截静态资源请求。

• 在 public/index.php 入口前加一层判断：检查 $_SERVER['REQUEST_URI'] 是否以 /uploads/ 开头，且对应文件不存在，就尝试用小写路径查找
• 用 realpath() + scandir() 检查同目录下是否存在大小写变体（仅限小规模目录，避免性能拖慢）
• 更稳妥的做法：上传时统一用 mb_strtolower() 处理文件扩展名，如 .JPEG → .jpeg，保证存储和 URL 一致

数据库记录文件名大小写混用导致查询失效

MySQL 在 Windows 默认不区分大小写（COLLATION=utf8mb4_general_ci），但 Linux 下同样配置也可能因文件系统底层差异表现不同；更麻烦的是，如果字段类型是 VARCHAR 且没设 _cs（case-sensitive）校对规则，where filename = 'a.jpg' 会命中 A.JPG，导致逻辑错乱。

这不是 ThinkPHP 的锅，但 TP 的 where() 查询默认不强制大小写，容易掩盖问题。

• 建表时明确指定校对规则：filename VARCHAR(255) COLLATE utf8mb4_0900_as_cs（MySQL 8.0+）或 utf8mb4_bin（通用）
• 查询时加 BINARY 强制：用 whereRaw('BINARY filename = ?', [$name])
• TP6 的 whereLike() 默认忽略大小写，要精确匹配必须用 where() + 上述 BINARY 方式

事情说清了就结束。最常被忽略的是：Web 服务器层和数据库层各自有独立的大小写策略，不能只盯着 PHP 代码改。