PHP quoted_printable_decode 为什么不会自动转换字符集

PHP quoted_printable_decode 只把 quoted-printable 传输编码还原为字节串，不会识别邮件里的 charset，也不会自动把结果转成 UTF-8。解码后仍乱码时，应保留该 MIME 文本部分的字符集声明，再按已知字符集转换；反复调用同一个解码函数通常解决不了这个问题。

官方文档：https://www.php.net/manual/en/function.quoted-printable-decode.php

先保留正文的字节与字符集声明

处理邮件正文预览时，我会先问输入处于哪个阶段：它是完整邮件、一个 MIME 部分，还是邮件库已经解码过的文本？本文从已经分离出的单个文本部分开始，传入的正文仍是 quoted-printable，charset 已从该部分的元数据取得。完整 MIME 拆分、附件和邮件头不在此例范围内。

需要一起保存的资产是原始正文、传输编码声明和 charset 声明。Content-Transfer-Encoding 描述字节如何在传输时表示；Content-Type 的 charset 描述文本字节采用的字符编码。丢掉后者，再去猜前者的结果，容易把可恢复的问题变成不可追溯的乱码。

还原出字节，不等于已经得到 UTF-8

例如，明确声明 ISO-8859-1 的文本部分里，caf=E9 解码得到末尾字节 E9。它在该字符集下表示 é；UTF-8 的同一字符则使用 C3 A9 两个字节。所以把解码结果直接放入 UTF-8 页面，不能指望页面替你完成字符集转换。

这是根据编码定义解释的示例，不是本文运行得到的日志。我的建议是把变量也按职责命名：encodedBody 保存传输内容，decodedBytes 保存还原字节，utf8 保存转换结果，避免三个阶段都叫 content。

使用明确来源编码转换，拒绝未知配置

下面的 PHP 8 示例需要 mbstring 扩展。为便于交接，只允许 UTF-8 和 ISO-8859-1 两种已明确支持的字符集，限制单部分传输正文为 64 KiB。这个上限是示例业务策略，并非内置函数限制。原始 charset 若使用别名，应由上游在允许列表内显式规范化，不能悄悄猜测。

 65536) {
        throw new LengthException('文本部分超过示例允许大小');
    }
    if (!extension_loaded('mbstring')) {
        throw new RuntimeException('需要启用mbstring扩展');
    }

    // 显式允许列表，不从未知charset自动退回默认编码。
    $allowed = ['UTF-8' => 'UTF-8', 'ISO-8859-1' => 'ISO-8859-1'];
    $key = strtoupper(trim($charset));
    if (!isset($allowed[$key])) {
        throw new InvalidArgumentException('未支持的源字符集');
    }
    $source = $allowed[$key];
    $decodedBytes = quoted_printable_decode($encodedBody);

    // 格式合法不等于声明可信，但可阻止明显不符合该编码的字节继续处理。
    if (!mb_check_encoding($decodedBytes, $source)) {
        throw new UnexpectedValueException('解码字节不符合源字符集');
    }
    $utf8 = mb_convert_encoding($decodedBytes, 'UTF-8', $source);
    if (!is_string($utf8)) {
        throw new RuntimeException('字符集转换失败');
    }
    return $utf8;
}

try {
    // 字符集来自本例明确约定，不对任意邮件猜编码。
    $utf8 = decodeTextPart('caf=E9 ', 'ISO-8859-1');
    // 按纯文本显示在HTML文本节点中，而不是渲染邮件HTML。
    echo htmlspecialchars($utf8, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
} catch (Throwable $e) {
    // 示例仅输出固定错误提示，避免把原始邮件内容泄露给页面。
    if (PHP_SAPI !== 'cli') {
        http_response_code(422);
    }
    echo '文本部分无法按指定规则转换';
}

代码中的小于号与大于号是示例字符串的一部分；正确转换后仍应作为文本显示。示例没有写文件、访问网络或修改全局编码设置，本文也没有执行它。quoted_printable_decode 返回字符串不表示输入的所有传输语法都符合严格规范，不能把本函数当作严格 MIME 验证器。

把显示权限与解码权限分开

对我来说，最容易忽略的是把“已经解码”理解成“可以直接渲染”。邮件文本即使已经成为合法 UTF-8，仍可能包含 HTML 特殊字符。本文只提供纯文本预览，因此使用 htmlspecialchars 并明确 UTF-8；不要把这段写法搬进脚本、样式或任意 URL 上下文后宣称同样安全。

若实际需求是保留邮件中的富文本样式，需要另行设计 HTML 清理和隔离显示方案。字符集转换不承担这些责任。这里只解决还原文本和按文本输出，不展开富文本渲染。

失败时留住原文，避免再次盲目解码

建议记录处理阶段、声明 charset、采用的规范化编码名、输入长度和固定错误类别。原文留存在具备访问控制的存储中，普通错误日志不写完整邮件。未知字符集、缺失声明或明显异常字节应进入明确的失败分支，由上游补全信息后重试，不能每次换一个编码“直到看起来正常”。

同一部分已经经过 quoted-printable 解码后，不要无条件再次解码：原文中本来要保留的等号编码形式可能被第二次改变。上游接口应明确返回的是原始传输内容、解码字节还是最终 UTF-8，回退时从保留的原始正文开始。

相关疑问

mb_check_encoding 返回 true 就能证明字符集猜对了吗？不能。它判断字节是否符合指定编码，而不是证明文本作者采用该字符集；某些不同解释可能都合法。

结果已经是 UTF-8 还要再转吗？若接口契约已经保证完成转换，应直接使用该结果并按输出上下文处理。不要再次把它当成旧编码，转换职责应由一个明确的组件承担。

这能直接处理邮件标题吗？不能。本文输入是单个正文文本部分，不是邮件头编码词，也不是整封邮件。应选用对应解析能力，不能把所有带等号的内容都交给同一个函数。

我的取舍是保留原始字节、显式传递 charset、让解码与显示各自负责。这样乱码出现时可以找到出错的层次，也能从原始输入恢复。

参考：quoted_printable_decode；mb_convert_encoding；mb_check_encoding；htmlspecialchars。