Back to Qt.io
Contact Us Blog Download Qt
本页内容

安全套接层（SSL）课程

变更内容Qt Network

Qt 6 的变更，是出于让该框架更高效、更易于使用的有意识努力。

我们力求在每个版本中保持所有公共 API 的二进制和源代码兼容性。但为了使 Qt 成为更优秀的框架，某些变更在所难免。

在本主题中，我们将总结Qt Network 中的这些变更，并提供相应的处理指南。

API 变更

名称歧义的重载

已移除若干名称歧义的重载函数。在QAbstractSocket 及其派生类（QTcpSocket 、QUdpSocket 、QLocalSocket 和QSslSocket ）以及QNetworkReply 中，error() 信号已被 errorOccurred() 取代。如下所示的代码：

connect(socket, qOverload<QAbstractSocket::SocketError>(&QAbstractSocket::error),
        this, &SomeClass::errorSlot);

因此必须修改为：

connect(socket, &QAbstractSocket::errorOccurred, this, &SomeClass::errorSlot);

在QSslSocket 中，该函数返回 TLS 握手过程中遇到的错误列表：

QList<QSslError> sslErrors() const;

已重命名为 sslHandshakeErrors()：

const auto tlsErrors = socket.sslHandshakeErrors();

移除了承载管理

在 Qt 6 中，QNetworkConfiguration 和 QNetworkConfigurationManager 类已被移除。因此，QNetworkAccessManager 的以下成员函数也被移除：

void setConfiguration(const QNetworkConfiguration &config);
QNetworkConfiguration configuration() const;
QNetworkConfiguration activeConfiguration() const;
void setNetworkAccessible(NetworkAccessibility accessible);
NetworkAccessibility networkAccessible() const;
void networkSessionConnected();

QNetworkInformation该功能最初引入于 Qt 6.1，旨在取代承载管理 API 的某些方面。它通过提供一个统一的 API 来实现，该 API 可订阅操作系统通知的网络状态变化。

QNetworkInformation::reachability（）于 Qt 6.1 中引入，它取代了 QNetworkAccessManager::networkAccessible() 函数，同时提供了关于网络可达性的更详细信息。更多详情请参阅其文档。

在 Qt 6.2 中，QNetworkInformation 增加了检测捕获门户（captive portals）的能力。

在 Qt 6.3 中，QNetworkInformation 新增了 `QNetworkInformation::transportMedium()` 和 `QNetworkInformation::isMetered()` 方法。

已删除的枚举

QtNetwork 中移除了若干枚举项。其中包括不再受支持的协议和功能的常量：

  • QSsl::SslV2;
  • QSsl::SslV3;
  • QSsl::TlsV1SslV3;
  • QNetworkRequest::SpdyAllowedAttribute;
  • QNetworkRequest::SpdyWasUsedAttribute;
  • QNetworkAccessManager::未知访问状态;
  • QNetworkAccessManager::不可访问;
  • QNetworkAccessManager::Accessible

以及名称未遵循正确命名规范的枚举器：

QNetworkRequest::FollowRedirectsAttribute 已在 Qt 6 中移除，请参阅下文关于重定向处理的部分。

配置 QSslSocket

以下已弃用的函数在 Qt 6 中已被移除：

QList<QSslCipher> ciphers() const;
void setCiphers(const QList<QSslCipher> &ciphers);
void setCiphers(const QString &ciphers);
static void setDefaultCiphers(const QList<QSslCipher> &ciphers);
static QList<QSslCipher> defaultCiphers();
static QList<QSslCipher> supportedCiphers();
QList<QSslCipher> ciphers() const;
void setCiphers(const QList<QSslCipher> &ciphers);
void setCiphers(const QString &ciphers);
static void setDefaultCiphers(const QList<QSslCipher> &ciphers);
static QList<QSslCipher> defaultCiphers();
static QList<QSslCipher> supportedCiphers();
bool addCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem,
                       QRegExp::PatternSyntax syntax = QRegExp::FixedString);
void addCaCertificate(const QSslCertificate &certificate);
void addCaCertificates(const QList<QSslCertificate> &certificates);
void setCaCertificates(const QList<QSslCertificate> &certificates);
QList<QSslCertificate> caCertificates() const;
static bool addDefaultCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem,
                                     QRegExp::PatternSyntax syntax = QRegExp::FixedString);
static void addDefaultCaCertificate(const QSslCertificate &certificate);
static void addDefaultCaCertificates(const QList<QSslCertificate> &certificates);
static void setDefaultCaCertificates(const QList<QSslCertificate> &certificates);
static QList<QSslCertificate> defaultCaCertificates();
static QList<QSslCertificate> systemCaCertificates();

请使用 `QSslConfiguration ` 及其成员函数来设置这些参数，例如：

auto sslConfiguration = QSslConfiguration::defaultConfiguration();
sslConfiguration.setCiphers("ECDHE-ECDSA-AES256-SHA384");
// Set other parameters here ...
socket.setSslConfiguration(sslConfiguration);

QNetworkAccessManager 默认行为的变更

重定向策略

在 Qt 6 中，默认重定向策略已从“手动”更改为“QNetworkRequest::NoLessSafeRedirectPolicy ”。如果您的应用程序依赖于手动重定向处理（即将其槽连接到QNetworkReply::redirected 信号），则在创建请求时必须显式设置此策略：

request.setAttribute(QNetworkRequest::RedirectPolicyAttribute, QNetworkRequest::ManualRedirectPolicy);

默认启用 HTTP/2

在 Qt 6 中，QNetworkAccessManager 默认启用 HTTP/2 协议。根据协议方案（“https”或“http”）的不同，QNetworkAccessManager 将使用应用层协议协商（ALPN）TLS 扩展或“协议升级”（protocol upgrade）HTTP 头来协商 HTTP/2。 如果无法协商 HTTP/2，访问管理器将回退到使用 HTTP/1.1。如果您的应用程序只能使用 HTTP/1.1，则必须在新请求中手动禁用 HTTP/2：

request.setAttribute(QNetworkRequest::Http2AllowedAttribute, false);

QNetworkAccessManager 现已防范“归档炸弹”

从 Qt 6.2 开始，QNetworkAccessManager 将防范解压后文件大小远大于压缩形式的情况：若解压比率超过特定阈值，系统将报错并返回失败响应。此检查仅适用于大于特定大小的文件，您可通过调用QNetworkRequest::setDecompressedSafetyCheckThreshold() 自定义该阈值（或通过传入 -1 来禁用此检查）。

安全套接层 (SSL) 类

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.