libcurl 自定义 DNS 服务器：CURLOPT_DNS_SERVERS 完整指南-开发者社区

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

【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl

导读

当应用需要绕过系统默认 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

两个关键点值得注意：

该 case 被#ifdef USE_RESOLV_ARES包裹，意味着只有在编译期启用了 c-ares 解析后端时，该选项才会被注册；否则curl_easy_setopt会返回CURLE_UNKNOWN_OPTION。
字符串通过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 是唯一满足条件的内置后端。这一点在源码中体现得十分直接：

lib/setopt.c 中CURLOPT_DNS_SERVERS仅在USE_RESOLV_ARES宏开启时注册；
lib/vdns/asyn-ares.c 还硬性要求 c-ares 版本不低于 1.16.0：

#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，其注释说明了两个调用场景：

应用通过CURLOPT_DNS_SERVERS传入新值（或传入 NULL 取消之前设置）时，若已有 channel，需要重建 channel 以使新值生效；
惰性初始化 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 使用注意事项

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考