PHP stream_context_create 怎么设置 TLS 主机校验

PHP 用 stream_context_create() 设置 TLS 主机校验时，核心是把两个检查同时保留：verify_peer 验证证书链是否可信，verify_peer_name 验证证书中的名称是否匹配目标主机。普通域名 URL 通常不必手动写 peer_name，PHP 会根据打开流时的主机名推断；只有按 IP、别名或特殊路由连接，却仍要验证证书里的正式域名时，才需要显式设置 peer_name。

官方文档：https://www.php.net/manual/en/context.ssl.php

我第一次踩坑是把两种校验混在了一起

一次内网接口改成 IP 直连后，连接报了证书名称不匹配。我最初看到不少旧示例直接把 verify_peer_name 关掉，确实能让请求继续，但这等于放弃确认“当前证书是不是发给目标主机”的能力。后来我把连接地址、信任链和期望主机名拆开，配置就清楚了。

PHP 官方文档里，verify_peer 和 verify_peer_name 默认都为 true。前者回答“这张证书能否追溯到受信任 CA”，后者回答“证书里的主机身份是否与期望名称一致”。两项不是二选一，正常生产连接应该同时成立。

普通域名访问保留默认校验就够了

当 URL 使用的域名就是证书对应的域名时，最小配置反而更可靠：明确保留两项校验，需要自定义 CA 时再加 cafile。TLS 选项必须放在 ssl 分组里；HTTPS 的请求方法、请求头等仍放在 http 分组里。

 [
        // 校验证书链，避免接受未知签发者。
        'verify_peer' => true,
        // 校验证书名称，默认会使用 URL 中的 api.example.com。
        'verify_peer_name' => true,
    ],
    'http' => [
        // HTTP 选项与 TLS 选项分开放置。
        'method' => 'GET',
        'timeout' => 10,
    ],
];

$context = stream_context_create($options);
$body = file_get_contents(
    'https://api.example.com/health',
    false,
    $context
);

if ($body === false) {
    // 生产代码应记录受控错误，不要通过关闭 TLS 校验绕过失败。
    throw new RuntimeException('TLS 请求失败');
}

这里没有设置 peer_name，因为 PHP 会根据打开流时使用的主机名推断它。这是域名正常、DNS 路由正常、证书也覆盖该域名时最合适的选择，配置更少，也不容易在换域名后留下旧值。

按 IP 连接时显式写证书对应的 peer_name

如果网络路径要求连接固定 IP，但服务端证书签给 api.example.com，那么连接目标和证书身份就不同。此时应把 peer_name 设为证书应匹配的 DNS 名称，而不是把 verify_peer_name 设为 false。

 [
        // 仍然校验证书链，不能因为按 IP 连接就关闭。
        'verify_peer' => true,
        // 要求证书名称与 peer_name 匹配。
        'verify_peer_name' => true,
        // 这里填写证书对应的正式 DNS 名称，而不是连接 IP。
        'peer_name' => 'api.example.com',
        // 多证书服务通常依赖 SNI 选择正确证书。
        'SNI_enabled' => true,
    ],
]);

$errno = 0;
$error = '';
$socket = stream_socket_client(
    'tls://203.0.113.10:443',
    $errno,
    $error,
    10,
    STREAM_CLIENT_CONNECT,
    $context
);

if ($socket === false) {
    // 错误信息可写入受控日志，避免泄露敏感连接细节。
    throw new RuntimeException("TLS 连接失败：{$errno}");
}

// 用完及时关闭网络资源。
fclose($socket);

203.0.113.10 只是文档示例地址。真实系统中还要确认服务端确实允许这种连接方式；对于 HTTPS，请求层的 Host 头与 TLS 层的 peer_name 属于不同配置，不要只改其中一处就假设虚拟主机一定正确。

私有 CA 应配置 cafile，而不是关闭校验

内网服务使用企业私有 CA 时，我更推荐把私有根证书或完整信任链放进专用 CA 文件，并通过 cafile 指定。cafile 的职责是告诉 PHP 用哪组 CA 认证远端身份；peer_name 仍负责主机名匹配，两者互不替代。

 [
        // 使用由运维维护的私有 CA 文件建立信任链。
        'cafile' => '/etc/myapp/certs/internal-ca.pem',
        'verify_peer' => true,
        'verify_peer_name' => true,
        // 按别名或 IP 连接时，显式声明证书应覆盖的名称。
        'peer_name' => 'service.internal.example',
    ],
]);

我不建议把 allow_self_signed 当成“内网证书开关”。官方文档说明它需要配合 verify_peer；即使允许自签名，仍需明确你信任什么、名称是否匹配以及证书如何轮换。把私有 CA 纳入可管理的信任文件，通常比广泛接受自签名证书更容易审计。

peer_fingerprint 是额外约束，不是通用替代品

peer_fingerprint 可以在远端证书摘要不匹配时终止连接，适合少量、受控且有明确证书轮换流程的场景。但证书更新会改变指纹，客户端配置必须同步更新；如果没有双指纹过渡或发布机制，正常轮换也可能造成故障。

对大多数公开 HTTPS 服务，系统 CA 信任链加主机名校验更合适。对企业内网，私有 CA 加主机名校验通常更易维护。只有确实需要固定特定证书，并能承担轮换成本时，才考虑在现有验证基础上增加指纹约束。

几种方案怎么选

不适合直接照搬的配置

测试环境里把 verify_peer 和 verify_peer_name 都设为 false，虽然能快速判断问题是否与证书相关，却不应进入生产配置。它既不验证签发链，也不核对主机身份，任何能介入连接的人都可能提供另一张证书。

同样，不要把错误主机名硬塞进 peer_name 来迁就现有证书。正确修复应是使用证书实际覆盖的正式域名、补齐 DNS/路由配置，或重新签发包含目标名称的证书。

常见问题

peer_name 不设置会怎样？

PHP 会根据打开流时使用的主机名推断。普通 HTTPS 域名访问通常不需要手动填写。

verify_peer_name 默认是 true 吗？

是。PHP 官方 SSL context 文档列出的默认值为 true；除非明确理解风险，否则不要关闭。

cafile 和 peer_name 有什么区别？

cafile 提供用于验证证书链的受信任 CA，peer_name 指定证书应匹配的主机名称。一个解决“谁签发”，另一个解决“签给谁”。

allow_self_signed 能替代 cafile 吗？

不能简单等同。允许自签名并没有替你定义可靠的信任和轮换机制；受控内网更适合维护明确的私有 CA 文件并保留主机名校验。