# 迁移指南 - sing-box
The universal proxy platform.
Author: nekohasekai

跳转至

# 迁移指南

## 1.14.0

### 迁移内联 ACME 到证书提供者

TLS 中的内联 ACME 选项已废弃，且可以被证书提供者替代。

`tls.acme` 的大多数字段都可以原样迁移到 ACME 证书提供者中。 sing-box 1.14.0 新增字段参阅 ACME 页面。

参考

TLS / 证书提供者

弃用的
内联
共享

    {
      "inbounds": [
        {
          "type": "trojan",
          "tls": {
            "enabled": true,
            "acme": {
              "domain": ["example.com"],
              "email": "admin@example.com"
            }
          }
        }
      ]
    }

    {
      "inbounds": [
        {
          "type": "trojan",
          "tls": {
            "enabled": true,
            "certificate_provider": {
              "type": "acme",
              "domain": ["example.com"],
              "email": "admin@example.com"
            }
          }
        }
      ]
    }

    {
      "certificate_providers": [
        {
          "type": "acme",
          "tag": "my-cert",
          "domain": ["example.com"],
          "email": "admin@example.com"
        }
      ],
      "inbounds": [
        {
          "type": "trojan",
          "tls": {
            "enabled": true,
            "certificate_provider": "my-cert"
          }
        }
      ]
    }

### 迁移地址筛选字段到响应匹配

旧版地址筛选字段（不使用 `match_response` 的 `ip_cidr`、`ip_is_private`）已废弃， 旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项也已废弃。当旧版 DNS 模式被禁用时， 引用仅包含 `ip_cidr` 项的规则集（例如 GeoIP 规则集）且未设置 `match_response` 的 DNS 规则 也将在启动时被拒绝。

在 sing-box 1.14.0 中，请使用 `evaluate` 动作 获取 DNS 响应，然后通过 `match_response` 显式匹配。

参考

DNS 规则 / DNS 规则动作

弃用的
新的

    {
      "dns": {
        "rules": [
          {
            "rule_set": "geoip-cn",
            "action": "route",
            "server": "local"
          },
          {
            "action": "route",
            "server": "remote"
          }
        ]
      }
    }

    {
      "dns": {
        "rules": [
          {
            "action": "evaluate",
            "server": "remote"
          },
          {
            "match_response": true,
            "rule_set": "geoip-cn",
            "action": "route",
            "server": "local"
          },
          {
            "action": "route",
            "server": "remote"
          }
        ]
      }
    }

### 迁移 independent DNS cache

DNS 缓存现在始终按传输名称分离，使 `independent_cache` 不再需要。 直接移除该字段即可。

参考

DNS

弃用的
新的

    {
      "dns": {
        "independent_cache": true
      }
    }

    {
      "dns": {}
    }

### 迁移 store_rdrc

`store_rdrc` 已废弃，且可以被 `store_dns` 替代， 后者将完整的 DNS 缓存持久化到缓存文件中。

参考

缓存文件

弃用的
新的

    {
      "experimental": {
        "cache_file": {
          "enabled": true,
          "store_rdrc": true
        }
      }
    }

    {
      "experimental": {
        "cache_file": {
          "enabled": true,
          "store_dns": true
        }
      }
    }

### DNS 规则中的 ip_version 和 query_type 行为更改

在 sing-box 1.14.0 中，DNS 规则中的 `ip_version` 和 `query_type`，以及被引用规则集中的 `query_type`， 行为有两项更改。

其一，这些字段现在对每一次 DNS 规则评估都会生效。此前它们仅对来自客户端的 DNS 查询 （例如来自 DNS 入站或被 `tun` 截获的查询）生效，当 DNS 规则被未指定具体 DNS 服务器的 内部域名解析匹配时，会被静默忽略。此类内部解析包括：

- 未设置 `server` 的 `resolve` 路由规则动作。
- 通过 `direct` 出站路由到域名目标的 ICMP 流量。
- 作为出站使用的 WireGuard 或 Tailscale 端点在解析自身目标地址时。
- SOCKS4 出站，因为协议本身不支持域名， 必须在本地解析目标。
- DERP 的 `bootstrap-dns` 端点，以及 `resolved` 服务在解析主机名或 SRV 目标时。

通过拨号字段中的 `domain_resolver`、 路由选项中的 `default_domain_resolver`， 或 DNS 规则动作与 `resolve` 路由规则动作上显式的 `server` 指定具体 DNS 服务器的 解析，不会经过 DNS 规则匹配，不受此次更改影响。

其二，设置了 `ip_version` 或 `query_type` 的 DNS 规则，或引用了包含 `query_type` 的 规则集的 DNS 规则，在同一 DNS 配置中不再能与旧版地址筛选字段 (DNS 规则)、旧版 DNS 规则动作 `strategy` 选项，或旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项共存。 此类配置将在启动时被拒绝。如需将这些字段与基于地址的筛选组合，请通过 `evaluate` 动作和 `match_response` 迁移到响应匹配， 参阅 迁移地址筛选字段到响应匹配。

参考

DNS 规则 / Headless 规则 / 路由规则动作

## 1.12.0

### 迁移到新的 DNS 服务器格式

DNS 服务器已经重构。

引用

DNS 服务器 / 旧 DNS 服务器

LocalTCPUDPTLSHTTPSQUICHTTP3DHCPFakeIPRCode带有域名地址的服务器带有域策略的服务器带有客户端子网的服务器
弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "local"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "local"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "tcp://1.1.1.1"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "tcp",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "1.1.1.1"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "udp",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "tls://1.1.1.1"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "tls",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "https://1.1.1.1/dns-query"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "https",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "quic://1.1.1.1"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "quic",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "h3://1.1.1.1/dns-query"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "h3",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "dhcp://auto"
          },
          {
            "address": "dhcp://en0"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "dhcp",
          },
          {
            "type": "dhcp",
            "interface": "en0"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "1.1.1.1"
          },
          {
            "address": "fakeip",
            "tag": "fakeip"
          }
        ],
        "rules": [
          {
            "query_type": [
              "A",
              "AAAA"
            ],
            "server": "fakeip"
          }
        ],
        "fakeip": {
          "enabled": true,
          "inet4_range": "198.18.0.0/15",
          "inet6_range": "fc00::/18"
        }
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "udp",
            "server": "1.1.1.1"
          },
          {
            "type": "fakeip",
            "tag": "fakeip",
            "inet4_range": "198.18.0.0/15",
            "inet6_range": "fc00::/18"
          }
        ],
        "rules": [
          {
            "query_type": [
              "A",
              "AAAA"
            ],
            "server": "fakeip"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "rcode://refused"
          }
        ]
      }
    }

    {
      "dns": {
        "rules": [
          {
            "domain": [
              "example.com"
            ],
            // 其它规则

            "action": "predefined",
            "rcode": "REFUSED"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "https://dns.google/dns-query",
            "address_resolver": "google"
          },
          {
            "tag": "google",
            "address": "1.1.1.1"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "https",
            "server": "dns.google",
            "domain_resolver": "google"
          },
          {
            "type": "udp",
            "tag": "google",
            "server": "1.1.1.1"
          }
        ]
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "1.1.1.1",
            "strategy": "ipv4_only"
          },
          {
            "tag": "google",
            "address": "8.8.8.8",
            "strategy": "prefer_ipv6"
          }
        ],
        "rules": [
          {
            "domain": "google.com",
            "server": "google"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "udp",
            "server": "1.1.1.1"
          },
          {
            "type": "udp",
            "tag": "google",
            "server": "8.8.8.8"
          }
        ],
        "rules": [
          {
            "domain": "google.com",
            "server": "google",
            "strategy": "prefer_ipv6"
          }
        ],
        "strategy": "ipv4_only"
      }
    }

弃用的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "1.1.1.1"
          },
          {
            "tag": "google",
            "address": "8.8.8.8",
            "client_subnet": "1.1.1.1"
          }
        ]
      }
    }

    {
      "dns": {
        "servers": [
          {
            "type": "udp",
            "server": "1.1.1.1"
          },
          {
            "type": "udp",
            "tag": "google",
            "server": "8.8.8.8"
          }
        ],
        "rules": [
          {
            "domain": "google.com",
            "server": "google",
            "client_subnet": "1.1.1.1"
          }
        ]
      }
    }

### 迁移 outbound DNS 规则项到域解析选项

旧的 `outbound` DNS 规则已废弃，且可新的域解析选项代替。

参考

DNS 规则 / 拨号字段 / 路由

废弃的
新的

    {
      "dns": {
        "servers": [
          {
            "address": "local",
            "tag": "local"
          }
        ],
        "rules": [
          {
            "outbound": "any",
            "server": "local"
          }
        ]
      },
      "outbounds": [
        {
          "type": "socks",
          "server": "example.org",
          "server_port": 2080
        }
      ]
    }

    {
      "dns": {
        "servers": [
          {
            "type": "local",
            "tag": "local"
          }
        ]
      },
      "outbounds": [
        {
          "type": "socks",
          "server": "example.org",
          "server_port": 2080,
          "domain_resolver": {
            "server": "local",
            "rewrite_ttl": 60,
            "client_subnet": "1.1.1.1"
          },
          // 或 "domain_resolver": "local",
        }
      ],

      // 或

      "route": {
        "default_domain_resolver": {
          "server": "local",
          "rewrite_ttl": 60,
          "client_subnet": "1.1.1.1"
        }
      }
    }

### 迁移出站域名策略选项到域名解析器

拨号字段中的 `domain_strategy` 选项已被弃用，可以用新的域名解析器选项替代。

请注意，由于 sing-box 1.12 中引入的一些新 DNS 服务器使用了拨号字段，一些人错误地认为 `domain_strategy` 与旧 DNS 服务器中的功能相同。

参考

拨号字段

弃用的
新的

    {
      "outbounds": [
        {
          "type": "socks",
          "server": "example.org",
          "server_port": 2080,
          "domain_strategy": "prefer_ipv4",
        }
      ]
    }

     {
      "dns": {
        "servers": [
          {
            "type": "local",
            "tag": "local"
          }
        ]
      },
      "outbounds": [
        {
          "type": "socks",
          "server": "example.org",
          "server_port": 2080,
          "domain_resolver": {
            "server": "local",
            "strategy": "prefer_ipv4"
          }
        }
      ]
    }

## 1.11.0

### 迁移旧的特殊出站到规则动作

旧的特殊出站已被弃用，且可以被规则动作替代。

参考

规则动作 / Block / DNS

BlockDNS
弃用的
新的

    {
      "outbounds": [
        {
          "type": "block",
          "tag": "block"
        }
      ],
      "route": {
        "rules": [
          {
            ...,

            "outbound": "block"
          }
        ]
      }
    }

    {
      "route": {
        "rules": [
          {
            ...,

            "action": "reject"
          }
        ]
      }
    }

弃用的
新的

    {
      "inbound": [
        {
          ...,

          "sniff": true
        }
      ],
      "outbounds": [
        {
          "tag": "dns",
          "type": "dns"
        }
      ],
      "route": {
        "rules": [
          {
            "protocol": "dns",
            "outbound": "dns"
          }
        ]
      }
    }

    {
      "route": {
        "rules": [
          {
            "action": "sniff"
          },
          {
            "protocol": "dns",
            "action": "hijack-dns"
          }
        ]
      }
    }

### 迁移旧的入站字段到规则动作

入站选项已被弃用，且可以被规则动作替代。

参考

监听字段 / 规则 / 规则动作 / DNS 规则 / DNS 规则动作

弃用的
新的

    {
      "inbounds": [
        {
          "type": "mixed",
          "sniff": true,
          "sniff_timeout": "1s",
          "domain_strategy": "prefer_ipv4"
        }
      ]
    }

    {
      "inbounds": [
        {
          "type": "mixed",
          "tag": "in"
        }
      ],
      "route": {
        "rules": [
          {
            "inbound": "in",
            "action": "resolve",
            "strategy": "prefer_ipv4"
          },
          {
            "inbound": "in",
            "action": "sniff",
            "timeout": "1s"
          }
        ]
      }
    }

### 迁移 direct 出站中的目标地址覆盖字段到路由字段

direct 出站中的目标地址覆盖字段已废弃，且可以被路由字段替代。

参考

Rule Action / Direct

弃用的
新的

    {
      "outbounds": [
        {
          "type": "direct",
          "override_address": "1.1.1.1",
          "override_port": 443
        }
      ]
    }

    {
      "route": {
        "rules": [
          {
            "action": "route-options", // 或 route
            "override_address": "1.1.1.1",
            "override_port": 443
          }
        ]
      }
    }

### 迁移 WireGuard 出站到端点

WireGuard 出站已被弃用，且可以被端点替代。

参考

端点 / WireGuard 端点 / WireGuard 出站

弃用的
新的

    {
      "outbounds": [
        {
          "type": "wireguard",
          "tag": "wg-out",

          "server": "127.0.0.1",
          "server_port": 10001,
          "system_interface": true,
          "gso": true,
          "interface_name": "wg0",
          "local_address": [
            "10.0.0.1/32"
          ],
          "private_key": "<private_key>",
          "peer_public_key": "<peer_public_key>",
          "pre_shared_key": "<pre_shared_key>",
          "reserved": [0, 0, 0],
          "mtu": 1408
        }
      ]
    }

    {
      "endpoints": [
        {
          "type": "wireguard",
          "tag": "wg-ep",
          "system": true,
          "name": "wg0",
          "mtu": 1408,
          "address": [
            "10.0.0.2/32"
          ],
          "private_key": "<private_key>",
          "listen_port": 10000,
          "peers": [
            {
              "address": "127.0.0.1",
              "port": 10001,
              "public_key": "<peer_public_key>",
              "pre_shared_key": "<pre_shared_key>",
              "allowed_ips": [
                "0.0.0.0/0"
              ],
              "persistent_keepalive_interval": 30,
              "reserved": [0, 0, 0]
            }
          ]
        }
      ]
    }

## 1.10.0

### TUN 地址字段已合并

`inet4_address` 和 `inet6_address` 已合并为 `address`， `inet4_route_address` 和 `inet6_route_address` 已合并为 `route_address`， `inet4_route_exclude_address` 和 `inet6_route_exclude_address` 已合并为 `route_exclude_address`。

参考

TUN

弃用的
新的

    {
      "inbounds": [
        {
          "type": "tun",
          "inet4_address": "172.19.0.1/30",
          "inet6_address": "fdfe:dcba:9876::1/126",
          "inet4_route_address": [
            "0.0.0.0/1",
            "128.0.0.0/1"
          ],
          "inet6_route_address": [
            "::/1",
            "8000::/1"
          ],
          "inet4_route_exclude_address": [
            "192.168.0.0/16"
          ],
          "inet6_route_exclude_address": [
            "fc00::/7"
          ]
        }
      ]
    }

    {
      "inbounds": [
        {
          "type": "tun",
          "address": [
            "172.19.0.1/30",
            "fdfe:dcba:9876::1/126"
          ],
          "route_address": [
            "0.0.0.0/1",
            "128.0.0.0/1",
            "::/1",
            "8000::/1"
          ],
          "route_exclude_address": [
            "192.168.0.0/16",
            "fc00::/7"
          ]
        }
      ]
    }

## 1.9.5

### Apple 平台客户端的 Bundle Identifier 更新

由于我们旧的苹果开发者账户存在问题，我们只能通过更新 Bundle Identifiers 来重新上架 sing-box 应用， 这意味着数据不会自动继承。

对于 iOS，您需要自行备份旧的数据（如果您仍然可以访问）；
对于 Apple tvOS，您需要从 iPhone 或 iPad 重新导入配置或者手动创建；
对于 macOS，您可以使用以下命令迁移数据文件夹：

    cd ~/Library/Group\ Containers && \
      mv group.io.nekohasekai.sfa group.io.nekohasekai.sfavt

## 1.9.0

### `domain_suffix` 行为更新

由于历史原因，sing-box 的 `domain_suffix` 规则匹配字面前缀，而不与其他项目相同。

sing-box 1.9.0 修改了 `domain_suffix` 的行为：如果规则值以 `.` 为前缀则行为不变，否则改为匹配 `(domain|.+\.domain)`。

### 对 Windows 上 `process_path` 格式的更新

sing-box 的 `process_path` 规则继承自Clash， 原始代码使用本地系统的路径格式（例如 `\Device\HarddiskVolume1\folder\program.exe`）， 但是当设备有多个硬盘时，该 HarddiskVolume 系列号并不稳定。

sing-box 1.9.0 使 QueryFullProcessImageNameW 输出 Win32 路径（如 `C:\folder\program.exe`）， 这将会破坏现有的 Windows `process_path` 用例。

## 1.8.0

###
将缓存文件从 Clash API 迁移到独立选项

参考

Clash API / Cache File

弃用的
新的

    {
      "experimental": {
        "clash_api": {
          "cache_file": "cache.db", // 默认值
          "cahce_id": "my_profile2",
          "store_mode": true,
          "store_selected": true,
          "store_fakeip": true
        }
      }
    }

    {
      "experimental"  : {
        "cache_file": {
          "enabled": true,
          "path": "cache.db", // 默认值
          "cache_id": "my_profile2",
          "store_fakeip": true
        }
      }
    }

###
迁移 GeoIP 到规则集

参考

GeoIP / 路由 / 路由规则 / DNS 规则 / 规则集

Tip

`sing-box geoip` 命令可以帮助您将自定义 GeoIP 转换为规则集。

弃用的
新的

    {
      "route": {
        "rules": [
          {
            "geoip": "private",
            "outbound": "direct"
          },
          {
            "geoip": "cn",
            "outbound": "direct"
          },
          {
            "source_geoip": "cn",
            "outbound": "block"
          }
        ],
        "geoip": {
          "download_detour": "proxy"
        }
      }
    }

    {
      "route": {
        "rules": [
          {
            "ip_is_private": true,
            "outbound": "direct"
          },
          {
            "rule_set": "geoip-cn",
            "outbound": "direct"
          },
          {
            "rule_set": "geoip-us",
            "rule_set_ipcidr_match_source": true,
            "outbound": "block"
          }
        ],
        "rule_set": [
          {
            "tag": "geoip-cn",
            "type": "remote",
            "format": "binary",
            "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs",
            "download_detour": "proxy"
          },
          {
            "tag": "geoip-us",
            "type": "remote",
            "format": "binary",
            "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-us.srs",
            "download_detour": "proxy"
          }
        ]
      },
      "experimental": {
        "cache_file": {
          "enabled": true // required to save rule-set cache
        }
      }
    }

###
迁移 Geosite 到规则集

参考

Geosite / 路由 / 路由规则 / DNS 规则 / 规则集

Tip

`sing-box geosite` 命令可以帮助您将自定义 Geosite 转换为规则集。

弃用的
新的

    {
      "route": {
        "rules": [
          {
            "geosite": "cn",
            "outbound": "direct"
          }
        ],
        "geosite": {
          "download_detour": "proxy"
        }
      }
    }

    {
      "route": {
        "rules": [
          {
            "rule_set": "geosite-cn",
            "outbound": "direct"
          }
        ],
        "rule_set": [
          {
            "tag": "geosite-cn",
            "type": "remote",
            "format": "binary",
            "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs",
            "download_detour": "proxy"
          }
        ]
      },
      "experimental": {
        "cache_file": {
          "enabled": true // required to save rule-set cache
        }
      }
    }