本文详解如何在 TYPO3 自定义扩展中安全、可靠地调用内置邮件 API 发送邮件，涵盖依赖注入、配置验证、MIME 地址构建、HTML/纯文本双格式支持、附件处理及常见错误（如 Undefined index: TYPO3_CONF_VARS）的根源与修复方案。
本文详解如何在 typo3 自定义扩展中安全、可靠地调用内置邮件 api 发送邮件，涵盖依赖注入、配置验证、mime 地址构建、html/纯文本双格式支持、附件处理及常见错误（如 `undefined index: typo3_conf_vars`）的根源与修复方案。
在 TYPO3 扩展开发中，通过官方邮件 API 发送调查结果、表单数据或通知邮件是高频需求。但直接在非 TYPO3 上下文（如独立 PHP 脚本或未初始化的 CLI 环境）中硬编码调用 \TYPO3\CMS\Core\Mail\MailMessage，极易触发 Notice: Undefined index: TYPO3_CONF_VARS 等致命错误——其根本原因在于：MailMessage 严重依赖 TYPO3 全局配置（$GLOBALS['TYPO3_CONF_VARS']）和已启动的 DI 容器，而该配置仅在 TYPO3 核心完整引导后才可用。
因此，正确的做法是严格遵循 TYPO3 的生命周期与架构规范，在受控上下文中发送邮件。以下是推荐的、生产就绪的实现方式：
✅ 正确姿势：在控制器或服务类中使用依赖注入
以 Extbase 控制器为例（适用于 TYPO3 v11+ / v12），避免手动 require autoload.php 或全局 makeInstance()：
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Controller;
use Psr\Http\Message\ResponseInterface;
use Symfony\Component\Mime\Address;
use TYPO3\CMS\Core\Mail\MailMessage;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
class SurveyController extends ActionController
{
public function submitAction(): ResponseInterface
{
// 1. 获取 JSON 数据（示例）
$jsonInput = $this->request->getArgument('surveyData');
$surveyData = json_decode($jsonInput, true) ?: [];
// 2. 创建邮件实例（推荐：通过构造函数注入或 makeInstance）
$mail = GeneralUtility::makeInstance(MailMessage::class);
// 3. 设置发件人（必须为已配置的系统邮箱，见下方注意事项）
$mail->from(new Address('noreply@my-site.com', 'My Site'));
// 4. 设置收件人（支持多个）
$mail->to(
new Address('admin@my-site.com', 'Admin Team'),
new Address('reports@my-site.com') // 无名称时可省略第二参数
);
// 5. 设置主题与内容
$mail->subject('[Survey Submission] ' . date('Y-m-d H:i'));
$mail->text($this->generatePlainTextBody($surveyData));
$mail->html($this->generateHtmlBody($surveyData));
// 6. （可选）添加附件（路径需绝对且存在）
$attachmentPath = PATH_site . 'uploads/tx_myextension/survey-' . date('YmdHis') . '.json';
file_put_contents($attachmentPath, json_encode($surveyData, JSON_PRETTY_PRINT));
if (file_exists($attachmentPath)) {
$mail->attachFromPath($attachmentPath, 'survey-data.json', 'application/json');
}
// 7. 发送并检查结果
try {
$mail->send();
$this->addFlashMessage('Survey submitted and email sent successfully.', '', \TYPO3\CMS\Core\Messaging\AbstractMessage::OK);
} catch (\Exception $e) {
$this->addFlashMessage('Failed to send email: ' . $e->getMessage(), '', \TYPO3\CMS\Core\Messaging\AbstractMessage::ERROR);
// 记录错误到日志
\TYPO3\CMS\Core\Utility\GeneralUtility::devLog(
'Email sending failed in SurveyController->submitAction',
'my_extension',
3,
['exception' => $e->__toString()]
);
}
return $this->htmlResponse();
}
private function generatePlainTextBody(array $data): string
{
$lines = ["Survey Submission (Plain Text)\n", '---'];
foreach ($data as $key => $value) {
$lines[] = sprintf('%s: %s', ucfirst($key), is_array($value) ? json_encode($value) : $value);
}
return implode("\n", $lines);
}
private function generateHtmlBody(array $data): string
{
$rows = [];
foreach ($data as $key => $value) {
$escapedKey = htmlspecialchars($key, ENT_QUOTES, 'UTF-8');
$escapedValue = htmlspecialchars(is_array($value) ? json_encode($value) : $value, ENT_QUOTES, 'UTF-8');
$rows[] = "<tr><td><strong>{$escapedKey}:</strong></td><td>{$escapedValue}</td></tr>";
}
return <<<HTML
<h2>Survey Submission</h2>
<table border="1" style="border-collapse: collapse;">
<tbody>
{$rows ? implode('', $rows) : '<tr><td colspan="2">No data received.</td></tr>'}
</tbody>
</table>
HTML;
}
}⚠️ 关键注意事项与最佳实践
禁止脱离 TYPO3 上下文调用：不要在 ext_localconf.php、ext_tables.php 或独立脚本中直接 new MailMessage()。此类场景应改用 Symfony Mailer（需自行配置传输器），或通过 TYPO3 的 Scheduler 任务异步执行。
发件人地址必须合法：from() 中的邮箱需在 TYPO3 后台 “设置 > 配置 > 邮件” 中配置为 SYS/setFromEmail 或 MAIL/fromAddress，否则可能被拒信或标记为垃圾邮件。
-
启用并验证邮件配置：确保 LocalConfiguration.php 中包含有效 SMTP 或 sendmail 配置：
'MAIL' => [ 'transport' => 'smtp', 'transport_smtp_server' => 'smtp.gmail.com:587', 'transport_smtp_encrypt' => 'tls', 'transport_smtp_username' => 'your-app@gmail.com', 'transport_smtp_password' => 'your-app-specific-password', ], 附件路径必须绝对且可读：attachFromPath() 接收服务器绝对路径（如 PATH_site . 'file.pdf'），相对路径将失败。
错误处理不可省略：始终包裹 send() 在 try/catch 中，并记录详细错误（含堆栈），便于排查 SMTP 认证失败、DNS 解析超时等底层问题。
✅ 总结
TYPO3 的邮件发送不是简单的函数调用，而是深度集成于其核心配置与依赖注入体系中的功能。成功的关键在于：在正确的上下文（如控制器、命令行命令、调度任务）中，通过标准 DI 方式获取 MailMessage 实例，并严格遵守 TYPO3 的配置约定与安全规范。跳过这些环节，强行“直连”邮件类，必然导致 TYPO3_CONF_VARS 缺失等运行时错误。遵循本文实践，即可稳定、可维护地在扩展中实现邮件自动化。
