Yii框架调用第三方API报错：Header不可含换行或多个头

报错信息 #

yii\base\ErrorException: Header may not contain more than a single header, new line detected in /www/wwwroot/xxx/vendor/yiisoft/yii2/web/Response.php:382

问题场景 #

为第三方API请求添加自定义认证Header，代码如下：

protected function getHeaders($data = [])
{
    ksort($data);
    reset($data);
    $ts = microtime().rand(0, 10000);

    return [
        'login: '.$this->login,
        'ts: '.$ts,
        'sig: '.md5($ts.$this->apiKey),
    ];
}

这段代码在纯PHP环境测试正常，但在Yii应用内触发上述报错，已排查未发现重复Header，仅存在CONTENT_TYPE: application/json; charset=utf-8头。

问题原因 #

1. Header格式错误：Yii的请求/响应组件要求Header使用键值对数组，而你返回的是拼接好的完整Header字符串（包含冒号）。Yii在解析这类字符串时，会将整个内容当作Header值处理，触发非法字符校验错误。
2. 潜在非法字符：microtime()默认返回"msec sec"格式的字符串（含空格），或$this->login/$this->apiKey中存在换行符（\n/\r），这些都会被Yii的Header校验逻辑判定为非法。

解决方案 #

方案1：改用键值对格式定义Header #

这是Yii框架推荐的Header写法，从根源避免格式解析问题：

protected function getHeaders($data = [])
{
    ksort($data);
    reset($data);
    // 使用microtime(true)返回浮点数，避免空格带来的潜在问题
    $ts = microtime(true) . rand(0, 10000);

    return [
        'login' => $this->login,
        'ts' => $ts,
        'sig' => md5($ts . $this->apiKey),
    ];
}

方案2：清理Header值中的非法字符 #

如果因特殊需求必须保留原有格式，需确保Header值中无换行、回车等非法字符：

protected function getHeaders($data = [])
{
    ksort($data);
    reset($data);
    $ts = microtime(true) . rand(0, 10000);
    
    // 过滤换行、回车等非法字符
    $cleanLogin = preg_replace('/[\r\n]/', '', $this->login);
    $cleanApiKey = preg_replace('/[\r\n]/', '', $this->apiKey);

    return [
        'login: ' . $cleanLogin,
        'ts: ' . $ts,
        'sig: ' . md5($ts . $cleanApiKey),
    ];
}

补充说明 #

纯PHP环境下header()函数允许直接传入完整Header字符串，但Yii对Header的格式校验更严格，且推荐使用键值对方式管理Header，既符合框架规范也能避免这类格式错误。

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