Nginx默认不配置resolver且不继承系统DNS,动态解析域名必须在http块顶层显式声明resolver,支持多DNS、valid缓存和resolver_timeout超时控制,禁用未运行DNS服务的127.0.0.1。

Nginx 安装后默认不配置 resolver,也**不会自动继承系统 DNS 设置**。若在配置中用到变量域名(如 proxy_pass http://$backend_host、upstream 动态解析、或使用 return 302 https://$domain 等场景),必须显式声明 resolver,否则会报错 no resolver defined to resolve ... 或连接失败。
resolver 必须在 http/server/location 块外的全局作用域设置
resolver 指令**不能写在 location 或 upstream 块内**,只能出现在 http 块或 server 块顶层(但推荐统一放在 http 块)。Nginx 启动时仅读取一次该配置,后续所有动态 DNS 解析均复用此 resolver。
- ✅ 正确位置:http { resolver 8.8.8.8 1.1.1.1 valid=30s; }
- ❌ 错误位置:location / { resolver 127.0.0.1; }(会被忽略)
- ⚠️ 注意:多个
resolver行会覆盖前值,只保留最后一个
推荐配置参数:DNS 地址 + valid + timeout
基础写法如 resolver 8.8.8.8 1.1.1.1 valid=30s; 已满足多数场景,但建议补充超时控制以提升健壮性:
-
指定多个 DNS 服务器:提高容错,如
resolver 114.114.114.114 223.5.5.5 1.1.1.1; -
设置缓存有效期(valid):避免频繁查 DNS,例如
valid=60s表示解析结果最多缓存 60 秒 -
添加超时参数(可选):如
resolver_timeout 5s;控制单次查询最大等待时间(默认 30s)
避免使用 localhost 或 127.0.0.1 作为 resolver
除非你明确运行了本地 DNS 服务(如 dnsmasq、coredns、systemd-resolved 并监听 UDP 53),否则配置 resolver 127.0.0.1 极大概率导致解析失败。
- Linux 上
/etc/resolv.conf的 nameserver 不代表 Nginx 能直接访问 —— Nginx 不读该文件 - Docker/K8s 环境中,宿主机的
127.0.0.1对容器不可达,应改用宿主机真实 IP 或集群 DNS 地址(如10.96.0.10) - 验证方法:
docker exec -it nginx-container nslookup google.com 8.8.8.8(模拟 Nginx 行为)
动态 upstream 场景需额外注意
若用 set $upstream "api.example.com:80"; proxy_pass http://$upstream; 这类方式实现动态上游,resolver 是强制前提;但要注意:
- Nginx 不会自动刷新已解析的 IP,靠
valid=控制缓存过期后重查 - 若后端 IP 变更但未过期,仍会发请求到旧地址,可能连接拒绝(Connection refused)
- 如需强实时性,可结合
resolver+proxy_next_upstream error timeout invalid_header http_500;实现故障转移

















