“Filename too long”错误的直接原因是操作系统（如Windows限260字符）对完整路径长度的限制，PHP函数调用时超出该上限即报错；需用realpath()检测真实路径长度，结合系统启用长路径支持或重构路径逻辑解决。
PHP中遇到“Filename too long”错误的直接原因
这个错误不是PHP本身抛出的，而是操作系统（尤其是Windows或某些旧版Linux）对路径长度有限制，当file_put_contents、rename、fopen等函数操作的完整路径（含盘符、目录、文件名、扩展名）超过系统上限（Windows通常为260字符），就会触发类似Filename too long的报错，部分PHP版本会转译成Invalid argument或静默失败。
检查并缩短实际路径长度的实操步骤
别只盯着文件名——完整路径才是关键。先用代码确认当前操作的真实路径：
echo 'Full path: ' . realpath($filename) . PHP_EOL; echo 'Length: ' . strlen(realpath($filename)) . PHP_EOL;
- 使用
realpath()展开所有../和符号链接，得到真实路径 - Windows下若路径以
//?/开头（启用长路径支持），PHP 7.4+ 才能识别；旧版PHP会忽略前缀导致截断 - 临时解决：把目标目录移到更短路径下，比如
C:/tmp/而非C:/Users/LongUserName/Projects/.../cache/... - 避免在路径中拼接大量动态子目录层级，改用哈希分片：
$dir = __DIR__ . '/cache/' . substr(md5($key), 0, 2) . '/' . substr(md5($key), 2, 2);
Windows启用长路径支持（PHP 7.4+ 可用）
仅修改PHP代码不够，系统层必须放开限制，否则/?/C:/...前缀会被忽略：
- 管理员运行PowerShell，执行：
Set-ItemProperty -Path "HKLM:/SYSTEM/CurrentControlSet/Control/FileSystem" -Name "LongPathsEnabled" -Value 1 - 重启PHP服务（php-fpm 或 Apache）或命令行终端
- PHP中显式使用长路径前缀：
$long_path = '////?//' . realpath($filename);，注意双反斜杠转义 - 注意：
//?/不支持相对路径、..、通配符，且file_exists()等函数可能仍返回false，需搭配is_file()或直接尝试读写
绕过路径长度限制的替代方案
当无法控制部署环境（如共享主机）时，优先改写逻辑而非硬扛路径：
立即学习“PHP免费学习笔记（深入）”；
- 用
tempnam(sys_get_temp_dir(), 'php_')生成短路径临时文件，再rename()过去——临时目录路径通常很短 - 改用
stream_context_create(['http' => ['timeout' => 5]])配合file_get_contents('php://temp')暂存内容，避免落地长路径 - 数据库或Redis存二进制内容，文件系统只存ID，彻底脱离路径长度依赖
- Web服务器配置别名（如Nginx
alias /short/ /very/long/real/path/;），让PHP操作短路径，由服务器映射
路径长度问题本质是系统与运行时协同的结果，单独改PHP代码或单独调系统设置都容易漏掉一环。最稳妥的做法是：先测真实路径长度，再决定走系统启用长路径、还是重构路径生成逻辑。