本文详解 php `rename()` 函数重命名目录的正确用法，重点纠正常见的字符串引号误用导致的“系统找不到指定文件（code: 2）”错误，并提供完整可运行示例、权限与路径注意事项及最佳实践。
在 PHP 中使用 rename() 函数重命名文件夹是一项基础但易出错的操作。许多开发者在尝试动态修改站点目录名（如因站点名称变更需同步更新物理文件夹名）时，会遇到典型的 Windows 错误提示：“The system cannot find the file specified. (code: 2)”。该错误绝大多数情况下并非路径真实不存在，而是因参数传递方式不当所致。
? 根本原因：变量被错误地包裹在单引号中
你提供的代码片段中存在一个关键语法错误：
rename('$OldNameFolder','$NewNameFolder'); // ❌ 错误！单引号会原样输出字符串，不解析变量PHP 中，单引号字符串不会解析变量，因此上述调用实际等价于：
rename('$OldNameFolder', '$NewNameFolder'); // 字面量字符串，而非变量值这会导致 rename() 尝试将名为字面量 '$OldNameFolder' 的文件夹重命名为 '$NewNameFolder' —— 显然路径不存在，故抛出 code 2 错误。
立即学习“PHP免费学习笔记（深入）”；
✅ 正确写法是直接传入已拼接完成的变量（推荐），或使用双引号（不推荐，易混淆）：
$OldNameFolder = $path . $OldName;
$NewNameFolder = $path . $NewName;
// ✅ 推荐：直接传变量（清晰、高效、无歧义）
if (rename($OldNameFolder, $NewNameFolder)) {
echo "文件夹已成功重命名为: {$NewNameFolder}";
} else {
$error = error_get_last();
echo "重命名失败：{$error['message']}";
}⚠️ 关键注意事项（生产环境必查）
-
路径必须绝对且真实存在：$OldNameFolder 必须指向一个已存在的目录；$NewNameFolder 的父目录（即 $path）必须可写。建议使用 is_dir() 和 is_writable() 预检：
if (!is_dir($OldNameFolder)) { throw new Exception("源目录不存在: {$OldNameFolder}"); } if (!is_writable(dirname($NewNameFolder))) { throw new Exception("目标父目录不可写: " . dirname($NewNameFolder)); } 跨文件系统限制：rename() 在 Linux/Unix 下无法跨挂载点（如从 /var/www 移动到 /home/user）；Windows 下虽支持跨驱动器，但本质是“复制+删除”，性能差且非原子操作。若需跨卷操作，请改用 RecursiveIteratorIterator + 手动复制删除。
权限与安全：确保 Web 服务器进程（如 www-data、apache 或 nginx 用户）对源目录有读取+执行（rx）权限，对目标父目录有写入+执行（wx）权限。切勿直接拼接用户输入（如 $_POST['new_name']）进路径——务必校验、过滤、白名单限制，防止路径遍历（../）攻击。
Windows 特别提醒：目标文件夹名不能正在被其他进程占用（如资源管理器打开、IDE 索引中、命令行处于该目录）。建议操作前关闭相关工具，或添加重试逻辑。
✅ 完整健壮示例（含错误处理与日志）
function renameDirectory(string $oldPath, string $newPath): bool
{
// 规范化路径，消除冗余分隔符
$oldPath = realpath($oldPath);
$newPath = rtrim($newPath, '/\\');
if (!$oldPath || !is_dir($oldPath)) {
error_log("[RenameDir] 源路径无效或不存在: {$oldPath}");
return false;
}
$parentDir = dirname($newPath);
if (!is_dir($parentDir) || !is_writable($parentDir)) {
error_log("[RenameDir] 目标父目录不可写: {$parentDir}");
return false;
}
if (is_dir($newPath)) {
error_log("[RenameDir] 目标目录已存在: {$newPath}");
return false;
}
$result = rename($oldPath, $newPath);
if ($result) {
error_log("[RenameDir] 成功: {$oldPath} → {$newPath}");
} else {
$err = error_get_last();
error_log("[RenameDir] 失败: {$oldPath} → {$newPath}, Error: {$err['message']}");
}
return $result;
}
// 使用示例
$path = '/var/www/sites/';
$OldName = 'old-site';
$NewName = 'new-site';
if (renameDirectory($path . $OldName, $path . $NewName)) {
echo "✅ 站点文件夹已更新为 '{$NewName}'";
} else {
echo "❌ 重命名失败，请检查日志";
}掌握 rename() 的正确调用方式，规避引号陷阱，并辅以严谨的路径验证与权限检查，即可安全、可靠地实现 PHP 中的目录重命名需求——无论是自动化部署、多租户站点切换，还是 CMS 的结构迁移，都将成为可控的常规操作。
