libcurl 自定义 DNS 服务器:CURLOPT_DNS_SERVERS 完整指南

原创2026-09-09 19:33:091,454 阅读
文章标签:网络通信CLI跨平台

libcurl 自定义 DNS 服务器:CURLOPT_DNS_SERVERS 完整指南

导读

当应用需要绕过系统默认 DNS 解析路径、切换特定解析器或排查域名解析故障时,libcurl 提供了 CURLOPT_DNS_SERVERS 选项,允许为单个 easy handle 指定一组自定义 DNS 服务器(可带端口)。本文基于 curl 官方文档 CURLOPT_DNS_SERVERS 展开,结合仓库内 setopt.c、asyn-ares.c 等源码实现,完整讲解该选项的语法、调用方式、底层解析流程、前提条件与常见问题,同时覆盖命令行工具 curl 对应的 --dns-servers 参数,帮助读者在需要精细控制 DNS 解析时正确使用这一能力。

一、选项总览

CURLOPT_DNS_SERVERS 用于替换系统默认 DNS 服务器,将域名解析请求定向到应用指定的 DNS 服务器列表。下表汇总了该选项的关键属性(依据 CURLOPT_DNS_SERVERS.md 头部元信息):

属性 值
引入版本 7.24.0
适用协议 全部(All,DNS 解析是传输层前置步骤)
默认值 NULL(即使用系统默认解析配置)
取值类型 char *(以 NUL 结尾的字符串)
底层要求 libcurl 须以 c-ares 作为解析后端构建
重复调用 最后一次设置覆盖此前值
重置方式 传入 NULL 关闭该功能

该选项在 curl_easy_setopt(3) 家族中归属于字符串指针类网络选项,其设置入口位于 lib/setopt.c 的 setopt_cptr_net() 函数:

#ifdef USE_RESOLV_ARES
  case CURLOPT_DNS_SERVERS:
    return Curl_setstropt(data, STRING_DNS_SERVERS, ptr);
#endif

两个关键点值得注意:

  1. 该 case 被 #ifdef USE_RESOLV_ARES 包裹,意味着只有在编译期启用了 c-ares 解析后端时,该选项才会被注册;否则 curl_easy_setopt 会返回 CURLE_UNKNOWN_OPTION。
  2. 字符串通过 Curl_setstropt 存入内部 STRING_DNS_SERVERS 槽位,libcurl 会自行拷贝,因此调用方在设置之后无需再保留该字符串(文档 DESCRIPTION 亦明确说明这一点)。

二、语法与取值格式

选项的值是一个逗号分隔的服务器列表,每项格式为:

host[:port][,host[:port]]...

示例:

192.168.1.100,192.168.1.101,3.4.5.6

说明:

  • host:DNS 服务器地址,通常为 IPv4 地址;从实现角度看,该字符串最终交给 c-ares 的 ares_set_servers_ports_csv() 解析,因此也支持 IPv6 地址字面量等 c-ares 认可的地址形式。
  • port:可选。省略时使用默认 DNS 端口 53;指定时以冒号追加,如 192.168.1.100:53。
  • 多个服务器之间用英文逗号分隔,libcurl 与 c-ares 会按列表顺序依次尝试。

命令行工具 curl 侧对应的 --dns-servers 参数(docs/cmdline-opts/dns-servers.md)使用同样的语法:

--dns-servers 192.168.0.1,192.168.0.2 $URL
--dns-servers 10.0.0.1:53 $URL

三、完整示例代码

以下示例来自官方文档 CURLOPT_DNS_SERVERS.md 的 EXAMPLE 小节,展示了在一个 easy handle 上同时设置 URL 与自定义 DNS 服务器:

#include <curl/curl.h>

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
    curl_easy_setopt(curl, CURLOPT_DNS_SERVERS,
                     "192.168.1.100:53,192.168.1.101");
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

代码要点:

  • CURLOPT_DNS_SERVERS 的设置在 curl_easy_perform() 之前完成即可,无需单独初始化解析器。
  • 第一个服务器 192.168.1.100 显式指定了端口 53,第二个 192.168.1.101 省略端口,两者写法等价。
  • 若设置失败(例如 libcurl 未以 c-ares 构建),curl_easy_setopt 返回非 CURLE_OK 的错误码,示例中通过 result 承接以便检查。

--libcurl 选项生成的代码同样会包含该设置,仓库 src/config2setopts.c 中有对应映射:

MY_SETOPT_STR(curl, CURLOPT_DNS_SERVERS, config->dns_servers);

四、底层实现:从选项到 c-ares 通道

4.1 前置条件:必须以 c-ares 构建

官方文档 NOTES 明确:该选项要求 libcurl 使用支持此操作的解析后端,c-ares 是唯一满足条件的内置后端。这一点在源码中体现得十分直接:

#if ARES_VERSION < 0x011000
#error "c-ares 1.16.0 or greater required"
#endif

因此,判断当前 libcurl 是否支持该选项,可以检查构建配置中是否包含 c-ares(如 ./configure --enable-ares 或 CMake 的 -DCARES=ON)。

4.2 设置生效时机与调用链

该选项的值并不会在 curl_easy_setopt 调用时立即下发到 c-ares 通道,而是在解析器初始化阶段统一应用。核心逻辑在 lib/vdns/asyn-ares.c 的 async_ares_init():创建 ares channel 之后,依次调用 async_ares_set_dns_servers()、async_ares_set_dns_interface()、async_ares_set_dns_local_ip4()、async_ares_set_dns_local_ip6() 四个设置函数,将用户配置的 DNS 服务器、出口接口、本地 IP 绑定等偏好一次性写入 channel。

async_ares_set_dns_servers() 的实现位于 lib/vdns/asyn-ares.c,其注释说明了两个调用场景:

  1. 应用通过 CURLOPT_DNS_SERVERS 传入新值(或传入 NULL 取消之前设置)时,若已有 channel,需要重建 channel 以使新值生效;
  2. 惰性初始化 channel 时应用已有偏好,此时 NULL 表示无偏好、不重置现有 channel。

函数核心代码如下:

const char *servers = CURL_EASY_STR(data, STRING_DNS_SERVERS);

#ifdef DEBUGBUILD
  if(getenv("CURL_DNS_SERVER"))
    servers = getenv("CURL_DNS_SERVER");
#endif

  if(!servers)
    return CURLE_OK;

  /* if channel is not there, this is a parameter check */
  if(ares && ares->channel)
    ares_result = ares_set_servers_ports_csv(ares->channel, servers);

值得注意的实现细节:

  • 调试环境变量:在 DEBUGBUILD 编译下,环境变量 CURL_DNS_SERVER 会覆盖代码中设置的值,便于开发者不修改代码即可切换 DNS 服务器进行调试。
  • 参数预校验:注释“if channel is not there, this is a parameter check”表明,即使 channel 尚未创建,该函数也会被调用以提前校验服务器字符串的合法性。

4.3 错误码映射

ares_set_servers_ports_csv() 的返回值被逐一映射为 libcurl 错误码(lib/vdns/asyn-ares.c):

c-ares 返回值 含义 libcurl 错误码
ARES_SUCCESS 解析成功 CURLE_OK (0)
ARES_ENOMEM 内存不足 CURLE_OUT_OF_MEMORY
ARES_ENOTINITIALIZED / ARES_ENODATA / ARES_EBADSTR 未初始化 / 无数据 / 服务器字符串格式非法 CURLE_BAD_FUNCTION_ARGUMENT

因此,当传入的服务器列表格式错误(如非法 IP、多余分隔符)时,应用会在解析阶段收到 CURLE_BAD_FUNCTION_ARGUMENT。若设置失败,async_ares_init() 会销毁已创建的 channel 并将错误向上传递。

五、命令行工具用法:--dns-servers

除库 API 外,curl 命令行工具从 7.33.0 起提供 --dns-servers 参数,与 CURLOPT_DNS_SERVERS 一一对应(docs/cmdline-opts/dns-servers.md):

curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com/
curl --dns-servers 10.0.0.1:53 https://example.com/

参数解析逻辑位于 src/tool_getparam.c:

case C_DNS_SERVERS: /* --dns-servers */
  if(!curlinfo->ares_num) /* c-ares is needed for this */
    err = PARAM_LIBCURL_DOESNT_SUPPORT;
  else
    /* IP addrs of DNS servers */
    err = getstr(&config->dns_servers, nextarg, DENY_BLANK);
  break;

同样地,命令行工具在运行时若检测到 libcurl 未编译 c-ares 支持(通过 curlinfo->ares_num 判断),会直接返回 PARAM_LIBCURL_DOESNT_SUPPORT,提示该参数不可用。

六、与其他 DNS 相关选项的配合

CURLOPT_DNS_SERVERS 属于 libcurl DNS 解析控制族,官方文档 See-also 一节指出了可配合使用的相邻选项,它们在 lib/setopt.c 中同属 USE_RESOLV_ARES 代码块:

选项 引入版本 作用
CURLOPT_DNS_CACHE_TIMEOUT 7.9.3 设置 DNS 缓存条目存活时间(秒),见 CURLOPT_DNS_CACHE_TIMEOUT.md
CURLOPT_DNS_LOCAL_IP4 7.33.0 指定 IPv4 解析请求的本地出口 IP,见 CURLOPT_DNS_LOCAL_IP4.md
CURLOPT_DNS_LOCAL_IP6 7.33.0 指定 IPv6 解析请求的本地出口 IP,见 CURLOPT_DNS_LOCAL_IP6.md
CURLOPT_DNS_INTERFACE 7.33.0 指定发起 DNS 查询的网络接口,见 CURLOPT_DNS_INTERFACE.md

这些选项都在 async_ares_init() 中依次生效(lib/vdns/asyn-ares.c),例如 async_ares_set_dns_interface() 通过 ares_set_local_dev() 绑定出口设备(lib/vdns/asyn-ares.c),async_ares_set_dns_local_ip4() 通过 ares_set_local_ip4() 绑定本地地址。当需要“指定 DNS 服务器 + 指定出口 IP/网卡”组合时,可同时设置多个选项。

另外,若使用 DoH(DNS over HTTPS,CURLOPT_DOH_URL),自定义 DNS 服务器列表会作用于 DoH 服务器本身的域名解析,二者搭配可实现“加密查询上游 + 私有解析下游”的分层解析。

七、测试验证与注意事项

7.1 仓库中的相关测试

仓库 tests/libtest/lib1592.c 给出了一个利用该选项的典型测试场景:

/* Set a DNS server that hopefully does not respond when using c-ares. */
if(curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, "0.0.0.0") == CURLE_OK)

该测试把 DNS 服务器指向 0.0.0.0(一个大概率不响应的地址),并据此推断当前 libcurl 构建使用的是 c-ares 后端——因为只有 c-ares 后端才会接受该选项并返回 CURLE_OK。这既验证了选项的功能,也提供了一种运行时探测 libcurl 是否支持自定义 DNS 服务器的实用手法。

7.2 使用注意事项

  1. 后端依赖:未以 c-ares 构建的 libcurl 无法使用本选项(API 返回 CURLE_UNKNOWN_OPTION,命令行返回参数不支持)。这是最常见的使用前提。
  2. 字符串生命周期:curl_easy_setopt 内部已拷贝字符串,调用后可立即释放或复用该内存;但后续若想修改服务器列表,需重新调用该选项。
  3. 覆盖与重置:多次调用以最后一次为准;传入 NULL 可恢复系统默认解析(在已有 channel 时会触发重建)。
  4. 格式校验:服务器列表格式错误时,解析阶段会返回 CURLE_BAD_FUNCTION_ARGUMENT,建议在调试模式下结合详细日志定位。
  5. 多服务器语义:列表按顺序提供多个服务器作为候选,具体故障切换策略由 c-ares 决定,应用层无需自行实现重试。

八、总结

CURLOPT_DNS_SERVERS 是 libcurl 面向应用层暴露的自定义 DNS 解析入口,其核心价值在于:在不影响系统全局 /etc/resolv.conf(或其他平台解析配置)的前提下,为单个 easy handle 指定专属 DNS 服务器列表。从仓库源码可以看出,它的实现深度绑定 c-ares 后端——从 setopt.c 的选项注册,到 asyn-ares.c 中调用 ares_set_servers_ports_csv() 完成下发,整条链路清晰可查。配合 CURLOPT_DNS_INTERFACE、CURLOPT_DNS_LOCAL_IP4/IP6 等选项,开发者可以构建精细的 DNS 分流与绑定策略,是排查域名解析故障、对接私有 DNS 基础设施时的重要工具。

登录后查看全文
curl