timamsk/sing-box
1
0
Fork 0
mirror of https://github.com/SagerNet/sing-box.git synced 2026-04-17 13:23:06 +10:00
Code Issues Packages Projects Releases Wiki Activity

Replace internal terminology in docs and error messages

Browse Source 
Remove all user-facing references to the internal `legacyDNSMode` variable
name. Error messages now reuse the deprecated.Note.MessageWithLink() method
to provide consistent deprecation text with migration URLs. Other internal
jargon ("consume response state", "response_*") is replaced with
user-friendly descriptions.

Add two migration guide entries under 1.14.0: one for strategy → rule items,
one for address filter fields → evaluate with match_response.
This commit is contained in:
世界
2026-04-01 18:27:14 +08:00
parent c5c9d3ec05
commit eb4c550da2
12 changed files with 282 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/configuration/dns/rule.md
View File

@@ -497,8 +497,8 @@ Enable response-based matching. When enabled, this rule matches against DNS resp
(set by a preceding [`evaluate`](/configuration/dns/rule_action/#evaluate) action)
instead of only matching the original query.
Required for `response_rcode`, `response_answer`, `response_ns`, `response_extra` fields.
Also required for `ip_cidr` and `ip_is_private` when `legacyDNSMode` is disabled.
Required for Response Match Fields (`response_rcode`, `response_answer`, `response_ns`, `response_extra`).
Also required for `ip_cidr` and `ip_is_private` when used with `evaluate` or Response Match Fields.
#### invert
@@ -544,17 +544,13 @@ See [DNS Rule Actions](../rule_action/) for details.
Moved to [DNS Rule Action](../rule_action#route).
### Legacy DNS Mode
`legacyDNSMode` is an internal compatibility mode that is automatically detected from your DNS rule
configuration. It is disabled when any rule uses features introduced in sing-box 1.14.0 such as
`evaluate`, `match_response`, response fields (`response_rcode`, `response_answer`, etc.),
`query_type`, or `ip_version`. When disabled, `ip_cidr` and `ip_is_private` require `match_response`
to be set, and deprecated fields like `strategy`, `ip_accept_any`, and `rule_set_ip_cidr_accept_empty`
are no longer accepted.
### Address Filter Fields
!!! failure "Deprecated in sing-box 1.14.0"
Address Filter Fields are deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Only takes effect for address requests (A/AAAA/HTTPS). When the query results do not match the address filtering rule items, the current rule will be skipped.
!!! info ""
@@ -579,7 +575,8 @@ Match GeoIP with query response.
Match IP CIDR with query response.
When `legacyDNSMode` is disabled, `match_response` must be set to `true`.
As an Address Filter Field, deprecated. Use with `match_response` instead,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
#### ip_is_private
@@ -587,7 +584,8 @@ When `legacyDNSMode` is disabled, `match_response` must be set to `true`.
Match private IP with query response.
When `legacyDNSMode` is disabled, `match_response` must be set to `true`.
As an Address Filter Field, deprecated. Use with `match_response` instead,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
#### rule_set_ip_cidr_accept_empty
@@ -595,8 +593,8 @@ When `legacyDNSMode` is disabled, `match_response` must be set to `true`.
!!! failure "Deprecated in sing-box 1.14.0"
`rule_set_ip_cidr_accept_empty` is deprecated and will be removed in sing-box 1.16.0.
Only supported in `legacyDNSMode`.
`rule_set_ip_cidr_accept_empty` is deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Make `ip_cidr` rules in rule-sets accept empty query response.
@@ -606,8 +604,8 @@ Make `ip_cidr` rules in rule-sets accept empty query response.
!!! failure "Deprecated in sing-box 1.14.0"
`ip_accept_any` is deprecated and will be removed in sing-box 1.16.0.
Only supported in `legacyDNSMode`. Use `match_response` with response items instead.
`ip_accept_any` is deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Match any IP with query response.

31
docs/configuration/dns/rule.zh.md
View File

@@ -495,8 +495,8 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
启用响应匹配。启用后，此规则将匹配 DNS 响应数据（由前序 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作设置），而不仅是匹配原始查询。
`response_rcode`、`response_answer`、`response_ns`、`response_extra` 字段需要此选项。
当 `legacyDNSMode` 未启用时，`ip_cidr` 和 `ip_is_private` 也需要此选项。
响应匹配字段（`response_rcode`、`response_answer`、`response_ns`、`response_extra`）需要此选项。
当与 `evaluate` 或响应匹配字段一起使用时，`ip_cidr` 和 `ip_is_private` 也需要此选项。
#### invert
@@ -542,16 +542,13 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
已移动到 [DNS 规则动作](../rule_action#route).
### Legacy DNS Mode
`legacyDNSMode` 是一种内部兼容模式，会根据 DNS 规则配置自动检测。
当任何规则使用了 sing-box 1.14.0 引入的特性（如 `evaluate`、`match_response`、
响应字段（`response_rcode`、`response_answer` 等）、`query_type` 或 `ip_version`）时，
该模式将被自动禁用。禁用后，`ip_cidr` 和 `ip_is_private` 需要设置 `match_response`，
且已废弃的字段（如 `strategy`、`ip_accept_any`、`rule_set_ip_cidr_accept_empty`）将不再被接受。
### 地址筛选字段
!!! failure "已在 sing-box 1.14.0 废弃"
地址筛选字段已废弃，且将在 sing-box 1.16.0 中被移除，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
仅对地址请求 (A/AAAA/HTTPS) 生效。 当查询结果与地址筛选规则项不匹配时，将跳过当前规则。
!!! info ""
@@ -577,7 +574,8 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
与查询响应匹配 IP CIDR。
当 `legacyDNSMode` 未启用时，`match_response` 必须设为 `true`。
作为地址筛选字段已废弃。请改为配合 `match_response` 使用，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
#### ip_is_private
@@ -585,7 +583,8 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
与查询响应匹配非公开 IP。
当 `legacyDNSMode` 未启用时，`match_response` 必须设为 `true`。
作为地址筛选字段已废弃。请改为配合 `match_response` 使用，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
#### rule_set_ip_cidr_accept_empty
@@ -593,8 +592,8 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
!!! failure "已在 sing-box 1.14.0 废弃"
`rule_set_ip_cidr_accept_empty` 已废弃且将在 sing-box 1.16.0 中被移除。
仅在 `legacyDNSMode` 中可用。
`rule_set_ip_cidr_accept_empty` 已废弃且将在 sing-box 1.16.0 中被移除，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
使规则集中的 `ip_cidr` 规则接受空查询响应。
@@ -604,8 +603,8 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
!!! failure "已在 sing-box 1.14.0 废弃"
`ip_accept_any` 已废弃且将在 sing-box 1.16.0 中被移除。
仅在 `legacyDNSMode` 中可用。请使用 `match_response` 和响应项替代。
`ip_accept_any` 已废弃且将在 sing-box 1.16.0 中被移除，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
匹配任意 IP。

4
docs/configuration/dns/rule_action.md
View File

@@ -43,7 +43,7 @@ Tag of target server.
`strategy` is deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0.
Set domain strategy for this query. Only supported when `legacyDNSMode` is active.
Set domain strategy for this query. Deprecated, check [Migration](/migration/#migrate-dns-rule-action-strategy-to-rule-items).
One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
@@ -82,6 +82,8 @@ to match against using [`match_response`](/configuration/dns/rule/#match_respons
Unlike `route`, it does **not** terminate rule evaluation.
Only allowed on top-level DNS rules (not inside logical sub-rules).
The rule itself must not use `match_response` or contain sub-rules with Response Match Fields,
since `evaluate` populates the response for subsequent rules to consume.
#### server

4
docs/configuration/dns/rule_action.zh.md
View File

@@ -43,7 +43,7 @@ icon: material/new-box
`strategy` 已在 sing-box 1.14.0 废弃，且将在 sing-box 1.16.0 中被移除。
为此查询设置域名策略。仅在 `legacyDNSMode` 启用时可用。
为此查询设置域名策略。已废弃，参阅[迁移指南](/zh/migration/#迁移-dns-规则动作-strategy-到规则项)。
可选项：`prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`。
@@ -80,6 +80,8 @@ icon: material/new-box
`evaluate` 向指定服务器发送 DNS 查询并保存响应，供后续规则通过 [`match_response`](/zh/configuration/dns/rule/#match_response) 和响应字段进行匹配。与 `route` 不同，它**不会**终止规则评估。
仅允许在顶层 DNS 规则中使用（不可在逻辑子规则内部使用）。
该规则本身不可使用 `match_response` 或包含带有响应匹配字段的子规则，
因为 `evaluate` 是为后续规则填充响应数据。
#### server