rename() 是 PHP 唯一标准、跨平台、原子性保障的文件重命名函数，成功返回 true，失败返回 false，需检查返回值并确保路径权限正确。
PHP 文件名替换用 rename() 最直接
PHP 本身不提供“重命名文件并自动触发事件”的内置机制，rename() 是唯一标准、跨平台、原子性保障的文件重命名函数。它不依赖 shell 命令，也不需要额外扩展，只要 PHP 进程对源路径和目标路径有读写权限即可生效。
常见错误是误用 copy() + unlink() 组合——这非原子操作，中间出错（如磁盘满、权限突变）会导致文件丢失或残留。而 rename() 在同文件系统内是瞬时完成的，失败则原样保留。
-
rename()成功返回true，失败返回false，务必检查返回值 - 目标路径不能已存在（Windows 下会失败；Linux 下默认覆盖，但行为不可靠，应先
file_exists()判断） - 跨文件系统（如从
/tmp移到/home）时，rename()可能退化为拷贝+删除，此时无原子性保障 - 路径必须是绝对路径或相对于当前工作目录（
getcwd()），建议统一用__DIR__或realpath()构造
if (rename('/var/www/old.jpg', '/var/www/new_v2.jpg')) {
echo "文件已重命名";
} else {
error_log('rename 失败：' . error_get_last()['message']);
}
PHP 没有“文件重命名后自动触发事件”的机制
操作系统层面的 inotify（Linux）、kqueue（macOS）或 ReadDirectoryChangesW（Windows）可以监听文件系统事件，但 PHP 默认不绑定这些。你写的 PHP 脚本执行完就退出，不会长期驻留监听。
所谓“替换后触发事件”，本质是两种不同场景：
立即学习“PHP免费学习笔记（深入）”；
-
同步响应：重命名完成后，立刻执行后续逻辑（如更新数据库、生成缩略图）——直接在
rename()后写代码即可 - 异步通知：其他进程/服务需要感知该变更（如 CDN 刷新、日志聚合、前端轮询更新）——需主动推送，而非等待“事件”
不要试图用 pcntl_fork() 或 exec('inotifywait') 在 Web 请求中监听，这极易导致超时、僵尸进程或资源泄漏。
替代方案：重命名后显式调用你需要的逻辑
把“事件”理解成函数调用，而不是操作系统信号。这是最可控、可测试、符合 PHP 运行模型的做法。
- 封装一个
renameWithAction($old, $new, $callback)函数，内部调用rename()并在成功后执行$callback - 若需跨服务通知，用 HTTP 请求（
file_get_contents()或cURL）调用另一个 API 端点，或写入 Redis 队列（redis->lPush('file_events', json_encode([...]))） - 避免在回调里做耗时操作（如压缩图片、转码视频），应投递到消息队列或后台任务，防止 Web 请求阻塞
$result = rename('/data/uploads/photo_123.tmp', '/data/uploads/photo_123.jpg');
if ($result) {
// 同步动作：记录日志、更新 DB
update_file_record('photo_123.jpg', 'uploaded_at', date('Y-m-d H:i:s'));
// 异步动作：发通知（非阻塞方式）
file_put_contents('/tmp/file_events.log', "RENAMED: photo_123.jpg/n", FILE_APPEND);
}
容易被忽略的关键点
权限和路径问题比逻辑更常导致失败。很多“重命名不生效”其实根本没走到你的业务代码里。
-
rename()的源路径和目标路径父目录必须可写（不是文件可写，而是目录可写） - Web 服务器用户（如
www-data或nginx）必须同时拥有源文件读权限、目标目录写权限 - SELinux 或 AppArmor 开启时，即使权限全开也会拒绝重命名，需检查
ausearch -m avc -ts recent日志 - Windows 下注意路径分隔符，
rename('C:/old.txt', 'C:/new.txt')可能失败，统一用str_replace('//', '/', $path)或dirname(__FILE__)
别指望 PHP 自动感知文件变化，它只是执行了一次函数调用。后续所有动作，都得你明确写出来。