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）。
立即学习“PHP免费学习笔记（深入）”；
- 不要依赖大小写变更来“刷新”文件名，尤其部署到不同系统时
- 若需强制更新，可先
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()，而是它背后牵扯的路径合法性、权限继承、原子性保障和跨平台行为差异——这些地方一漏，线上就静默丢文件。
