PHP stream_context 怎么为单次 HTTP 请求设置选项

给单次 HTTP 请求设置选项，最稳妥的写法是：把 method、header、timeout 等配置放进 ['http' => [...]]，用 stream_context_create() 创建上下文资源，再把它传给 file_get_contents() 的第三个参数。这个 context 只影响当前调用，不需要修改 php.ini 或全局默认上下文。

官方文档：https://www.php.net/manual/en/function.stream-context-create.php

下面从一次“请求头和超时都没有生效”的故障现场开始，按影响面、触发条件、根因、修复和防复发来讲清 stream context 的正确用法。

影响面：接口偶发卡住，鉴权头也没有送到

一个定时脚本用 file_get_contents() 请求内部 JSON 接口。平时响应很快，接口变慢时，脚本会一直等到 PHP 默认套接字超时；加入自定义请求头后，服务端仍返回 401。为了止损，有人把 default_socket_timeout 调小，但这会影响同一进程里的其他流操作，范围明显过大。

排查时出现了三个关键现象：

• 单独打印选项数组，Authorization 和 timeout 都存在；
• 请求代码仍是 file_get_contents($url)，没有传 context；
• 另一次尝试把 timeout 直接放在数组顶层，而不是放进 http wrapper。

问题不在 HTTP 服务，也不在 header 字符串本身，而是选项没有真正绑定到这一次请求。

根因：配置层级和传参位置都必须正确

PHP 官方规定，stream context 选项必须使用 $options['wrapper']['option'] = $value 的两层结构。对 http:// 和 https:// 请求，HTTP 方法、请求头和读取超时都放在 http wrapper 下；HTTPS 的证书校验等传输层配置才放在 ssl wrapper 下。

最小可用写法如下：

 [
        // 这些选项只绑定本次 HTTP 请求
        'method' => 'GET',
        'header' => [
            'Accept: application/json',
            'Authorization: Bearer example-token',
        ],
        // timeout 是读取超时，单位为秒，可使用浮点数
        'timeout' => 3.5,
    ],
];

$context = stream_context_create($options);

// 第二个参数表示不搜索 include_path，第三个参数才是 context
$body = file_get_contents($url, false, $context);

if ($body === false) {
    throw new RuntimeException('HTTP 请求未取得响应正文');
}

echo $body;

这里有两个容易被忽略的细节。第一，header 可以传数组，也可以传用 \r\n 分隔的字符串；数组更不容易漏分隔符。第二，file_get_contents() 失败时返回 false，但合法响应也可能是空字符串，因此必须使用 === false，不能写成 if (!$body)。

修复动作：把一次 JSON POST 的配置收在 context 里

需要发送 JSON 时，仍然使用相同结构，只是增加 content 并明确 Content-Type。content 是请求头之后发送的正文，常用于 POST 或 PUT。

 'daily-report', 'priority' => 2],
    JSON_THROW_ON_ERROR
);

$context = stream_context_create([
    'http' => [
        // 当前调用发送 JSON POST，不改变其他请求
        'method' => 'POST',
        'header' => [
            'Accept: application/json',
            'Content-Type: application/json',
            'Connection: close',
        ],
        'content' => $payload,
        'timeout' => 5.0,
        // 允许读取 4xx/5xx 的正文，业务仍要检查状态码
        'ignore_errors' => true,
    ],
]);

$body = file_get_contents($url, false, $context);

if ($body === false) {
    throw new RuntimeException('连接、传输或读取阶段失败');
}

$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
var_dump($data);

ignore_errors 的含义经常被误解。它不是“忽略所有错误”，而是在 HTTP 返回失败状态码时仍抓取响应正文。DNS 失败、连接失败、TLS 失败或读取失败仍可能让函数返回 false 并产生警告。若接口把错误详情放在 400 或 500 正文中，这个选项很有用；但业务不能因为拿到正文就把请求当成成功。

触发条件：为什么只在某些接口上暴露

配置错误之所以容易潜伏，是因为默认行为在简单接口上看起来也能工作。HTTP 方法默认是 GET；未显式设置 timeout 时使用 default_socket_timeout；服务端不要求鉴权或特殊 Accept 头时，请求头缺失也不会立即失败。只有遇到慢响应、鉴权接口、JSON POST 或错误正文时，问题才集中暴露。

如果启用自动重定向，官方文档不建议手工固定 Host 请求头，因为 header 选项会在跟随 Location 时继续覆盖对应值，可能把原主机名带到新地址。对敏感鉴权头也应谨慎：跨主机重定向是否允许携带凭据，最好由业务代码显式判断，而不是依赖自动跳转。

四个最常见的不生效原因

把选项放在顶层

['timeout' => 3] 不符合 wrapper/option 结构；HTTP 请求应写成 ['http' => ['timeout' => 3]]。数组能创建不代表其中的选项会被 HTTP wrapper 识别。

创建了 context，却没有传给请求

stream_context_create() 只是返回资源，不会自动改变后续所有 HTTP 调用。必须将它传给 file_get_contents($url, false, $context)、fopen() 或其他支持 context 的流函数。

用 https 作为 HTTP 选项的 wrapper 名

方法、header、content 和 timeout 对 HTTP 与 HTTPS 传输都放在 http 下。若还要配置证书校验、CA 文件或对端名称，再额外增加 ssl 选项组。把请求头放进 https 组不会得到预期效果。

把 false、空正文和错误状态混为一谈

false 表示流读取失败；空字符串可能是合法空响应；启用 ignore_errors 后，4xx/5xx 也可能返回非空正文。这三种情况必须分开处理。需要状态码时，应读取最近一次 HTTP 响应头，并考虑当前 PHP 版本的接口。

响应状态怎么取，要注意 PHP 8.5 的变化

过去常见的做法是读取局部作用域中的 $http_response_header。PHP 官方文档已经标明，该变量从 PHP 8.5 起弃用，并建议改用 http_get_last_response_headers()。如果项目同时覆盖新旧 PHP，可以封装一个兼容分支：

旧版本的 $http_response_header 在调用 HTTP wrapper 的局部作用域生成，因此封装时不能指望在另一个函数外部自动取得它。更稳妥的方式是让执行请求的函数同时返回正文与响应头，或在可升级的项目中统一使用新的函数接口。

防复发：提交前检查这六项

• 选项是否按 http -> option 两层结构组织；
• context 是否真的传入流函数的 context 参数；
• header 是否使用数组，或正确用 \r\n 分隔；
• timeout 是否被误当成完整请求生命周期超时；
• 是否用 === false 区分失败与合法空正文；
• 启用 ignore_errors 后，是否仍检查 HTTP 状态和业务错误字段。

如果多个调用需要不同策略，应为每次调用创建独立 context，或由一个请求函数按参数创建 context。不要为了一个慢接口修改全局默认上下文，这会让无关请求共享同一组 header、代理或超时设置，后续排查会更困难。

相关问题

stream_context 的 timeout 是连接超时吗？

HTTP context 文档把它定义为读取超时，单位为秒，支持浮点数。它不应被理解为覆盖 DNS、连接、TLS、重定向和读取全过程的统一总时限。

HTTPS 请求为什么仍然写 http 选项组？

HTTP 方法、请求头、正文、重定向和读取超时属于 HTTP wrapper 选项，对 http 与 https 传输都使用 http。证书和 TLS 相关设置另放在 ssl 组。

stream_context_set_option 适合什么时候用？

已有 context 或 stream resource 后需要补充单个选项时可以使用。若一次性设置完整请求，直接在 stream_context_create() 中传入两层数组更清楚。PHP 8.4 起，向 stream_context_set_option() 传整个 options 数组的旧签名已弃用，应使用单项签名或 stream_context_set_options()。

什么时候应该改用 cURL？

简单 GET、POST 和短小响应可继续用 stream context。需要独立的连接超时与总超时、精细 TLS 控制、上传进度、并发请求或完整响应元数据时，cURL 通常更合适。