CodeIgniter 4作为轻量高效的PHP开发框架，内置了邮件发送功能，很多开发者会选择使用SMTP方式发送邮件，但在实际使用中经常会遇到发送失败的问题，这类问题需要从配置、环境、服务商规则多个维度排查。
常见失败原因及排查步骤
1. 基础配置参数错误
SMTP发送邮件首先需要保证配置参数和服务商提供的信息完全一致，最常见的错误是用户名、密码、主机地址填写错误。需要注意部分SMTP服务商的密码不是账号登录密码，而是专用的应用授权码，比如QQ邮箱、163邮箱都需要生成授权码作为SMTP认证密码。
可以在app/Config/Email.php中配置基础参数，也可以动态设置，以下是标准配置示例：
<?php
namespace Config;
use CodeIgniterConfigBaseConfig;
class Email extends BaseConfig
{
// 邮件协议，使用SMTP
public $protocol = 'smtp';
// SMTP主机地址，比如QQ邮箱是smtp.qq.com
public $SMTPHost = 'smtp.qq.com';
// SMTP端口，常见25、465、587
public $SMTPPort = 465;
// SMTP用户名，即邮箱账号
public $SMTPUser = '123456@qq.com';
// SMTP密码，这里是邮箱的SMTP授权码
public $SMTPPass = 'xxxxxx授权码xxxxxx';
// 加密方式，465端口对应ssl，587端口对应tls
public $SMTPCrypto = 'ssl';
// 发件人邮箱
public $fromEmail = '123456@qq.com';
// 发件人名称
public $fromName = '测试站点';
// 是否启用SMTP调试，调试时可设为true
public $SMTPDebug = 0;
}
2. 端口与加密方式不匹配
SMTP服务商的端口和加密方式需要对应，否则会出现连接失败的问题。常见的组合如下：
| 端口 | 加密方式 | 说明 |
|---|---|---|
| 25 | 无或tls | 部分服务器会禁用该端口，不建议优先使用 |
| 465 | ssl | SSL加密端口，兼容性较好 |
| 587 | tls | TLS加密端口，很多服务商推荐使用该端口 |
3. PHP扩展缺失
CodeIgniter 4的SMTP邮件发送依赖PHP的openssl扩展，如果服务器没有开启该扩展，会导致加密连接失败。可以通过以下代码检查扩展是否开启：
<?php
// 检查openssl扩展是否加载
if (extension_loaded('openssl')) {
echo 'openssl扩展已开启';
} else {
echo 'openssl扩展未开启，需要到php.ini中开启';
}
4. 服务器环境限制
部分云服务器默认禁用SMTP相关端口，比如阿里云、腾讯云服务器需要到安全组规则中放行对应的SMTP端口，否则会出现连接超时的问题。同时如果服务器安装了防火墙，也需要同步放行对应端口。
完整发送代码示例
配置完成后，可以使用以下代码发送邮件：
<?php
namespace AppControllers;
use CodeIgniterController;
use CodeIgniterEmailEmail;
class MailController extends Controller
{
public function send()
{
$email = new Email();
// 设置收件人
$email->setTo('test@ipipp.com');
// 设置邮件主题
$email->setSubject('测试邮件');
// 设置邮件内容
$email->setMessage('这是一封CodeIgniter 4发送的SMTP测试邮件');
// 发送邮件并判断结果
if ($email->send()) {
echo '邮件发送成功';
} else {
// 输出调试信息，排查错误
echo $email->printDebugger();
}
}
}
调试技巧
如果发送失败，可以将app/Config/Email.php中的SMTPDebug设为1或者2，再调用printDebugger()方法，会输出详细的SMTP交互日志，根据日志中的错误提示可以快速定位问题，比如认证失败会提示Authentication failed，连接失败会提示Connection refused。
注意：测试时不要频繁发送邮件，否则可能会被SMTP服务商判定为垃圾邮件发送者，导致账号被限制发送权限。
CodeIgniter_4SMTP邮件发送邮件配置修改时间：2026-07-19 03:48:23