17370845950

rename()本质是文件系统级移动+重命名，需同分区、全路径、父目录存在、目标可覆盖；不支持字符串替换，须手动处理路径；跨平台注意大小写敏感性及错误捕获。

PHP 中用 rename() 替换文件名，本质是「移动+重命名」，不是字符串替换。直接调用就能生效，但路径、权限、跨分区等细节容易出错。

rename() 的基本用法和路径要求

rename() 实际执行的是文件系统级的重命名或移动操作，第一个参数是源路径，第二个是目标路径。两个路径必须在同一个文件系统（即同个磁盘分区）下才 100% 可靠；跨分区时可能失败并返回 false。

• 源路径和目标路径都必须是完整路径（绝对或相对），不能只传文件名
• 目标路径的父目录必须已存在，rename() 不会自动创建目录
• 如果目标文件已存在，会被直接覆盖（无提示）
• 建议始终用

  

  is_file() 和 is_writable() 提前校验

if (is_file('/var/www/old.txt') && is_writable(dirname('/var/www/new_name.txt'))) {
    if (rename('/var/www/old.txt', '/var/www/new_name.txt')) {
        echo "成功";
    } else {
        echo "失败：检查权限或是否跨分区";
    }
}

想批量替换文件名中的某段字符串？得自己拼路径

rename() 本身不提供「查找并替换文件名中某个子串」的功能。你需要先读取文件列表，用 str_replace() 或 preg_replace() 处理文件名，再组合成新路径调用 rename()。

• 别直接对 basename() 结果做 str_replace() 后就 rename —— 必须保留原目录结构
• 推荐用 pathinfo() 拆解路径，安全拼接新文件名
• 注意避免重名冲突，比如多个文件替换成同一名字，后调用的会覆盖前一个

$oldPath = '/var/www/report_v1.log';
$pathInfo = pathinfo($oldPath);
$newBasename = str_replace('_v1.', '_v2.', $pathInfo['basename']);
$newPath = $pathInfo['dirname'] . '/' . $newBasename;

if (rename($oldPath, $newPath)) {
    echo "已重命名为: $newPath";
}

Windows 下大小写不敏感，Linux 下要特别小心

在 Linux / macOS 等大小写敏感文件系统中，rename('a.txt', 'A.TXT') 是合法操作，会产生两个不同文件；而 Windows 下这会被视为同一文件，rename() 直接返回 false（或静默失败，取决于 PHP 版本和 SAPI）。

• 不要依赖大小写变更来“刷新”文件名，尤其部署到不同系统时
• 若需强制更新，可先 unlink() 再 file_put_contents()，但会丢失原文件属性（如修改时间、权限位）
• 跨平台脚本中，建议统一转小写或加哈希后缀，避免仅靠大小写区分

rename() 失败却不报错？检查错误抑制符和错误报告级别

常见误操作是在 rename() 前加了 @ 错误抑制符，或 error_reporting 关闭了警告，导致失败无声无息。

• 开发阶段务必关闭 @，打开 error_reporting(E_ALL)
• 失败后可用 error_get_last() 查看最近系统级错误（如 “Permission denied”、“No such file or directory”）
• 某些共享主机禁用 rename() 跨目录操作，此时只能用 copy() + unlink() 模拟

rename('/tmp/abc', '/home/user/def');
if (false === $result) {
    $err = error_get_last();
    echo "rename 失败: " . ($err['message'] ?? '未知错误');
}

真正麻烦的不是怎么写这一行 rename()，而是它背后牵扯的路径合法性、权限继承、原子性保障和跨平台行为差异——这些地方一漏，线上就静默丢文件。