邮件模板应放在独立目录如@app/mail/并配置别名，传参需显式兜底防空值，HTML样式须内联且用table布局，调试时启用文件传输或捕获完整异常。
邮件模板该放哪？别往 views/site/ 里硬塞
Yii 的邮件内容本质是视图渲染，但直接复用前台视图路径会出问题：权限控制逻辑混入、布局干扰、路径耦合强。正确做法是单独划出邮件视图目录，比如 @app/mail/（需在配置中注册别名）。
实操建议：
- 在
config/web.php或config/main.php中添加：'aliases' => [ '@mail' => '@app/mail', ], - 创建目录
@app/mail/passwordReset.php，只写纯 HTML +$user、$token这类传入变量，不调用$this->beginPage()等布局方法 - 避免使用
renderPartial()—— 它不处理视图路径别名，要用render()并显式指定路径或别名
怎么传参进邮件模板？compose() 的 view 参数不是万能的
很多人以为 compose()->view('xxx', $params) 就完事了，但实际中常遇到变量未定义、数组键缺失、类型不一致等问题。关键在于 Yii 的 view 渲染机制默认只把数组键作为变量注入，且不做深层合并或默认值兜底。
常见错误现象：Undefined variable: user，即使你传了 ['user' => $model]，也可能因模板里写了 $user->name 而 $model 是 null 导致报错。
实操建议：
- 始终做空值判断：
<?php if ($user && $user->email): ?>= $user->email ?><?php endif; ?> - 不要依赖隐式变量解包；显式传参更可控：
$mailer->compose() ->setTo($to) ->setSubject('重置密码') ->setHtmlBody($this->render('@mail/passwordReset', [ 'user' => $user ?: new User(), 'resetLink' => $link, ])); - 复杂数据建议封装成 DTO 类或简单数组，避免传整个 ActiveRecord 实例（可能触发额外查询或序列化失败）
HTML 邮件样式怎么写才不被 Gmail/QQ邮箱砍掉？
邮件客户端对 CSS 支持极差：外部样式表、<style></style> 块、甚至 class 名都会被过滤。Yii 模板本身不处理内联，得自己动手。
性能与兼容性影响：用 PHP 手动内联 CSS 效率低、易出错；全靠行内 style 又难维护。折中方案是“预编译”+ “有限内联”。
实操建议：
- 禁止使用
<link rel="stylesheet">和<style></style>标签 - 基础样式写成函数封装，比如：
function inlineStyle($props) { return 'style="' . implode('; ', array_map( fn($k, $v) => "$k: $v", array_keys($props), $props )) . '"'; }然后在模板里：<td echo inlinestyle> '#333', 'font-size' => '14px']); ?>> <li>优先用 table 布局（兼容性最强），避免 flex/grid</li> <li>字体用系统安全字体栈：<code>font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; - 临时开启调试：在发送前加
\Yii::$app->mailer->useFileTransport = true;
，邮件会保存为文件，路径在@runtime/mail/，可直接查看 HTML 源码和报错上下文 - 捕获并展开异常：
try { $result = $mailer->send(); } catch (\Exception $e) { \Yii::error($e->getMessage(), 'mail'); \Yii::error($e->getTraceAsString(), 'mail'); throw $e; } - 检查模板路径是否存在——最常被忽略的是大小写问题（Linux 下
PasswordReset.php≠passwordReset.php）
调试邮件模板时 send() 报错却看不到真实原因？
常见错误现象：Swift_TransportException 或静默失败，但日志里只有“Failed to send email”，根本看不出是 SMTP 认证失败、模板路径不存在，还是变量语法错误。
根本原因是 Yii 默认吞掉了底层 SwiftMailer 的详细异常链，尤其在生产环境 YII_DEBUG=false 时更明显。
实操建议：
