PHP文件名替换需原子写入、OPcache重置、自动加载更新及CDN缓存清理，仅rename()会导致旧代码执行或500错误。
PHP 文件名替换不能靠 rename() 简单重命名就完事
直接用 rename() 改 PHP 文件名，表面上文件变了，但 Web 服务器（如 Nginx/Apache）和 OPcache 都可能还在用旧的字节码或路径缓存。用户访问时仍可能执行旧逻辑，甚至 500 报错——尤其当文件被 include/require 或自动加载器引用时。
真正安全的替换，必须同时满足：文件内容更新、文件路径变更、OPcache 失效、Web 服务路由无残留。
- 先备份原文件：
copy('old.php', 'old.php.bak') - 用新内容写入临时文件（避免原子性中断）：
file_put_contents('new.php.tmp', $newContent) - 再原子重命名：
rename('new.php.tmp', 'new.php') - 绝不要在运行中直接
unlink('old.php'); rename('new.php', 'old.php')—— 这中间存在请求命中空窗期
OPcache 必须手动清除，否则 rename 后照样执行旧代码
PHP 的 OPcache 缓存的是编译后的 opcode，键是文件绝对路径。即使你把 index.php 改成 home.php，只要没清 OPcache，老路径的 opcode 依然在内存里，include('/var/www/index.php') 仍会执行旧逻辑。
清除方式取决于你的部署环境：
立即学习“PHP免费学习笔记（深入）”；
- 开发环境：访问
/opcache-reset.php（需自行创建，内容为opcache_reset();），并确保opcache.enable_cli=1和opcache.restrict_api="" - CLI 手动触发：
php -r "opcache_reset();"（需 PHP CLI 配置与 FPM 一致） - FPM 场景更稳妥：重启 PHP-FPM 进程（
systemctl reload php-fpm或service php7.4-fpm reload），它会强制重建整个 OPcache - 注意：
opcache_invalidate('/path/old.php', true)只对已缓存的文件有效，且不递归清理依赖项，不可靠
Web 服务器配置和自动加载器也得同步更新
文件名改了，但 Nginx 的 location ~ /.php$ 或 Apache 的 FilesMatch 一般不受影响；真正容易出问题的是硬编码路径和自动加载规则。
比如 Composer 的 autoload.files 或 PSR-4 映射里写了 "OldClass" => "lib/old.php"，你把文件改成 new.php 却没改 composer.json，class_exists('OldClass') 就会失败。
- 检查所有
require/include路径是否还指向旧文件名 - 运行
composer dump-autoload（如果用了 Composer 自动加载） - Nginx 中若用了
try_files $uri /index.php?$query_string，确保新入口文件也在匹配链路里，否则 404 - Apache 的
.htaccess若有RewriteRule显式匹配旧文件名，也要一并更新
浏览器和代理缓存不是 PHP 层能控制的，得靠响应头
用户本地浏览器可能缓存了旧 PHP 页面的 HTML 输出（尤其是 GET 请求返回的静态化内容），或者 CDN（如 Cloudflare）缓存了响应体。这跟 PHP 文件名无关，但用户“感觉没更新”，常误以为是 rename 没生效。
关键不是改文件名，而是让客户端重新拉取：
- 在 PHP 响应头加：
header('Cache-Control: no-cache, no-store, must-revalidate'); - 对关键页面（如首页），可加版本参数强制刷新：
- CDN 缓存需单独 purge：Cloudflare 控制台点 “Purge Everything”，或调用 API
/zones/:id/purge_cache - 别依赖
filemtime()动态加时间戳——它只对静态资源有效，PHP 脚本本身输出不受此影响
if (isset($_GET['flush'])) {
opcache_reset();
header('Location: /');
exit;
}
这个小技巧适合临时触发，但上线后务必删掉，避免被滥用清空全站 OPcache。