官方手册 · 配置大全

Shadowrocket
规则与配置参考

先确认当前配置,再检查匹配条件与规则顺序。本文把配置文件、策略和请求处理边界分开说明,适合按问题定位,也适合逐章核对已有配置。

示例均使用 example.com,不包含服务器凭据,也不替代用户已有订阅。

本页是系统查阅手册;入门指南负责从导入已有订阅到首次连接的操作主线。尚未完成基本连接时,先走完入门流程;已经可以连接但需要解释某条请求的去向时,再按本页目录查阅。不同平台的编辑入口与可用字段可能不同,以下以 Shadowrocket 的配置语义为主,界面入口以当前客户端显示为准。

Shadowrocket 覆盖 iPhone、iPad、Mac、Windows、安卓与 Linux。iPhone / iPad 版在 App Store $2.99 一次性付费,Mac(Apple 芯片与 Intel)、Windows、安卓、Linux 版免费。获取入口见全平台下载页;iPhone / iPad 系统要求以 App Store 页面标注为准。客户端一次性买断 ≠ 线路套餐,本站不提供、不销售、不推荐节点或订阅;本文始终以用户已有自己的订阅或服务器信息为前提。

配置文件结构:先分清每一段的职责

Shadowrocket 的配置文件不是服务器列表的另一种名称。服务器信息回答“使用哪个连接端点”,配置文件回答“遇到某种请求时如何处理”。从 Subscribe 更新已有订阅,通常是在维护连接信息;在 Config 中切换配置,则可能改变规则、DNS 与地址映射等行为。两者可以关联,但不能把一次订阅更新理解为所有配置项都已经同步。排查时应分别记录当前选中的服务器与当前生效的配置,避免只检查其中一项。

段名确定作用域,规则行表达条件

常见的 .conf 文本用方括号标记段名。[General] 放整体选项,[Rule] 放按顺序判断的分流规则,[Host] 放主机名到地址的静态映射,[URL Rewrite] 放针对可见请求 URL 的改写表达式。段落在文件中的排版顺序,不等于所有功能按这个顺序串行执行;其中只有 Rule 内的规则列表,应直接按从上到下的顺序理解。不要为了“提高优先级”把 Host 段搬到文件最前面。

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

[Host]
example.com = 192.0.2.10

这段文本展示三个独立职责:General 选择系统 DNS,Rule 对示例域名与局域网地址作分流,Host 将示例主机名映射到文档保留地址。这里的地址只用于说明格式,不应作为真实服务配置。URL Rewrite 并非基础连接必需项,因此没有加入这份起点示例。用户只想调整分流时,应先保留其他段不动,减少同时改变多个变量造成的误判。

编辑前确认生效对象

进入 Config 后,先核对当前被选中的配置,而不是打开名称最相近的文件就开始修改。远程来源的配置、本地复制的配置与临时测试文件可以拥有相似名称,内容却不同。建议在已有配置的副本中实验,使用便于辨认的本地名称,并记录来源与修改意图。远程配置再次更新时,是否覆盖本地修改取决于保存方式;需要长期保留的规则应放在明确可维护的位置,不能假设所有手动改动都会被远程来源合并。

保存文本后,还要回到 Config 确认该文件已经选中;随后检查 Global Routing 是否为 Config。编辑成功只说明文本被保存,不说明每条新请求都已经按它处理。对于已经建立的连接,旧的处理结果可能继续存在,验证时应创建新的请求。若客户端报告解析错误,应先修复错误,再进行连通性测试,不要把不能载入的文件与上一次正常配置的结果混在一起。

文本格式与最小改动

规则通常以英文逗号分隔字段,选项通常以英文等号连接键和值。中文输入法产生的全角逗号、不可见空格以及从富文本复制的引号,都可能让看似相同的文本无法解析。建议使用纯文本编辑方式;一行只放一条规则,避免把解释文字直接追加为未知字段。本文代码块之外的中文说明不是配置内容,复制时不要连同章节编号或行号一起粘贴。

每次只修改一种行为,例如仅添加一条 DOMAIN 规则,再测试它对应的域名。若同时替换 DNS、加入重写、移动 FINAL 并更换服务器,即使结果发生变化,也无法确定是哪项改动起作用。可靠的维护记录应写清修改前的现象、修改的具体行以及验证结果,而不只是写“优化配置”。下一次回退时,这些信息比一份更长的规则列表更有用。

域名规则:精确、后缀与关键字如何选择

域名规则的输入是请求处理过程中可获得的主机名,不是浏览器地址栏里的整段 URL。把协议、端口或路径一并写进 DOMAIN,通常不会得到预期结果。例如,目标是 example.com 下的某个页面时,域名字段仍只写主机名;若确实需要按路径处理请求,应另外评估 URL Rewrite 的适用条件,不能让域名规则承担路径匹配的职责。

DOMAIN:只针对一个完整主机名

DOMAIN,example.com,DIRECT 表示对 example.com 这个主机名使用 DIRECT。它不会自动覆盖 api.example.com,也不应被理解为“整个网站的全部资源直连”。一个页面可能同时请求主域名、静态资源域名和接口域名;主页面能够打开,不等于所有请求都命中了同一条规则。需要精确处理某个接口时,DOMAIN 的范围容易核对,也便于在以后撤销例外。

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

这段片段先为 api.example.com 指定 DIRECT,再让 example.com 及其子域名走 PROXY。例外必须放在范围更大的后缀规则之前,否则请求会先命中后缀规则,精确规则没有机会参与。这里真正决定结果的是排列顺序,不是 DOMAIN 这个关键字天然比 DOMAIN-SUFFIX “更高级”。

DOMAIN-SUFFIX:覆盖域名与其子域名

DOMAIN-SUFFIX 适合希望统一处理一个域名族的场景。写成 DOMAIN-SUFFIX,example.com,PROXY 时,目标包括 example.com 与其下的子域名;不应把它写成带路径的形式,也不需要在开头加星号。后缀匹配按域名边界理解,不能仅凭字符串尾部相似就判断命中。维护时应选择真正需要覆盖的域名边界,避免为了少写几行而扩大到不相关的主机。

类型示例条件范围与检查重点
DOMAINapi.example.com完整主机名;适合单独例外。
DOMAIN-SUFFIXexample.com主域名与子域名;检查域名边界。
DOMAIN-KEYWORDexample主机名包含关键字;覆盖范围更宽。

DOMAIN-KEYWORD:范围宽,维护成本也更高

DOMAIN-KEYWORD 用来检查域名中是否包含指定文本。它不是对页面标题、搜索词或网页正文进行搜索。DOMAIN-KEYWORD,example,PROXY 可以表达关键字范围,但不能保证命中的主机都属于同一业务。关键字越短,越容易覆盖原本没有打算处理的请求。因此,有明确域名列表时优先用 DOMAIN 或 DOMAIN-SUFFIX;只有确实接受更宽匹配范围时,再使用关键字规则。

关键字规则尤其容易掩盖后面的例外。测试时不要只选一个预期会命中的主机,还应选择一个不应命中的对照主机,确认规则没有扩大作用范围。若关键字来自一份远程配置,应阅读它附近的规则与注释,确认是否存在配套例外。单独复制一行而不理解它原来的上下文,可能把原本受限的匹配变成全局范围的宽泛处理。

域名存在,不等于客户端一定拿到了域名

部分应用直接连接 IP,或者在应用内部完成地址选择;此时分流过程未必能取得可用于判断的主机名。若请求记录里只显示地址,不应立即认为 DOMAIN-SUFFIX 写错。先检查请求究竟是按域名发起,还是只带目标 IP;再决定是否补充地址规则。反向猜测 IP 属于哪个域名并据此下结论,容易在共享地址或动态解析场景中出错。

同样,网页跳转可能让第二次请求访问另一个主机;初始域名命中正确,后续资源仍可走不同策略。验证应围绕请求记录中的实际主机名展开,而不是围绕用户记住的网站名称。需要进一步理解宽规则与例外的关系,可继续阅读自定义规则、匹配顺序与 FINAL,然后回到本章逐一缩小匹配范围。

IP-CIDR、IP-CIDR6 与 GEOIP 的判断边界

地址规则判断目标地址,不判断网页的语言、用户所在位置或服务商名称。当一条请求没有命中前面的域名规则时,地址条件可以继续参与判断;如果更早的规则已经命中,后面的 IP-CIDR 或 GEOIP 就不会再为同一条请求重新选择策略。理解这点以后,才能区分“地址分类结果不符合预期”和“请求根本没有走到地址规则”这两种不同问题。

IP-CIDR:用网络前缀表达 IPv4 范围

CIDR 由地址与斜杠后的前缀长度组成。前缀越长,范围越小;192.168.0.0/16 表示一个私有地址范围,192.168.1.10/32 则只表示一个 IPv4 地址。不要把端口号写在地址字段里,也不要用连字符表达起止地址。针对本地设备设置 DIRECT 时,应先确认设备实际地址及所在子网,不要因为示例使用某段私有地址,就假设自己的网络一定属于该范围。

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
FINAL,PROXY

这组规则用来解释私有地址匹配,不是完整的本地网络通行清单。局域网访问还受系统网络权限、设备防火墙、监听地址和路由影响。命中 DIRECT 只是说明不通过所选代理转发,不能保证打印机、文件共享或本地服务一定可达。验证时应同时检查目标服务是否正在运行,以及同一网络里的其他设备能否访问。

no-resolve:避免仅为这条判断主动解析

地址规则末尾的 no-resolve 用于避免仅为了尝试匹配该规则而触发域名解析。它不是“禁用整个客户端 DNS”,也不是“忽略所有已有地址信息”。当请求本来就使用 IP,或处理过程中已经有可用地址时,仍可能参与相应的地址判断。因此,不能靠添加 no-resolve 来修复所有 DNS 问题,更不能把它当成强制让域名规则优先的开关。

给本地地址规则加上这一参数,通常是为了避免每个尚未解析的域名都仅因本地网段判断而引发额外解析。实际效果仍取决于请求进入规则阶段时掌握的信息。若目标是一个域名,却一直未命中本地地址规则,应查看解析结果与请求记录,而不是直接删除参数后把偶然变化当成最终结论。

GEOIP:地址数据库分类,不是业务归属

GEOIP,CN,DIRECT 按地址数据库中的地区分类选择 DIRECT。这里的 CN 是规则参数,不表示“中文网页”,也不表示“所有面向某地区的服务”。同一主机可能使用多个地址,内容分发网络也可能随访问网络改变解析结果。不同地址的分类未必相同;数据库记录与实际网络部署之间还可能存在时间差,所以应把 GEOIP 作为范围性条件,而不是精确的业务身份判断。

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

在这个片段里,example.com 先由域名规则决定去向,即使解析后的地址符合 CN 分类,也不会被后面的 GEOIP 改成 DIRECT。其他未命中域名规则的请求,才可能进入 GEOIP 判断。若有一个必须固定策略的业务,优先为已知主机建立清晰的域名规则,再让 GEOIP 处理剩余请求,维护时更容易解释结果。

IPv6 要单独检查,不能套用 IPv4 结论

IPv4 与 IPv6 是不同地址族。只写 IP-CIDR 并不等于已经覆盖 IPv6;需要表达 IPv6 前缀时使用 IP-CIDR6。域名同时返回两类地址时,应用最终采用哪一个地址,还受系统与网络条件影响。一次连接成功只能说明本次路径可用,不能证明另一地址族同样可用。排错应记录实际目标地址,再分别检查规则与网络连通性。

策略与 USER-AGENT:命中以后如何处理

规则条件决定“是否命中”,策略决定“命中以后做什么”。PROXY、DIRECT 与 REJECT 是三种不同处理结果,不是服务质量等级,也不代表协议名称。Shadowsocks、VMess、VLESS、Trojan、Hysteria2 与 WireGuard 描述连接方式;使用其中某种协议,并不会让规则里的 PROXY 自动获得额外优先级。维护配置时应把条件、策略与连接端点分开检查,避免用更换协议掩盖规则错误。

PROXY、DIRECT 与 REJECT

PROXY 将请求交给当前代理选择所对应的处理路径;是否能够完成连接,还取决于用户已有服务器信息、认证参数和服务端可用性。DIRECT 表示直接连接目标,不意味着该请求避开所有系统网络限制,也不意味着 DNS 行为必然与关闭客户端时完全相同。REJECT 用于拒绝匹配请求,适合明确需要阻止的目标;如果把业务必需的主机拒绝,应用可能表现为加载失败、反复重试或部分内容缺失。

Global Routing中文说明验证用途
Config配置:按当前配置处理。检查具体规则命中与最终策略。
Proxy代理:以代理模式处理请求。与 Config 对照,缩小规则问题范围。
Direct直连:以直连模式处理请求。与其他模式对照,检查目标直连情况。

Global Routing 的 Config、Proxy、Direct 是全局姿态,规则行中的 PROXY、DIRECT、REJECT 是配置内部策略,大小写与含义应分别阅读。想验证某条 Rule 是否起作用,应先选 Config;切换到 Proxy 后请求恢复,只能提示问题可能与配置分流或直连路径有关,不能直接证明某一行语法错误。完成对照测试后应恢复原来的模式,以免后续测试基于不同前提。

USER-AGENT 依赖可见的请求头

USER-AGENT 规则按可获得的 User-Agent 内容匹配,不是按应用图标、应用名称或系统进程名匹配。应用可以使用不同的请求头,也可以在更新后改变内容;相同头部还可能被多个程序复用。因此,把某个字符串当作应用身份的永久标识并不可靠。只有在已经观察到实际请求头、并确认客户端能在相应请求场景下读取它时,才适合使用此类规则。

[Rule]
USER-AGENT,ExampleClient*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

这里的 ExampleClient 是教学字符串,不代表真实应用。星号表达通配范围;如果请求头不可见,这条规则就不能按预想参与判断。加密连接中的 HTTP 头部通常不能仅凭普通转发读取,不能因为浏览器开发工具里能看到 User-Agent,就认定客户端规则阶段也一定能看到。不要为了验证一条 USER-AGENT 规则,直接扩大证书信任或开启不必要的流量解密。

策略正确,连接仍可能失败

请求记录显示 PROXY,只能确认路由选择,不代表远端已经完成认证、解析或连接目标。接下来应检查服务器地址、端口、认证方式与传输参数是否与用户已有服务信息一致。请求记录显示 DIRECT,也只能确认选择了直接路径;如果本地网络无法访问目标,改变规则名称并不会修复网络。记录显示 REJECT 时,则应先定位是哪条规则拒绝了它,而不是先测试服务器。

尤其在页面只加载一部分时,应将失败资源与成功资源分开观察。一个应用可以同时包含被 DIRECT、PROXY 与 REJECT 处理的多个请求;“应用能打开”不是完整验证,“应用打不开”也不是单一规则的充分证据。把实际主机、命中规则和策略逐项对应,才能确定需要调整的是条件范围、排列顺序还是连接参数。

对于日常维护,优先采用域名或地址条件来表达稳定的网络边界,把 USER-AGENT 留给能够明确验证的有限场景。规则越依赖请求内部细节,跨应用与跨平台复用时越需要重新测试。已有配置中如果出现不认识的自定义策略名,应先找到它的定义与引用关系;不要直接把名字改成 PROXY 后宣称配置已经等价,也不要假设任意名称都是客户端内置策略。

匹配顺序与 FINAL:先命中,不按具体程度重排

Rule 的核心规则是从上到下检查,先命中的规则决定处理策略。客户端不会先把所有匹配结果收集起来,再选看起来最具体的一条。精确域名、域名后缀、关键字与地址范围之间,也不存在可以替代行顺序的固定等级。排查“明明写了规则却不生效”时,第一步不是重复添加同样的条件,而是向上寻找已经覆盖这条请求的规则。

把明确例外放在宽泛条件之前

假设 example.com 及其子域名应走 PROXY,但 api.example.com 需要 DIRECT,正确结构是先写单独例外,再写后缀范围。如果反过来,api.example.com 已经在后缀规则处命中,后面的 DOMAIN 不会再次修改结果。这个原则同样适用于 REJECT:宽泛拒绝规则之前必须放置确有需要的例外,并确认例外没有比原计划覆盖更多主机。

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

逐行演算时,api.example.com 在第一行结束判断;blocked.example.com 在第二行被拒绝;其他 example.com 子域名在第三行走 PROXY。目标是私有地址且此前没有域名命中时,可能由第四行选择 DIRECT;剩余请求继续检查 GEOIP,仍未命中才走 FINAL。演算要使用实际请求条件,而不是只盯着希望它命中的那一行。

FINAL 是兜底,不是补丁

FINAL,PROXY 不带额外匹配条件,用来处理没有命中前序规则的请求,所以应放在 Rule 末尾。把 FINAL 提前,相当于在中途接走所有剩余请求,其后的普通规则便失去处理机会。FINAL 的策略应由用户明确选择:PROXY 与 DIRECT 代表不同的默认路径,不能仅凭别人配置的最后一行就推断哪种更适合自己的网络。

建议一份易维护的 Rule 只保留一个明确的 FINAL。合并两份规则时,常见错误是把第一份配置连同 FINAL 一起粘贴到第二份前面,于是第二份的大部分规则永远无法命中。合并后应先定位所有 FINAL,整理为唯一的末尾兜底,再检查重复规则与互相冲突的范围。不要只比较文件长度或规则数量来判断合并是否成功。

重复规则、冲突规则与看似合理的排序

完全相同的条件重复出现时,前面一条通常已经决定结果;后面即使使用不同策略,也不会成为“备用策略”。例如连续写两条相同 DOMAIN,先 DIRECT 后 PROXY,并不表示直连失败后自动代理。分流匹配不是连接失败后的重试流程。需要改变策略时,应修改真正先命中的那条,而不是在后面追加一个期望结果。

按字母顺序整理规则也可能改变语义。人类看起来整齐的排序,会把原来位于宽条件之前的例外移到后面;按规则类型分组也有同样风险。适合的维护顺序通常是先写明确例外,再写业务域名范围,再处理地址范围与地区分类,最后放兜底,但这只是便于审阅的组织方式,不是要求所有配置必须照抄的固定模板。

用命中表代替主观猜测

修改前可以列出三到五个测试目标,包括必须直连的主机、必须代理的主机、需要拒绝的主机以及一个应落入 FINAL 的目标。分别写下预期命中行,再用新连接验证实际结果。如果两者不一致,先查看实际主机和地址是否与预期相同,再逐行检查条件。这样既能发现顺序错误,也能发现网页跳转、资源域名变化或地址族差异。

当配置含外部规则引用时,还要考虑引用被检查的位置及其当前内容。引用名称相同不代表内容永远不变;更新后的范围可能覆盖原本依赖 FINAL 的请求。不能只审阅本地文件里能直接看见的几行。更完整的顺序示例可见规则优先级与 FINAL 专题;阅读后仍应回到当前生效配置中确认实际排列。

General 与 DNS:区分解析、选路和连接

General 处理配置的整体选项,不是把规则换一种格式集中书写。DNS、网络行为和平台相关参数可能在这里设置,但不同客户端界面与平台实现存在差异,不应把另一份配置里的全部字段直接搬入。一个无法识别的键值即使没有立即引发明显报错,也不能作为它已经生效的证据。先使用当前客户端能够确认支持的设置,再逐项增加确有需求的选项。

DNS 先解决“地址是什么”

域名解析把主机名转换为地址;规则决定请求的处理策略;连接阶段再尝试到达目标。这三个环节相关但并不相同。DNS 得到结果不代表目标可连接,PROXY 命中也不代表 DNS 一定经由同一条路径完成。遇到问题时,先问“有没有地址”,再问“选了什么策略”,最后问“连接在哪个环节失败”,比直接更换整份配置更容易定位。

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

dns-server = system 是使用系统 DNS 的起点示例,不表示它适合所有网络条件。它的价值在于先建立一个容易理解的基线:保留系统提供的解析方式,只检查规则是否按预期处理。若已有配置采用其他受支持的 DNS 设置,应记录具体参数和原来结果,再决定是否临时切回基线。不要在不知道原配置目的时直接清空 General。

解析结果会改变地址规则的输入

同一个域名可以返回多个地址,也可能因网络位置与缓存状态返回不同结果。域名规则以主机名为条件时,地址变化通常不改变域名条件本身;GEOIP 与 IP-CIDR 则直接依赖地址信息,所以结果变化可能影响命中。测试前后如果地址已经改变,不能把策略变化全部归因于刚刚移动的一行规则,必须同时记录当次目标地址。

此外,浏览器、应用、系统与客户端可能分别保留缓存或连接状态。修改 DNS 后立即刷新一次页面,不一定创建全新的解析与连接。可先结束目标应用当前活动,再发起新请求,并在客户端记录中确认出现了新的时间点与目标连接。不要反复清空所有数据来代替观察;如果无法确认缓存在哪里,应先保留现场,再按最小范围排查。

不要混淆本地解析与服务器侧解析

某些连接方式可以把主机名交给远端处理,另一些处理路径可能先在本地取得地址;具体行为取决于协议、配置与请求形态。不能仅看到 PROXY 就断言所有解析发生在服务器侧,也不能仅看到本地 DNS 记录就断言业务流量没有代理。应将 DNS 请求本身与后续目标连接分别核对,尤其不要把两条不同用途的请求当作同一条流量。

用户已有服务器信息中的服务器地址,也可能是域名。若这个地址无法解析,客户端可能连代理端点都无法建立,此时业务域名规则再准确也无法修复。排查链路应从服务器地址解析开始,随后检查端口与认证,最后检查目标站点。把服务器主机名与业务主机名写在不同记录行,能避免为一个问题反复修改错误的域名规则。

绕过选项与 DIRECT 不是同一个层级

General 中某些网络排除或绕过设置,可能使特定流量不进入通常的 Rule 判断路径;DIRECT 则是流量进入分流判断后的一种策略结果。若请求根本没有出现在预期记录里,应检查系统网络接管状态及相关绕过设置,而不是只在 Rule 里追加 DIRECT。具体字段应以当前客户端支持的设置说明为准,本文不把平台相关选项当作通用必填项。

维护 General 时,建议为每一项记录目的,例如“使用系统解析基线”或“保留已有本地网络行为”。不能解释用途的参数,先保留原值并在副本中单独测试,而不是照着更长的配置逐项补齐。字段多并不代表覆盖更完整;可解释、可验证、可回退,才是配置持续可用的基础。若基础连接尚未建立,应回到入门指南完成服务器与连接检查后,再调整解析行为。

Host 与 URL Rewrite:地址映射不等于请求改写

Host 与 URL Rewrite 经常同时出现在配置文件中,但作用对象不同。Host 改变指定主机名取得的地址映射;URL Rewrite 针对满足表达式的可见请求 URL 执行改写动作。两者都不能被理解成“换一个域名就能访问同样的服务”。目标服务器是否接受对应主机名、证书是否匹配以及应用是否跟随跳转,仍由实际连接与服务行为决定。

Host:固定映射必须有明确用途

[Host]
example.com = 192.0.2.10
api.example.com = 192.0.2.20

这份示例把两个主机名分别映射到文档保留地址,用来展示键值格式,不能直接用于真实访问。固定 Host 常用于用户自己掌握的测试环境;在没有确认目标地址用途时,不要为了“加速”随意填入网络上看到的地址。域名可能由多个后端提供服务,固定到单一地址可能绕过原有调度,也可能在地址调整后持续指向失效目标。

Host 映射通常不会把请求里的主机名改成地址字符串。请求仍可能携带原来的主机身份,TLS 校验也仍需要匹配相应域名。把域名映射到一台随意选择的服务器,不会让那台服务器自动提供原业务。若出现证书不匹配,应先核对地址与服务部署,不应通过忽略证书验证来掩盖映射错误。

Host 不替代 Rule 的选路判断

一个域名存在静态映射,并不等于它会自动 DIRECT。请求的策略仍需结合当前模式、可用主机名与地址规则判断。若希望某个自有测试主机固定地址并直连,应分别说明这两项意图:Host 提供地址,Rule 表达 DIRECT。将映射与策略分开书写,也能在测试结束后分别撤销,避免遗留一个难以发现的静态地址。

URL Rewrite:先理解正则,再选择动作

[URL Rewrite]
^http://example\.com/old$ http://example.com/new 302

这个例子对可见的明文 HTTP URL 作精确匹配,并以 302 动作将旧路径指向新路径。正则中的点需要转义,否则它表示任意字符;开头的脱字符与末尾的美元符号限制完整匹配范围。表达式只覆盖示例中的旧路径,不自动覆盖带查询参数或其他尾部内容的地址。匹配条件越宽,越容易把本来不应改写的请求一起处理。

302 是重定向语义,不是直接修改目标服务器上的文件,也不是永久迁移数据。客户端收到跳转后会产生后续请求,新请求可能重新参与分流,并受缓存、应用跟随行为与目标服务状态影响。若应用忽略跳转或只接受特定响应,浏览器中的成功测试不一定能代表应用内部调用也成功。

HTTPS 的边界不能省略

HTTPS 的路径与 HTTP 头部通常位于加密内容中,普通代理转发并不能直接查看完整 URL。因此,不能把上面的 HTTP 示例简单改成 HTTPS 就认定必然生效。涉及加密流量处理的功能有额外配置与信任边界,本页不将其作为基础分流的前提,也不建议为修复普通规则问题而先扩大证书信任。只需要按域名分流时,应优先使用域名规则。

重写也可能产生循环,例如新地址又被另一条表达式改回旧地址,或一个过宽表达式连自己的替换结果也再次匹配。测试时观察地址变化与连续响应,确认一次跳转后能够结束。应避免同时启用多份作用于同一目标的重写来源;难以解释每一条的用途时,先在副本中只保留一条,确认效果后再逐条恢复。

撤销时同时检查三处状态

移除 Host 后,已有解析缓存与连接可能暂时保留旧地址;移除 URL Rewrite 后,应用也可能保留跳转结果。完整撤销应包括恢复配置、建立新请求以及确认实际地址和路径。若问题依旧,不要马上重新添加更多规则,应先判断看到的是旧连接还是新行为。对正式业务,建议先在用户自己控制的测试主机上验证,再决定是否应用到日常配置。

组合配置与诊断:用一次只改一项的流程收尾

将前面各章组合起来时,目标不是得到规则最多的文件,而是得到能够解释每条关键请求的配置。先明确需要哪些例外,再确定默认处理策略;DNS 与 Host 只有在存在具体需求时才调整,URL Rewrite 则保持独立验证。开始前应确认用户已有订阅中的至少一个服务器能够正常使用,避免让服务器故障与分流问题相互干扰。

一份便于逐行核对的组合片段

[General]
dns-server = system

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

该片段表达精确例外、拒绝目标、后缀范围、本地地址、地区分类与最终兜底的组织关系,不包含代理端点,也不是可以代替订阅使用的连接信息。实际应用前,应把每一条条件与自己的目标对应起来;没有相应需求的示例规则不必保留。尤其是 REJECT,只有在确认目标确实需要被拒绝后才应加入正式配置。

先确认文件,再确认模式

  1. 在 Config 确认当前选中的文件,核对刚修改的规则确实存在于该文件中,并检查是否有解析错误。
  2. 把 Global Routing 设为 Config,记录当前选中的服务器,不要在同一次规则测试中同时切换服务器。
  3. 结束目标应用的旧连接后发起新请求,记录实际主机、目标地址、命中条件与处理策略。
  4. 把实际命中与预期行号比较;不一致时先向上查找覆盖条件,一致时再检查连接、解析与目标服务。

如果所有目标都表现为相同策略,应优先检查全局模式与 FINAL 位置;如果只有某个主机异常,优先检查精确域名、跳转后的主机以及地址变化;如果整个代理路径都失败,则先检查当前服务器信息与网络状态。不同范围的问题需要不同入口,不能一律通过新增 DOMAIN-SUFFIX 解决。

根据现象选择下一步

现象先检查下一步
保存后行为完全不变生效配置、Global Routing、旧连接选中正确文件并创建新请求。
例外一直不命中上方宽规则、实际主机名把明确例外移到覆盖规则之前。
命中 PROXY 仍失败端点、认证、服务器解析与已知可用路径对照测试。
只有部分资源异常失败资源主机、REJECT 规则逐个核对资源,不以主页面替代验证。
地址变化后策略改变GEOIP、IP-CIDR、地址族记录实际地址,必要时使用明确域名条件。

Connectivity Test 可以辅助判断端点是否响应,但它不是对某个网站完整请求链的替代验证。测试通过后,业务请求仍可能因域名解析、规则、认证细节或目标限制而失败。反过来,某种测试方式没有得到预期结果,也不应立刻证明全部业务连接都不可用。应把测试目标、测试方式与真实业务现象分别记录。

回退、更新与跨设备复用

每次修改完成后,至少验证一个预期命中目标和一个不应受影响的对照目标。出现回归时先回到上一份正常配置,确认问题确实随改动出现,再只恢复其中一项。远程配置更新后也应做同样检查,尤其关注新增宽规则、FINAL 位置与 DNS 参数。不能因为文件名称没变,就认为其行为没有变化。

跨设备复用时,优先迁移规则意图,再核对字段支持与网络环境。手机网络、家庭局域网和桌面网络的地址范围可能不同,系统网络接管能力也不同;同一文本并不保证所有设备产生相同记录。规则与配置可以作为参考,但平台相关参数应重新验证。获取与平台入口集中在下载页,基础连接流程见入门指南,常见现象可继续查阅常见问题。

描述问题时保留必要信息

一份可复现记录应包含当前模式、已选配置、脱敏后的相关规则、实际主机或地址、预期策略与实际策略,以及修改前后的差异。不要发送完整订阅链接、认证字段或包含私人数据的日志;若必须展示配置,只截取有关段落并移除凭据。对方能够逐行演算请求如何被处理,才有条件判断是顺序、参数还是连接问题。

最终检查可以归纳为三问:请求进入了哪份配置,最早命中了什么条件,命中后的连接在哪里失败。前两问属于配置解释,后一问属于网络与端点验证。按这个顺序保留证据,通常能避免把所有异常都归咎于“规则失效”,也能让下一次维护从已有结论继续,而不是重新替换整份文件。