rename() 是文件系统级原子移动操作，非字符串替换工具；路径须绝对、父目录须存在、不可跨分区，失败静默返回 false，需前置校验权限与路径。
rename() 不是字符串替换工具，它本质是文件系统级的原子移动操作 —— 路径写错、权限不对、跨分区、目标父目录不存在，任一条件不满足都会静默失败（返回 false，不抛异常）。
rename() 参数必须是完整路径，不能只传文件名
常见错误是把 rename('old.txt', 'new.txt') 理解为“当前目录下重命名”，但实际行为取决于 PHP 当前工作目录（getcwd()），而该目录在 Web 服务器中往往不可控（如 Apache 的 DocumentRoot 或 CLI 的启动路径）。一旦路径解析错位，文件就“消失”了。
- ✅ 正确做法：始终用绝对路径或基于已知根路径拼接，例如
rename('/var/www/html/uploads/file.pdf', '/var/www/html/uploads/file_v2.pdf') - ⚠️ 注意：
dirname($newname)必须已存在 ——rename()不会自动创建父目录 - ❌ 错误示例：
rename('data/old.log', 'logs/new.log')—— 若logs/目录不存在，操作直接失败
跨分区移动文件时 rename() 会失败
Linux/macOS 下，rename() 依赖底层 rename(2) 系统调用，该调用仅支持同文件系统（即同挂载点）内的操作。跨分区（如从 /var 移到 /home）必然返回 false，且无明确错误码提示。
- ✅ 替代方案：先
copy($oldname, $newname)，再确认copy()返回true后执行unlink($oldname) - ⚠️ 风险点：若
copy()成功但unlink()失败，会导致文件残留；建议加if (copy(...) && unlink(...))双重判断 - ? 提示：可用
disk_free_space(dirname($newname))预估空间，避免大文件复制中途失败
重命名前必须手动校验路径与权限
rename() 不做任何前置检查，失败后仅返回 false，错误信息需靠 error_get_last() 获取，但该函数在某些 SAPI（如部分 CGI 模式）下可能为空。生产环境必须主动防御。
立即学习“PHP免费学习笔记（深入）”；
- ✅ 推荐校验顺序：
is_file($oldname) || is_dir($oldname)→is_writable(dirname($newname))→!file_exists($newname) || is_writable($newname)（覆盖场景） - ⚠️ Windows 下注意：
$newname若已存在且只读，rename()会失败并触发警告（E_WARNING），但返回值仍是false - ❌ 常见坑：用单引号包裹变量，如
rename('$old', '$new')—— 这是在尝试重命名字面量字符串，不是变量值
批量替换文件名中的某段字符串要自己拼路径
rename() 本身不提供「查找-替换」能力。比如要把所有 _v1. 改成 _v2.，必须自己遍历、拆解、重组路径。
- ✅ 安全做法：用
pathinfo($oldpath)拆出dirname、basename、extension，再用str_replace()处理basename，最后拼回完整路径 - ⚠️ 避免直接对
basename()结果操作后就rename()—— 会丢失原目录层级，导致文件被移到当前工作目录 - ? 冲突预防：批量处理前先用
array_unique()检查新路径是否重复，否则后执行的会覆盖先执行的
最易被忽略的是跨分区场景下的静默失败，以及 Windows 下目标文件只读导致的警告+返回 false 组合。别依赖返回值就认为安全，路径和权限必须提前兜底验证。
