
文章目录
结论先行:WooCommerce 订单邮件应先在子主题覆盖模板,再用钩子控制数据,最后把发送交给已验证域名的 SMTP;多语言按订单语言而非后台语言渲染。判断做对的标准是:测试订单、重发、退款、多语言切换都能收到且内容一致,SPF、DKIM、DMARC 全部通过,日志可追踪,回滚不丢订单。
准备:确认 2026 年环境、备份与验收口径
2026 年主流生产环境仍是 WordPress 6.x 系列配合 WooCommerce 9.x/10.x;WooCommerce 自 8.x 起默认启用 HPOS 高性能订单存储,9.x 以后大量新站点不再依赖 postmeta 读取订单。邮件模板本身仍兼容经典 PHP 模板覆盖,但订单对象应统一使用 WC_Order 与 wc_get_order(),不要直接写 get_post_meta($order_id, ...)。本文所有路径以 Linux 服务器、WP-CLI 可访问为前提。
动手前先做可回滚备份。站点负责人若还没有固定备份策略,可先对照 2026 如何备份 WordPress:服务商决策与验收 把数据库、上传目录与代码快照纳入同一窗口,邮件改造涉及模板、选项表和 wp_mail 拦截,单备份数据库不够。
# 1) 记录版本与邮件配置
wp core version
wp plugin list --status=active | grep -E 'woocommerce|wpml|polylang|smtp|mail'
wp option get woocommerce_email_from_name
wp option get woocommerce_email_from_address
wp option get woocommerce_email_base_color
# 2) 建本次变更目录并备份
SITE=/var/www/example.com
mkdir -p "$SITE/wp-content/email-change-2026"
wp db export "$SITE/wp-content/email-change-2026/db-before.sql"
tar -czf "$SITE/wp-content/email-change-2026/themes-before.tgz" -C "$SITE/wp-content" themes
wp theme status
准备一个子主题。若当前主题已是子主题,直接复用;不要改 wp-content/plugins/woocommerce/templates/,插件升级会覆盖。标准覆盖路径是 wp-content/themes/your-child/woocommerce/emails/...,WooCommerce 通过 wc_get_template() 按「主题/woocommerce → 插件/templates」优先级查找,函数文档见 developer.wordpress.org 对模板层级与子主题加载的说明。
验收口径提前写死,避免上线后凭感觉判断:一是收件箱到达,不是仅看后台「已发送」;二是 Message-ID、From、Reply-To 与订单号可关联;三是 HTML 与纯文本两版都不乱码;四是 zh_CN、en_US 各下一单,标题、商品名、日期格式、货币格式跟随订单语言;五是失败时能切回原模板与原生 wp_mail()。
实施步骤:按准备 → 步骤 → 验证 → 回滚落地
- 在子主题建立
woocommerce/emails/与woocommerce/emails/plain/,只复制需要改的模板,不整目录搬运。 - 用
woocommerce_email_*_context、woocommerce_email_order_details等钩子注入数据,模板里只做输出与转义。 - 配置 SMTP 插件或
phpmailer_init,绑定已做 SPF、DKIM、DMARC 的发信域名,禁用「与收件人同域」的伪造 From。 - 为订单保存
_order_locale,发送前用switch_to_locale()切换,发送后restore_previous_locale()。 - 用 WP-CLI 造测试订单、触发重发、抓邮件头与日志,逐项对照验收表。
- 保留
email-change-2026快照与开关常量,异常时 5 分钟内回退模板、SMTP 与语言钩子。
邮件模板的结构与覆盖方式
先拆清三层结构
WooCommerce 订单邮件不是单个文件,而是「外壳 + 内容模板 + 数据上下文」三层。emails/email-header.php 负责 <!DOCTYPE html>、内联样式、Logo 与 $email_heading;emails/email-footer.php 负责版权与 apply_filters('woocommerce_email_footer_text');中间由 customer-processing-order.php、customer-completed-order.php、customer-refunded-order.php、admin-new-order.php 等调用 email-order-details.php、email-order-items.php、email-addresses.php。纯文本版在 emails/plain/ 下同名对应,别只改 HTML 版。
邮件类位于 includes/emails/class-wc-email-*.php,每个类有 $id、$title、$template_html、$template_plain、trigger($order_id) 与 get_content_html()。覆盖时改的是视图,不是类;要改收件人、标题、条件发送,用 woocommerce_email_recipient_{$id}、woocommerce_email_subject_{$id}、woocommerce_email_enabled_{$id} 这类过滤器。
| 需求 | 正确落点 | 文件路径 / 钩子 | 不要做 |
|---|---|---|---|
| 换 Logo、配色、页脚 | 外壳模板 + 设置 | woocommerce/emails/email-header.php、email-footer.php | 改插件目录 |
| 订单表加交付时间 | 内容模板 + 上下文 | woocommerce/emails/email-order-details.php、woocommerce_email_order_details | 在模板里查数据库 |
| 改标题 / 收件人 | 邮件类过滤器 | woocommerce_email_subject_customer_processing_order | 直接改 class-wc-email-*.php |
| 纯文本同步 | plain 模板 | woocommerce/emails/plain/email-order-details.php | 只发 HTML |
可复制的最小覆盖代码
下面示例在子主题 functions.php 里给「处理中订单」邮件注入预计发货日,并同时覆盖 HTML 与纯文本输出。所有输出到页面的变量都做转义,<、>、& 在代码块里已按 HTML 源码转义。
<?php
// wp-content/themes/your-child/functions.php
add_filter('woocommerce_email_order_details', 'runok_add_dispatch_note', 20, 4);
function runok_add_dispatch_note($order, $sent_to_admin, $plain_text, $email) {
if ($email->id !== 'customer_processing_order') {
return;
}
$dispatch = $order->get_meta('_dispatch_date', true);
if (! $dispatch) {
$dispatch = wp_date('Y-m-d', strtotime('+2 weekdays', $order->get_date_created()->getTimestamp()));
$order->update_meta_data('_dispatch_date', $dispatch);
$order->save();
}
$label = __('Estimated dispatch', 'your-child');
if ($plain_text) {
echo "n" . $label . ': ' . esc_html($dispatch) . "n";
} else {
echo '<p style="margin:16px 0;color:#333;">'
. esc_html($label) . ': <strong>' . esc_html($dispatch) . '</strong></p>';
}
}
add_filter('woocommerce_email_subject_customer_processing_order', 'runok_processing_subject', 10, 2);
function runok_processing_subject($subject, $order) {
return sprintf(__('Order %s received / payment confirmed', 'your-child'), $order->get_order_number());
}
若必须改表格结构,复制插件原文件到子主题再改,命令如下。复制后先 diff 一次,确认只改了目标行;2026 年 WooCommerce 模板头部仍带 @version,升级后要用新版本重新 diff,别长期锁死旧模板。
获取报价
邮箱 + 需求 + 预算区间,24 小时内回复报价。
SITE=/var/www/example.com
CHILD="$SITE/wp-content/themes/your-child"
SRC="$SITE/wp-content/plugins/woocommerce/templates/emails"
mkdir -p "$CHILD/woocommerce/emails/plain"
cp "$SRC/email-header.php" "$CHILD/woocommerce/emails/"
cp "$SRC/email-footer.php" "$CHILD/woocommerce/emails/"
cp "$SRC/email-order-details.php" "$CHILD/woocommerce/emails/"
cp "$SRC/plain/email-order-details.php" "$CHILD/woocommerce/emails/plain/"
diff -u "$SRC/email-order-details.php" "$CHILD/woocommerce/emails/email-order-details.php" || true
wp cache flush
常见坑:一,把 woocommerce/ 目录放到了父主题,父主题更新即丢;二,模板里调用 get_post_meta(),HPOS 下取不到自定义字段;三,用 esc_html() 包整段 HTML 导致标签被显示成文本,应逐字段转义;四,忘记 plain 版,部分企业网关只收 text/plain;五,内联 CSS 写了外部 class,Gmail、Outlook 会丢样式。
触发时机与重发
状态机与真实触发点
订单邮件由状态迁移触发,不是由「支付按钮点击」触发。woocommerce_order_status_pending_to_processing 对应 WC_Email_Customer_Processing_Order,processing_to_completed 对应 WC_Email_Customer_Completed_Order,processing_to_refunded 对应退款邮件;管理员新订单挂在 woocommerce_order_status_pending_to_processing 等同组钩子上,由 WC_Emails::init() 注册。2026 年 HPOS 站点应监听 woocommerce_order_status_changed 做自定义旁路,并用 $order->get_status() 判断,不要依赖 transition_post_status。
异步队列要注意:WooCommerce 9.x/10.x 默认把邮件交给 Action Scheduler,后台看到「订单已付款」不等于邮件已出队成功。排查时先看 wp actionscheduler,再看 SMTP 日志。
# 查看待执行/失败任务
wp action-scheduler list --status=pending --per-page=20
wp action-scheduler list --status=failed --per-page=20
# 手工触发一次已存在订单的「处理中」邮件(先置为测试收件人)
wp eval '
$id = 12345;
$order = wc_get_order($id);
if (! $order) { WP_CLI::error("order missing"); }
add_filter("woocommerce_email_recipient_customer_processing_order", function(){ return "qa@example.com"; }, 99);
$mailer = WC()->mailer();
$mail = $mailer->emails["WC_Email_Customer_Processing_Order"] ?? null;
if (! $mail) { WP_CLI::error("email class missing"); }
$mail->trigger($id);
WP_CLI::success("triggered #" . $id);
'
# 等价于后台订单详情 → Order actions → Resend processing order
wp eval 'do_action("woocommerce_order_action_resend_processing_order", wc_get_order(12345));'
后台重发路径是 WooCommerce → Orders → 打开订单 → Order actions → Resend … → Update。它调用 woocommerce_order_action_{$action},最终仍是对应邮件类的 trigger(),因此会带上当前模板、当前 SMTP、当前语言钩子。批量重发不要直接循环 trigger() 打生产收件人,先用上面的收件人过滤器导流到 QA 邮箱,确认后再按订单 ID 白名单执行。
验证触发做对了
- 下一笔真实测试单:只收到一次 admin 新订单 + 一次 customer processing,不重复、不缺件。
- 把订单从 processing 改 completed,只收到 completed 邮件;再点 Resend processing,能收到且
Message-ID与首次不同。 wp action-scheduler list --status=failed为空;若有失败,先看woocommerce_email_*_context里是否有致命错误。- 订单备注出现
Processing order email sent to customer类记录,且时间戳与 SMTP 日志相差不超过 2 分钟。
失败回退:若重发导致重复投递,立刻在 WooCommerce → Settings → Emails 临时关闭对应邮件,清空 Action Scheduler 中同 hook 的 pending 任务,再恢复;不要删订单备注,它是审计依据。若自定义钩子抛错,注释 functions.php 中本次新增的 add_filter/add_action 段即可,模板文件保留不影响原生触发。
SMTP 与送达率
为什么不能继续用 PHP mail()
wp_mail() 默认走 PHP mail(),由本机 MTA 直接投递,没有域名签名、没有退信回执、没有队列重试。共享主机 IP 信誉不可控,2026 年 Gmail、Yahoo、Microsoft 对无 DKIM 或 DMARC 不对齐的商业邮件基本直接进垃圾箱。WooCommerce 订单邮件属于交易邮件,但仍受同一套认证规则约束;「后台显示成功」只代表交给 MTA,不代表到达。
推荐用 SMTP 插件(WP Mail SMTP、Post SMTP 等)或 phpmailer_init 绑定事务邮件服务。不要用客户填的联系邮箱当 From:若收件人是 gmail.com 而 From 也是 gmail.com,SPF 必然不对齐。固定使用站点自有域名的 orders@example.com,Reply-To 再指向客服。
<?php
// wp-content/themes/your-child/functions.php,或 mu-plugins/runok-smtp.php
add_action('phpmailer_init', function($phpmailer) {
$phpmailer->isSMTP();
$phpmailer->Host = 'smtp.transactional.example.com';
$phpmailer->Port = 587;
$phpmailer->SMTPSecure = 'tls';
$phpmailer->SMTPAuth = true;
$phpmailer->Username = 'orders-api-key';
$phpmailer->Password = getenv('RUNOK_SMTP_PASS'); // 不放数据库、不进 Git
$phpmailer->setFrom('orders@example.com', 'Example Store');
$phpmailer->addReplyTo('support@example.com', 'Support');
$phpmailer->CharSet = 'UTF-8';
});
add_filter('wp_mail_from', function(){ return 'orders@example.com'; });
add_filter('wp_mail_from_name', function(){ return 'Example Store'; });
密钥放环境变量,Nginx/PHP-FPM 里用 fastcgi_param RUNOK_SMTP_PASS '...'; 或 wp-config.php 前 putenv(),不要写进 wp option。DNS 侧至少三条:example.com TXT "v=spf1 include:smtp.transactional.example.com -all"、服务商给的 selector._domainkey CNAME、_dmarc.example.com TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com; adkim=s; aspf=s",观察 7 天后再把 p 收到 quarantine。
# DNS 与连通性验收
dig +short TXT example.com
dig +short CNAME selector._domainkey.example.com
dig +short TXT _dmarc.example.com
openssl s_client -starttls smtp -connect smtp.transactional.example.com:587 -brief
# 发一封带完整头的测试信,保存 .eml 供核对
wp eval '
add_filter("wp_mail_content_type", function(){ return "text/html"; });
wp_mail("qa@example.com", "SMTP header check 2026", "<p>header check</p>", array("X-Runok-Check: order-mail"));
'
# 在收件箱「显示原文」检查:spf=pass / dkim=pass / dmarc=pass
送达率还要控节奏与内容:同一收件人 1 分钟内不要因状态抖动连发 3 封;标题别堆「Free / Invoice / Urgent」;HTML 里所有图片用绝对 https:// 地址并带 alt;退信地址单独收件并每日看。若站点同时做跨域跳转,发信域名与落地域名的一致性也要一起验,可参照 2026 WordPress域名跳转选型与验收 把跳转链纳入同一轮检查,避免邮件里链接被判为异常重定向。
常见坑与回退:端口 465 被云厂商默认拦截却硬配 ssl,改 587 + tls;插件与 phpmailer_init 同时改 From 造成双重 setFrom(),只保留一处;DMARC 直接上 p=reject 把未对齐的旧通知全丢了,先 p=none。回滚时把 mu-plugins/runok-smtp.php 重命名、停用 SMTP 插件、恢复 wp_mail_from 过滤器,再用 wp mailer test 或上面的 wp eval 确认回到原生通道,同时保留 DNS 记录不删。
多语言邮件
按订单语言,不按当前后台语言
最常见事故是:客户在英文站下单,管理员在中文后台点「Resend」,邮件变成中文。原因是 trigger() 执行时的 locale 取自当前请求,而不是订单。正确做法在结账时把语言写进订单元数据,邮件发送前切换,发送后恢复。WPML 可用 wpml_post_language_details / ICL_LANGUAGE_CODE,Polylang 用 pll_current_language('locale');无多语言插件时直接用 determine_locale() 的结果。
<?php
// 1) 结账时固化订单语言
add_action('woocommerce_checkout_create_order', function($order, $data) {
$order->update_meta_data('_order_locale', determine_locale());
}, 10, 2);
// 2) 所有 WooCommerce 邮件发送前按订单切语言
add_action('woocommerce_email_before_send', function($email, $order = null) {
if (! is_a($order, 'WC_Order')) {
return;
}
$locale = $order->get_meta('_order_locale', true) ?: 'en_US';
if (function_exists('switch_to_locale')) {
switch_to_locale($locale);
load_plugin_textdomain('woocommerce', false, dirname(plugin_basename(WC_PLUGIN_FILE)) . '/i18n/languages');
load_child_theme_textdomain('your-child', get_stylesheet_directory() . '/languages');
}
}, 5, 2);
add_action('woocommerce_email_after_send', function() {
if (function_exists('restore_previous_locale')) {
restore_previous_locale();
}
}, 99);
// 3) 子主题语言包:your-child/languages/zh_CN.mo / en_US.mo
// 生成:wp i18n make-mo languages/zh_CN.po languages/zh_CN.mo
为什么要在 before_send 而不是模板里 switch_to_locale():标题、页脚、WC_Email 的 get_subject() 都在模板渲染之前就完成翻译,模板内切换只能改一半。优先级给 5,确保早于 WooCommerce 自身组装内容;after_send 必须恢复,否则同一请求里后续管理员通知、Action Scheduler 下一个任务会串语言。
验证与回退
- 用
wp eval '$o=wc_get_order(12345); $o->update_meta_data("_order_locale","en_US"); $o->save();'固定语言,再在中文后台重发,收到的仍是英文标题与英文页脚。 - 检查日期与货币:
wp_date()跟随 locale,金额必须用wc_price($value, array('currency' => $order->get_currency())),不要自己拼¥或$。 - 纯文本版同样切语言;
CharSet = 'UTF-8'已在 SMTP 段固定,中文不出现=?gb2312?。 - 若串语言,先注释
woocommerce_email_before_send回调,回到「跟随后台」的原生行为,再排查是否漏了restore_previous_locale();不要直接删_order_locale元数据。
面向海外订单的站点还会把模板、SMTP 与语言一起纳入交付验收,我们的 外贸独立站与 WooCommerce 建站 服务页也按同一套「订单语言 + 域名认证 + 可重发」口径做上线检查,适合把本文流程直接嵌进交付清单。更多部署侧排障可看 技术栏目首页 里的同类文章。
验证流程:上线前逐项打勾

- 静态检查:
php -l跑子主题functions.php与所有覆盖模板,wp cache flush后无 fatal。 - 模板检查:HTML 与 plain 各下一单,diff 输出确认新增字段两边都在,无未转义
&、无外链 CSS。 - 触发检查:pending→processing→completed 各一次,Action Scheduler 无 failed,后台重发产生新
Message-ID。 - 投递检查:Gmail、Outlook、企业网关各收一封「显示原文」,
spf=pass、dkim=pass、dmarc=pass,不在垃圾箱。 - 语言检查:
zh_CN/en_US订单分别在相反语言后台重发,标题、页脚、日期、货币全跟随订单。 - 回滚演练:把
email-change-2026里的 SQL 与themes-before.tgz在预发还原一次,计时并记录命令,生产才允许切流。
| 现象 | 优先定位 | 命令 / 位置 | 回退动作 |
|---|---|---|---|
| 完全没收到 | 队列未执行或 SMTP 认证 | wp action-scheduler list --status=failed、SMTP 插件 Log | 停用自定义 SMTP,回原生 wp_mail() |
| 收到但乱码 | CharSet / plain 模板 | 邮件原文 Content-Type | 恢复原 plain/ 文件 |
| 重复两封 | 钩子与后台重发叠加 | grep -R 'trigger(' your-child mu-plugins | 关闭对应 Email 设置,清 pending |
| 重发变中文 | locale 未随订单 | wp eval 'echo wc_get_order(ID)->get_meta("_order_locale", true);' | 注释 before_send 回调 |
| 进垃圾箱 | From 与 SPF 不对齐 | dig +short TXT example.com | 改回 orders@example.com,DMARC 暂回 p=none |
回滚:5 分钟内恢复可发信状态
回滚顺序固定为「先通道、再钩子、最后模板」,反过来会继续往坏通道里塞信。所有本次新增文件都放在 wp-content/email-change-2026/ 或子主题内,便于按名停用。
SITE=/var/www/example.com
CHILD="$SITE/wp-content/themes/your-child"
BK="$SITE/wp-content/email-change-2026"
# 1) 通道回原生
wp plugin deactivate wp-mail-smtp 2>/dev/null || true
[ -f "$SITE/wp-content/mu-plugins/runok-smtp.php" ] && mv "$SITE/wp-content/mu-plugins/runok-smtp.php" "$BK/runok-smtp.php.off"
# 2) 本次钩子整段移出(建议平时就单独放 mu-plugins/runok-order-mail.php)
[ -f "$SITE/wp-content/mu-plugins/runok-order-mail.php" ] && mv "$SITE/wp-content/mu-plugins/runok-order-mail.php" "$BK/runok-order-mail.php.off"
# 3) 覆盖模板回插件默认
rm -f "$CHILD/woocommerce/emails/email-header.php" "$CHILD/woocommerce/emails/email-footer.php"
rm -f "$CHILD/woocommerce/emails/email-order-details.php" "$CHILD/woocommerce/emails/plain/email-order-details.php"
# 4) 选项级兜底(只在配置被改坏时执行)
wp option update woocommerce_email_from_address 'orders@example.com'
wp option update woocommerce_email_from_name 'Example Store'
wp cache flush
wp action-scheduler list --status=failed --per-page=10
# 5) 极端情况:整包还原预发验证过的快照
# wp db import "$BK/db-before.sql"
# tar -xzf "$BK/themes-before.tgz" -C "$SITE/wp-content"
不要一上来 wp db import:回滚窗口内可能已有新订单,整库还原会丢单。只有代码与选项都恢复后仍发不出,且确认备份窗口之后无真实交易,才走第 5 步。回滚后补发用后台 Order actions 白名单重发,并在订单备注写明「2026 回滚补发」,避免客服二次解释。
常见问题
覆盖模板后升级 WooCommerce 会不会被冲掉?
子主题里的 woocommerce/emails/ 不会被插件升级覆盖,但会「落后于新模板」。每次升级后跑一次 diff -u 插件新模板 子主题模板,把新版 @version 对应的结构变更合并进来,再走一遍 HTML/plain 双验收。
后台点重发会不会重复扣款或重复发货?
不会。重发只调用邮件类 trigger(),不碰支付网关、不改库存、不触发 woocommerce_order_status_changed。风险只在「重复打扰客户」,所以用收件人过滤器先导流 QA,再按白名单补发。
SPF、DKIM 都过了,为什么仍进垃圾箱?
先看 DMARC 对齐与 From 域名,再看内容:外链图片、短链、与落地域名不一致的跳转、同收件人高频重发都会拉低信誉。用「显示原文」确认三项 pass,再把邮件里所有链接改成绝对 https:// 自有域名并降频观察 24 小时。
上线动作清单
- 今天在预发建
email-change-2026快照,跑通wp db export+tar+ 一次真实还原计时。 - 把本文两个代码块分别落为
mu-plugins/runok-order-mail.php与mu-plugins/runok-smtp.php,密钥改getenv(),不进 Git。 - 给
orders@example.com配齐 SPF、DKIM、p=none的 DMARC,收 7 天报表后再收紧。 - 用
zh_CN/en_US各下一单并在相反语言后台重发,保存两份.eml作为交付附件。 - 把「验证流程」6 项写进发布单,未打勾不允许切生产流量。
需要把这套流程落到外贸站交付?查看 外贸站服务 或 服务页,我们按验收表交付。
