本文揭示一个在多站点共存环境下偶发的 php “fatal error: cannot redeclare” 错误的真实成因——并非代码或路径问题，而是 runkit7 与 opcache 模块的已知不兼容性导致函数定义被错误共享和缓存。
本文揭示一个在多站点共存环境下偶发的 php “fatal error: cannot redeclare” 错误的真实成因——并非代码或路径问题，而是 runkit7 与 opcache 模块的已知不兼容性导致函数定义被错误共享和缓存。
在 Apache 共享 PHP 模块（如 libphp）的部署中，多个虚拟主机（如 /var/www/one/ 和 /var/www/two/）若使用完全隔离的文件路径（如全路径 require_once('/var/www/one/htdocs/functions.php')），理论上不应发生跨站点函数重复声明。然而，实践中却出现如下难以复现的致命错误：
Fatal error: Cannot redeclare okay() (previously declared in /var/www/two/htdocs/functions.php:3) in /var/www/one/htdocs/functions.php on line 3
该错误具有典型“偶发性”特征：仅在高流量时段成批出现（所谓“streaks”），重启 Apache 后短暂消失，数分钟内重现；get_included_files() 返回结果缺失实际定义函数的文件，但 function_exists('okay') 却返回 true——这明确指向函数符号表已被污染，而非文件包含逻辑错误。
根本原因：runkit7 模块引发的符号污染
尽管 OPcache 常被怀疑（因其默认按函数名而非完整路径缓存），但用户已正确启用关键防护配置：
opcache.revalidate_path = 1 opcache.use_cwd = 1 opcache.file_cache_consistency_checks = 1
且所有 require_once 均使用绝对路径，排除了路径解析歧义。真正的问题在于另一个被忽略的模块：runkit7。
立即学习“PHP免费学习笔记（深入）”；
runkit7 是一个用于运行时修改函数、类、常量等定义的调试/开发扩展。它通过直接操作 Zend 引擎的符号表（symbol table）实现功能，而该操作与 OPcache 的编译后字节码缓存机制存在底层冲突。官方 issue #217 明确指出：当两者共存时，runkit7 可能导致函数定义在不同请求上下文间“泄漏”，尤其在 Apache prefork MPM 下，子进程复用导致 OPcache 缓存与 runkit7 修改状态跨虚拟主机污染。
✅ 验证方式：临时禁用 runkit7
sudo phpdismod runkit7 sudo systemctl reload apache2错误立即消失，且不再复现。
正确解决方案与最佳实践
| 场景 | 推荐方案 | 说明 |
|---|---|---|
| 生产环境 | ✅ 彻底禁用 runkit7 | 该模块不应出现在生产环境。其设计目标仅为开发/调试，引入严重安全与稳定性风险。 |
| 需动态调试能力 | ✅ 切换至 PHP-FPM + 独立 Pool | 为每个站点配置独立 FPM pool（php-fpm.d/one.conf, two.conf），并确保 runkit7 仅在特定 pool 的 php.ini 中启用（或更优：完全不用）。进程隔离天然阻断符号污染。 |
| 必须保留 OPcache + 多站点 | ✅ 确保 opcache.validate_root = 1（PHP ≥ 8.2）或严格路径隔离 | 避免任何相对路径、include_path 或 __DIR__ 混用；所有 require_once 使用 realpath() 归一化绝对路径。 |
代码层防御（辅助手段，非根本解）
即使模块配置正确，仍建议在关键函数定义前增加显式保护：
// config.php 中（在 require_once functions.php 前）
if (!function_exists('okay')) {
require_once('/var/www/one/htdocs/functions.php');
} else {
// 记录异常上下文（仅用于诊断）
error_log(
sprintf(
"[RUNKIT CONFLICT?] Function 'okay' already exists. Included: %s\n",
implode(',', get_included_files())
),
3,
'/var/log/php/runkit-debug.log'
);
}⚠️ 注意：此检查不能替代模块治理，仅用于快速定位残留问题。
总结
- ❌ 不要将 runkit7、xdebug（开发模式）、uopz 等运行时修改扩展带入生产环境；
- ✅ 多站点共享 PHP 模块时，优先采用 PHP-FPM 进程隔离，而非 Apache 模块直连；
- ✅ 所有缓存相关模块（OPcache、APCu）必须与运行时修改类扩展严格互斥；
- ? 遇到“不可能”的函数重复声明，优先检查 php -m 输出，排查非常规扩展。
真正的稳定性，源于对扩展能力边界的敬畏，而非对 require_once 的盲目信任。
