PHP 8.0+ 升级后，PEAR Mail 扩展因路径解析机制变更导致 Net/SMTP.php 等依赖文件无法加载，引发 500 错误；根本解决方案是将动态 include_once 'Net/SMTP.php' 替换为基于 __DIR__ 的相对路径引用。
php 8.0+ 升级后，pear mail 扩展因路径解析机制变更导致 `net/smtp.php` 等依赖文件无法加载，引发 500 错误；根本解决方案是将动态 `include_once 'net/smtp.php'` 替换为基于 `__dir__` 的相对路径引用。
在将网站从 PHP 7.x 升级至 PHP 8.0 或 8.1 后，许多使用 PEAR Mail + SMTP 发送邮件的项目会突然出现 HTTP 500 内部服务器错误，且错误日志中反复出现类似以下关键信息：
include_once(Net/SMTP.php): Failed to open stream: No such file or directory in /home/.../pear/share/pear/Mail/smtp.php
尽管通过 pear list 可确认 pear/Net_SMTP（v1.10.0）和 pear/Mail 已正确安装，但 PHP 8 引入了更严格的文件包含路径解析策略——不再自动将 include_path 中的 PEAR 目录用于裸字符串路径（如 'Net/SMTP.php'）的解析，尤其在 CGI/FPM 模式下，get_include_path() 的行为与运行时上下文耦合更紧密，导致传统 PEAR 的 require_once 'Net/SMTP.php' 形式失效。
✅ 正确修复方式：统一替换为 __DIR__ 相对路径
需手动修改 PEAR 安装目录下相关 .php 文件中的硬编码 include/require 语句。典型需修改的文件包括（路径以实际 PEAR 安装位置为准，常见于 /usr/share/php/ 或 /home/xxx/pear/share/pear/）：
- Mail/smtp.php
- Mail.php
- Net/SMTP.php（如有嵌套引用）
- PEAR.php
将如下形式的旧代码：
立即学习“PHP免费学习笔记（深入）”；
require_once 'PEAR.php'; include_once 'Net/SMTP.php'; require_once 'Socket.php';
全部替换为基于当前文件目录的显式路径：
require_once __DIR__ . '/../PEAR.php'; include_once __DIR__ . '/../Net/SMTP.php'; require_once __DIR__ . '/Socket.php'; // 注意：Socket.php 通常与 SMTP.php 同级，无需向上
? 验证路径层级：Mail/smtp.php 中的 ../Net/SMTP.php 表示从 Mail/ 目录上溯一级进入 Net/；确保你的 PEAR 目录结构为：
pear/ ├── Mail/ │ └── smtp.php ├── Net/ │ └── SMTP.php └── PEAR.php
⚠️ 注意事项与最佳实践
- 不要依赖 set_include_path() 临时修复：虽可尝试 set_include_path(get_include_path() . PATH_SEPARATOR . '/path/to/pear')，但在 PHP 8.1+ 的严格模式及共享主机环境下不可靠，且违背 PEAR 设计初衷。
- 避免直接修改系统 PEAR（如 /usr/share/php）：若无 root 权限或需多版本共存，建议使用 pear config-set php_dir /your/custom/pear 指定用户级安装路径，并在应用启动时 ini_set('include_path', '/your/custom/pear')。
- 升级替代方案更推荐：PEAR 已于 2017 年停止维护，官方明确建议迁移到 PHPMailer 或 Symfony Mailer。例如，仅需几行即可等效替代原 PEAR 逻辑：
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp.example.com';
$mail->SMTPAuth = true;
$mail->Username = 'user@example.com';
$mail->Password = 'app_password';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port = 587;
$mail->setFrom('from@example.com');
$mail->addAddress($to);
$mail->Subject = 'Test';
$mail->Body = $email_body;
$mail->send(); // ✅ 原生支持 PHP 8.0+- 部署前务必测试：修改后清空 OPcache（opcache_reset() 或重启 PHP-FPM），并在 CLI 和 Web 环境下分别执行 php -r "include 'Mail/smtp.php'; echo 'OK';" 验证基础加载无误。
通过上述路径修正，PEAR Mail 在 PHP 8 环境下可恢复稳定运行；但从长期维护性、安全性与功能丰富度出发，强烈建议将邮件模块逐步迁移至现代、活跃维护的替代库。
