首页 › 博客 › 文章

WooCommerce 订单邮件:模板定制与到达率保障

WooCommerce 订单邮件:模板定制与到达率保障

结论先行: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()。

实施步骤:按准备 → 步骤 → 验证 → 回滚落地

  1. 在子主题建立 woocommerce/emails/ 与 woocommerce/emails/plain/,只复制需要改的模板,不整目录搬运。
  2. 用 woocommerce_email_*_context、woocommerce_email_order_details 等钩子注入数据,模板里只做输出与转义。
  3. 配置 SMTP 插件或 phpmailer_init,绑定已做 SPF、DKIM、DMARC 的发信域名,禁用「与收件人同域」的伪造 From。
  4. 为订单保存 _order_locale,发送前用 switch_to_locale() 切换,发送后 restore_previous_locale()。
  5. 用 WP-CLI 造测试订单、触发重发、抓邮件头与日志,逐项对照验收表。
  6. 保留 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 建站 服务页也按同一套「订单语言 + 域名认证 + 可重发」口径做上线检查,适合把本文流程直接嵌进交付清单。更多部署侧排障可看 技术栏目首页 里的同类文章。

验证流程:上线前逐项打勾

验证流程:上线前逐项打勾
  1. 静态检查:php -l 跑子主题 functions.php 与所有覆盖模板,wp cache flush 后无 fatal。
  2. 模板检查:HTML 与 plain 各下一单,diff 输出确认新增字段两边都在,无未转义 &、无外链 CSS。
  3. 触发检查:pending→processing→completed 各一次,Action Scheduler 无 failed,后台重发产生新 Message-ID。
  4. 投递检查:Gmail、Outlook、企业网关各收一封「显示原文」,spf=pass、dkim=pass、dmarc=pass,不在垃圾箱。
  5. 语言检查:zh_CN / en_US 订单分别在相反语言后台重发,标题、页脚、日期、货币全跟随订单。
  6. 回滚演练:把 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 项写进发布单,未打勾不允许切生产流量。

需要把这套流程落到外贸站交付?查看 外贸站服务 或 服务页,我们按验收表交付。

参考资料与延伸阅读

WPDaiwei

WPDaiwei-专业Wordpress网站定制开发提供商

需要 WordPress 开发服务?

24 小时内免费出方案与报价,国内国外都接单。

QQ