QT WebEngine接入DoH

1. 前言

Qt WebEngine 从 Qt 6.6 版本开始支持 DNS over HTTPS (DoH) 功能，允许开发者通过加密的 HTTPS 协议进行 DNS 解析，以解决 Web 应用遇到的 DNS 劫持问题。HTTPDNS 是阿里云提供的移动解析服务，专门面向移动 APP 和 IoT 设备，提供稳定、安全、精准的公网递归觤析服务。本文将介绍如何在 Qt WebEngine 应用中接入 HTTPDNS 的 DoH 服务。

2. 前提条件

在接入Qt WebEngine DoH 前，请您确保已经完成配置DoH服务。

3. 接入配置

接入 HTTPDNS 的 DoH 服务主要通过 QWebEngineGlobalSettings::DnsMode API进行设置。

设置包含两部分内容：

• 安全模式（secureMode）：决定 DoH 与 LocalDNS 的使用优先级，控制在不同网络环境下的 DNS 解析策略和回退机制

• 服务器模板（serverTemplates）：配置 DoH 服务列表，指定可用的 DoH 服务器接入地址，支持多个服务器以提供高可用性

示例代码如下：

// DoH 配置
QWebEngineGlobalSettings::DnsMode dnsMode;
dnsMode.secureMode = QWebEngineGlobalSettings::SecureDnsMode::SecureWithFallback;
dnsMode.serverTemplates = QStringList{
 "https://xxxx.com/dns-query{?dns}"
};
QWebEngineGlobalSettings::setDnsMode(dnsMode);
// 配置 DoH 后，创建 WebEngineView 并加载网页
QWebEngineView *webView = new QWebEngineView();
webView->load(QUrl("https://www.example.com"));
webView->show();

4. 配置注意事项

• DoH接入模板格式，必须包含{?dns}参数

  • 正确示例："https://xxxx.aliyunhttpdns.com/dns-query{?dns}"

  • 错误示例："https://dns.xxxx/dns-query" （缺少{?dns}参数）

  • 错误示例："https://1.1.X.X/dns-query?dns=" （参数格式错误）

• DoH配置是全局生效

  • 通过QWebEngineGlobalSettings设置

  • 必须在创建任何QWebEngineView实例之前完成配置

  • 配置完成后，所有后续创建的WebEngineView都会自动使用DoH设置

• 高可用配置

  • 推荐使用SecureWithFallback模式避免极端情况下 DoH 不可用影响业务

  • 配置多个DoH服务器作为兜底方案，首个DoH服务使用 HTTPDNS，使用其他备用 DoH 作为容灾备用，比如免费的公共 DoH 服务。

5. 总结

本文介绍了在 Qt WebEngine 应用中集成 DNS over HTTPS (DoH) 的完整方案，包括基础配置、安全模式选择和高可用部署策略。配置后可通过网络抓包查看 HTTPS 请求、检查 DNS 日志或进行网络故障测试来验证 DoH 接入成功。推荐使用 SecureWithFallback 模式并配置多个 DoH 服务器以确保生产环境的稳定性。