rename()前必须手动检查源文件存在、源目录可读删、目标父目录存在且可写，Windows还需确保文件句柄已释放，跨文件系统时需用copy()+unlink()替代。
rename() 执行前必须检查文件是否存在且可写
PHP 的 rename() 函数不会自动校验目标目录是否可写、源文件是否存在或用户是否有权限重命名。直接调用失败时只返回 false，错误信息藏在系统层（如 Permission denied 或 No such file or directory），不抛异常。所以替换前必须手动验证关键条件。
常见错误现象：rename(): Permission denied（目标目录不可写）、rename(): No such file or directory（源路径错或目标父目录不存在）、rename(): File exists（目标已存在且未开启覆盖逻辑）。
- 用
file_exists()检查源文件是否存在 - 用
is_writable()检查源文件所在目录（不是文件本身）和目标文件所在目录是否都可写 - 用
dirname()提取目标路径的父目录，并确保它存在（is_dir()+mkdir(..., 0755, true)）
正确顺序：检查 → 创建目录 → 执行 rename()
不能跳过中间步骤。比如目标路径是 /var/www/uploads/newname.jpg，需确认 /var/www/uploads/ 存在且可写；若不存在，rename() 必然失败，即使源文件一切正常。
注意：is_writable() 在某些 Linux 环境下对目录可能返回 false（尤其启用了 safe_mode 或 open_basedir 限制），此时应结合 touch() 尝试创建临时文件来实测写权限。
立即学习“PHP免费学习笔记（深入）”；
if (!file_exists($old_path)) {
throw new RuntimeException("Source file does not exist: $old_path");
}
$target_dir = dirname($new_path);
if (!is_dir($target_dir)) {
if (!mkdir($target_dir, 0755, true)) {
throw new RuntimeException("Cannot create target directory: $target_dir");
}
}
// 实测目标目录是否真能写
$test_file = $target_dir . '/.write_test_' . uniqid();
if (!@touch($test_file) || !unlink($test_file)) {
throw new RuntimeException("Target directory is not writable: $target_dir");
}
if (rename($old_path, $new_path) === false) {
throw new RuntimeException("Failed to rename: $old_path → $new_path");
}
Windows 下要注意文件句柄未释放导致 rename 失败
Windows 系统中，如果源文件正被 PHP 自身（如 fopen()、imagecreatefromjpeg()）或外部进程（如杀毒软件、资源管理器预览窗格）打开，rename() 会报错 Access is denied。这不是权限配置问题，而是系统级锁。
解决方法：
- 确保所有对该文件的
fopen()已调用fclose() - 避免在
rename()前使用 GD 函数加载图片后未释放资源（imagedestroy()） - 必要时加
clearstatcache(true, $old_path)避免缓存干扰判断
替代方案：copy() + unlink() 更可控但非原子操作
当 rename() 因跨文件系统（如不同挂载点）失败时，Linux/Unix 下会退化为 copy+delete，而 PHP 不会自动处理——此时必须手动实现。但注意：copy() + unlink() 不是原子操作，中途失败会导致源文件丢失或目标不完整。
使用场景仅限：rename() 明确返回 false 且 error_get_last()['message'] 含 Invalid cross-device link。
务必先 copy() 成功，再 unlink() 源文件，并检查每一步返回值：
if (!copy($old_path, $new_path)) {
throw new RuntimeException("Copy failed: $old_path → $new_path");
}
if (!unlink($old_path)) {
// 复制成功但删除失败：留下副本，需人工干预
throw new RuntimeException("Unlink failed after copy, orphan file exists: $old_path");
}
权限检查不是“有就行”，而是要精确到「目标父目录可写」和「源目录可读可删」两个维度；跨系统移动、Windows 句柄锁定、PHP 缓存干扰，都是线上 rename 失败最常被忽略的三个点。