XTLS_Xray-docs-next/docs/development/lua/reference/module-dns.md

xray.dns

提供 DNS 查询和上游服务器访问接口。

local dns = require("xray.dns")

API 索引

分类	成员	说明
函数	dns.Query(domain, ipv4, ipv6, fake)	通过 Xray DNS 客户端查询
字段	dns.Servers	上游服务器数组
对象	serverObj	单个 DNS 上游服务器
字段	serverObj.ID	服务器标识
方法	serverObj:Query(domain, ipv4, ipv6, fake)	直接查询指定上游

函数

dns.Query

local ips, ttl, err = dns.Query(domain, ipv4, ipv6, fake)

通过 Xray 的 DNS 客户端查询域名。在 DNS Hook 中不可用，因为脚本接管的就是它。

参数

参数	类型	说明
domain	string	待查询域名
ipv4	boolean	是否允许查询 IPv4
ipv6	boolean	是否允许查询 IPv6
fake	boolean	是否允许使用 FakeDNS

返回值

返回值	类型	说明
ips	[]net.IP 或 nil	查询结果
ttl	number	TTL（秒），范围 0 .. 4294967295，始终非 nil
err	error 或 nil	查询错误，nil 表示无错误

行为约定

四个参数均须显式传入且类型正确，否则抛出 Lua 异常。

查询遵循客户端的全局查询类型限制、Hosts 和上游配置；配置了 DNS 脚本时，也会交由该脚本处理。未配置内置 DNS 时使用系统 DNS。

查询成功时返回非空 IP slice；查询失败或没有可用地址时返回 nil, 0, err。

示例

local ips, ttl, err = dns.Query("example.com", true, true, false)
if err == nil and ips ~= nil and #ips > 0 then
    local firstIP = ips[1]:String()
end

字段

dns.Servers

local servers = dns.Servers

名称	类型	说明
dns.Servers	table	serverObj 数组，下标从 1 开始，顺序与配置相同

使用内置 DNS 时，列表包含配置的上游；未配置 DNS 或上游服务器时，列表仅包含 localhost（系统 DNS）。

可用 ipairs 遍历列表；下标超出范围时，servers[i] 为 nil。

示例

for _, serverObj in ipairs(dns.Servers) do
    local id = serverObj.ID
end

对象

server

serverObj 表示一个 DNS 上游服务器，包含其标识和查询方法。

属性	说明
Go 侧实现	app/dns 中的 luaDNSServer
Lua 表现	table
取得方式	dns.Servers 的数组元素

ID

local id = serverObj.ID

名称	类型	说明
serverObj.ID	string	对应 DNS 服务器配置中的 id 字段，始终非 nil

未填写 id 时为 ""，包括用字符串形式配置的服务器；自动添加的系统 DNS 上游 ID 为 "localhost"。

需要通过 ID 区分服务器时，请自行配置唯一的值，核心不会检查是否重复。

Query

local ips, ttl, err = serverObj:Query(domain, ipv4, ipv6, fake)

查询 serverObj 对应的上游。

参数与返回值

参数要求和返回值类型与 dns.Query 相同。

行为约定

正常配置的上游成功时返回非空 IP slice、TTL 和 nil；查询失败、没有符合条件的地址，或 fake == false 却查询 FakeDNS 时返回 nil, 0, err。

直接查询该服务器，跳过全局 Hosts 和 DNS 脚本。服务器自身的 queryStrategy、缓存、timeoutMs、clientIP、tag，以及 expectedIPs / unexpectedIPs 和对应的 actPrior / actUnprior 仍然生效。

示例

在 DNS Hook 中直接返回首个上游的查询结果：

function HandleDNSQuery(domain, ipv4, ipv6, fake)
    return dns.Servers[1]:Query(domain, ipv4, ipv6, fake)
end