PHP生成HTML邮件链接在客户端异常的排查求助

问题概述 #

PHP生成HTML邮件并发送，动态链接在文本文件中显示正常，但Apple Mail和Gmail网页端接收后链接损坏：

• 预期链接：http://test.domain/wp-admin/admin.php?page=test-plugin&action=edit&entry_id=48
• Apple Mail渲染后：http://test.domain/wp-admin/admin.php?page=test-plugin&action%EF%BF%BDit&entry_id1
• Gmail渲染后：http://wordpress.local/wp-admin/admi= n.php?page=3Dtest-plugin&action%EF%BF%BDit&entry_idH"

异常细节：Apple Mail查看原始源码时链接正常，但渲染后异常；Gmail的原始源码和显示均混乱。已确认未对HTML内容做Base64编码，相关Content-Type配置如下：

• 邮件头：Content-Type: multipart/related; boundary="inline717a95a1da99481c8ff625418eeedf70"; charset=UTF-8;
• 内容段：Content-Type: text/html; charset=UTF-8、Content-Transfer-Encoding: Quoted-Printable
• HTML内部：<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

链接生成已通过mb_convert_encoding(get_site_url().'/wp-admin/admin.php?page=test-plugin&action=edit&entry_id='.$entry->id, "UTF-8");处理。

排查方向 #

• Quoted-Printable编码逻辑检查：邮件内容采用Quoted-Printable编码，该编码会将特殊字符转为=XX格式，且要求每行不超过76字符。若编码时未正确处理URL中的=（如entry_id=48的=），或换行截断位置错误（如Gmail中admi=的换行），会导致解码异常。检查PHP发送邮件时的编码实现：若手动处理编码，需确保符合RFC 2045规范；若使用邮件库（如PHPMailer），确认编码参数配置正确。
• HTML实体转义重复处理排查：链接中的&是HTML实体，若生成过程中对URL进行多次转义，或Quoted-Printable编码与HTML转义冲突，会出现&这类二次转义（如Gmail中的情况）。检查链接生成逻辑，确保仅做一次正确的HTML实体转义，或在编码前保证内容为原始正确格式。
• 字符编码一致性验证：尽管配置了UTF-8，仍需检查PHP环境默认字符集（mb_internal_encoding、default_charset）是否与邮件UTF-8一致。若PHP输出内容为其他编码，转UTF-8时可能产生无法识别的字节（%EF%BF%BD为替换字符，说明存在无效字节）。可直接输出链接原始字节，排查是否含异常字符。
• 邮件库配置检查：若使用第三方邮件库（如PHPMailer、SwiftMailer），确认是否开启自动编码转换，或是否存在导致URL错误处理的配置项。部分库会自动对长URL换行，若处理不当会截断URL参数。
• URL参数拼接校验：检查$entry->id的原始值，确认是否包含不可见字符（控制字符、全角字符等）。若$entry->id为48但附带不可见字符，拼接后会破坏URL参数结构。可通过var_dump($entry->id)查看原始值，或用urlencode()处理参数值（即使是数字，也能避免潜在异常）。
• 多部分邮件边界冲突排查：邮件采用multipart/related格式，检查边界字符串是否在邮件内容中意外出现，导致内容被错误分割。若边界字符串与URL字符重复，会破坏邮件结构，引发客户端解析错误。

内容的提问来源于stack exchange，提问作者whiteatom