[Reference]
Shadowrocket
规则与配置参考
[Scope]
这是 Shadowrocket 官方手册的系统查阅部分。第一次连接请先沿着使用教程完成导入、选择 Global Routing 与连接验证，再返回本页解释具体规则。本页不代替服务器参数说明；订阅链接从你的服务商处获取，已有服务器信息也应先核对可用性。
获取客户端请查看下载指南：iPhone / iPad 版在 App Store $2.99 一次性付费，系统要求以 App Store 页面标注为准；Mac（Apple 芯片与 Intel）、Windows、安卓、Linux 版免费，安装包由本站 /dl/ 提供。客户端一次性买断 ≠ 线路套餐，本站不提供节点或订阅服务。
[General]
配置文件结构与生效范围
Shadowrocket 的配置文件不只是域名列表。它把运行参数、请求分流、名称解析映射及 URL 处理放在不同段落，每个段头用英文方括号包围。阅读文件时，先找段头，再判断下一行属于哪类语法，直到遇到新的段头为止。不能因为两行都含有域名，就把它们放在同一段；例如 Rule 中的域名决定策略，Host 中的域名决定名称映射，两者作用不同。
从最小配置建立可验证的基线
已有可用服务器后，可以先用下面的片段理解结构。这里的 General 只说明是否绕过部分系统流量，Rule 则给出局域网与最终策略。它不是适用于所有网络的完整模板，也没有包含服务器认证信息。实际操作应复制当前 Config，保留原文件，再在副本内逐项修改；尤其不要为了套用一个示例而删除原先需要的 DNS、规则或网络相关参数。
[General]
bypass-system = true
[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
FINAL,PROXYbypass-system = true 会影响部分系统流量是否交由客户端处理，因此不能据此推断所有系统请求都会出现在连接记录中。规则日志只反映客户端实际接管且能够识别的请求。若某项系统功能没有记录，先确认其流量是否进入处理范围，再讨论 Rule 是否写错，不要直接加一条范围很大的域名规则。
区分文件、服务器列表与当前连接
Config 中的文件负责描述处理方式，Home 中已有的服务器负责提供连接目标。规则写成 PROXY 并不等于把服务器地址写进了配置，更不代表客户端已经选中了一个可用连接。排查时应分别核对当前启用的配置文件、Global Routing 的姿态和 Home 中的选中项。文件名相似或导入成功，都不足以证明本次请求正在使用刚编辑的内容。
编辑后先保存，回到 Config 确认选中的是目标文件，再按应用界面提示重新应用连接。对于远程配置，还要分清本地修改与上游更新之间的关系：重新下载可能覆盖本地编辑，另存副本则可能不再自动跟随原来的内容。建议给副本使用可辨认的用途名称，并在文件开头写明修改原因，而不是只用数字区分多个近似版本。
| 段头 | 主要职责 | 不能代替的内容 |
|---|---|---|
[General] | 设置整体运行及解析相关参数 | 服务器连接信息 |
[Rule] | 按顺序为请求选择策略 | 域名的固定地址映射 |
[Host] | 指定域名与地址的对应关系 | PROXY 或 DIRECT 策略 |
[URL Rewrite] | 按表达式处理可识别的 URL | 所有加密请求的内容读取能力 |
语法检查从字符和所在段开始
规则字段使用英文逗号，键值项常用英文等号，段名和策略名保持英文原文。中文标点、复制时带入的不可见字符、断行后的半条规则，都可能使内容无法按预期解析。建议每行只写一个有效条目，说明文字另起一行以 # 开头；不要把说明夹在字段中间，也不要把网页展示用的行号复制进文件。
一份能够保存的文件不一定符合实际意图。保存只解决文本和语法层面的问题，真正生效还取决于当前文件、当前模式、流量接管范围及服务器状态。维护时保留一份能够正常访问的基线，每次只改变一类设置，再用同一请求复测。这样失败时可以明确回退到哪一步，不必同时追查多个段落的变化。
[Rule]
域名规则的范围与边界
域名分流适合表达“这个服务走哪种策略”，但必须先选对匹配范围。Rule 中常见的三个域名关键字是 DOMAIN、DOMAIN-SUFFIX 和 DOMAIN-KEYWORD。它们都不是完整 URL 匹配：不能把协议头、路径、查询参数和端口一起塞进域名字段，也不能用浏览器地址栏的整段内容替代主机名。判断时应先把请求拆为协议、主机、端口和路径，再提取主机部分。
DOMAIN：只处理指定的主机名
DOMAIN,example.com,PROXY 表达的是对指定域名的匹配，不自动扩展到 api.example.com。需要为单独主机保留例外时，DOMAIN 比宽泛规则更便于审阅。例如同一个服务的主站与文件接口可能采用不同策略，先把确切主机单独列出，便能避免后面整站规则吞掉例外。域名通常不区分大小写，但维护时统一小写有助于去重。
[Rule]
DOMAIN,files.example.com,DIRECT
DOMAIN,api.example.com,PROXY
DOMAIN,example.com,PROXY
FINAL,DIRECT这个片段只覆盖列出的三个主机，其他名称走 FINAL。若页面仍缺少图片或接口数据，原因可能是页面引用了未列出的其他域名，而不是 DOMAIN 没有生效。打开一次页面往往产生多组连接，验证时应把失败资源的主机与主文档主机分开，不要仅凭地址栏中的一个名称判断所有资源的走向。
DOMAIN-SUFFIX：覆盖根域及其下级域名
当同一域名体系下的服务需要采用相同策略，可以使用 DOMAIN-SUFFIX,example.com,PROXY。它覆盖 example.com 及其下级域名，例如 api.example.com，不应理解成随意的字符串结尾测试；otherexample.com 不是 example.com 的下级域名。规则字段只写域名后缀，不加前导星号，也不写 https://。
[Rule]
DOMAIN,local.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT这里的确切主机放在后缀规则之前，因此 local.example.com 可以保留 DIRECT，其余匹配该后缀的请求走 PROXY。如果把两行颠倒，后缀规则就会先处理这个主机，后面的例外不会再有机会。规则并不会自动比较哪一条更精确；“精确规则在前”是文件作者安排出来的效果。
DOMAIN-KEYWORD：宽泛匹配需要额外审阅
DOMAIN-KEYWORD 对域名中的关键字进行匹配，不以某个域名所有权边界为依据。例如 DOMAIN-KEYWORD,example,PROXY 可能覆盖多个包含 example 的名称，而不只 example.com 这一组。它适合明确需要宽范围匹配的情况，不宜仅因为写起来简短就替代 DOMAIN-SUFFIX。关键字越短，越容易命中与原意无关的目标。
| 规则 | 示例字段 | 适用意图 |
|---|---|---|
| DOMAIN | api.example.com | 仅指定主机，便于建立例外 |
| DOMAIN-SUFFIX | example.com | 根域与下级域名采用同一策略 |
| DOMAIN-KEYWORD | example | 匹配包含关键字的多组域名 |
观察域名来源，而不是猜测网站归属
客户端能否按域名匹配，取决于本次连接是否具有可用的域名信息。应用直接连接 IP、复用已有连接，或采用独立解析方式时，记录中的信息可能与浏览器输入不同。先检查请求记录展示的目标和命中规则，再决定使用域名还是 IP 条件。不要为了让一个应用整体走代理而用过短的关键字扩大范围，这通常会引入难以解释的旁路影响。
对于国际化域名，界面显示的字符与实际请求使用的编码形式可能不同，排查时应以记录中的主机名为依据。也不要把搜索结果跳转链接当成最终站点：一次跳转可以涉及多个域名，每次新连接分别接受规则判断。若需求就是“指定网站走 PROXY，其余 DIRECT”，可继续阅读DOMAIN-SUFFIX 与 FINAL,DIRECT 的场景说明，先建立明确的域名清单再扩展范围。
[IP]
IP、GEOIP 与 USER-AGENT
域名规则用于服务名称，IP 规则用于目标地址范围。两者不是互相替代的写法：同一个域名可能解析到多个地址，同一个地址也可能承载多个服务。如果实际需求是稳定地指定某个网站，优先考虑域名条件；如果需求是让办公室网段或某台设备直接连接，则 IP-CIDR 更容易表达清楚。选择条件前，先明确要控制的是“名称集合”还是“地址集合”。
IP-CIDR 与前缀长度
IPv4 CIDR 由网络地址与斜线后的前缀长度构成。前缀越长，覆盖的地址越少；/32 表示单个 IPv4 地址，192.168.0.0/16 表示一个较大的私有地址范围。不要把端口放进 CIDR 字段，也不要用域名替代网络地址。若只需处理一台设备，应写明确地址，而不是为了省事覆盖整个私有网络。
[Rule]
IP-CIDR,192.168.1.20/32,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR,172.16.0.0/12,DIRECT
FINAL,PROXY以上三组较大的范围是常见私有 IPv4 地址空间，并不代表当前网络真的使用了它们。实际网络若存在重叠路由、远端内网或专用访问要求，需要按自己的地址规划调整。规则选择 DIRECT 只表示不经代理策略，不能替系统建立不存在的路由，也不能让没有网络权限的地址变得可达。
IP-CIDR6 与双栈请求
IPv6 使用 IP-CIDR6，例如 IP-CIDR6,fd00::/8,DIRECT。不要把 IPv4 和 IPv6 地址放进同一个关键字后。设备可能同时获得两种地址，应用也可能优先连接其中一种；因此只修正 IPv4 规则，不一定能改变实际连接走向。测试时应看本次使用的地址族，而不是只看某一次 DNS 查询的结果。
[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR6,fd00::/8,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY这段配置表达不同地址条件的组合，并不承诺处理所有局域网环境。IPv6 的链路范围、网络接口及系统路由另有约束。若记录中出现 IPv6 目标而配置只有 IPv4 条目，应先确认预期，再补充具体范围；不要把整片地址空间全部 DIRECT 当成通用修复办法。
GEOIP 判断的是地址归属数据
GEOIP,CN,DIRECT 以客户端使用的 IP 归属数据库判断目标地址，并不是识别网页语言、域名注册地或账号地区。内容分发网络可能在不同地点返回不同地址，数据库本身也可能与实际部署存在差异。因此 GEOIP 适合作为宽范围策略的一部分，不适合作为某个网站归属的唯一证据；重要服务可以在它前面放置明确域名规则。
域名请求遇到需要目标地址的规则时，可能涉及解析过程。可选的 no-resolve 用于避免该 IP 规则为匹配域名额外触发解析，例如 IP-CIDR,192.168.0.0/16,DIRECT,no-resolve。它不等于关闭整个应用的 DNS，也不代表已知 IP 不再匹配。是否使用应根据解析意图决定，不能把它当成一项总能提升速度的开关。
USER-AGENT 的可见性限制
USER-AGENT,ExampleApp*,DIRECT 按可获取的 User-Agent 信息匹配，其中示例星号用于匹配后续字符。这里匹配的是请求标识，不是操作系统里的应用安装包名称。多个程序可能使用相同标识，一个程序也可能在不同请求中发送不同标识，因此它不能被当成可靠的进程分流替代品。
对于加密请求，客户端不一定能够读取 HTTP 请求头。仅在 Rule 中加入 USER-AGENT，并不会自动获得这些内容，也不应为此盲目改变证书相关设置。如果记录里没有相应字段，应先承认信息不可见，再使用可观察的域名或地址条件。需要访问路径或请求头才能表达的需求，应与普通连接分流分开评估，避免规则看似完整却从未有机会命中。
[Policy]
策略与 Global Routing 的关系
规则先回答“是否命中这个条件”，策略再回答“命中后如何处理”。PROXY、DIRECT、REJECT 是策略名称，不是协议类型，也不是服务器地址。Shadowsocks、VMess、VLESS、Trojan、Hysteria2、WireGuard 等名称描述连接方式；同样写成 PROXY 的规则，可以通过当前可用的代理连接执行。不能靠把策略名改成某个协议名来完成服务器配置。
PROXY：将请求交给当前代理路径
当规则选择 PROXY 时，需要有已配置并可用的代理目标。地址、端口、认证、传输与 TLS 等参数是否正确，属于连接配置问题；域名是否命中这条规则，属于分流问题。两者可以分别成立或失败：日志显示命中 PROXY 但网页仍失败，不代表规则无效，也可能是选中服务器不可达、认证错误或服务器无法连接目标。
先通过 Home 核对选中项，再使用 Connectivity Test 辅助判断连通性。测试结果只说明对应测试条件下的表现，不保证所有网站、端口或协议都能成功。若需要检查 Trojan 的密码、SNI 与 TLS 字段，可以阅读Trojan 参数逐项说明；不要把远端认证失败用增加域名规则的方式掩盖。
DIRECT 与 REJECT 的边界
DIRECT 表示目标连接不经代理策略，仍然受到本地网络、系统权限、DNS、路由及目标服务的影响。直连失败并不能证明必须改用代理，也不能证明客户端拦截了请求。REJECT 则用于拒绝匹配的请求，适合已确认需要阻止的目标；它不是“自动换一条连接”，也不是在代理失败时临时回退的意思。
[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,internal.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT这个示例把拒绝条件放在前面，内部服务其次，后缀规则再处理其余下级域名。REJECT 之后客户端如何向具体应用呈现失败，可能受请求类型影响，因此不应拿错误页面样式判断有没有命中。更可靠的依据是目标、策略和规则记录是否一致。
Global Routing 的三种姿态
Global Routing 的配置 / 代理 / 直连，对应界面词 Config / Proxy / Direct。Config 按当前配置文件进行分流，是验证 Rule 的主要姿态。Proxy 与 Direct 用于将处理范围内的连接整体导向代理或直连路径，不能继续假设普通 Rule 会按 Config 的方式逐条执行。这里的整体也受系统接管范围约束，并不表示设备上任何流量都一定经过同一条路径。
| 姿态 | 主要用途 | 验证时注意 |
|---|---|---|
| 配置 · Config | 按当前 Config 选择策略 | 确认选中正确文件及命中行 |
| 代理 · Proxy | 检查代理路径整体表现 | 不能据此证明域名规则有效 |
| 直连 · Direct | 对照本地网络访问表现 | 不等于停用所有系统网络设置 |
模式对照用于定位，不用于同时修改
如果 Config 失败而 Proxy 成功，可以怀疑分流方向或解析路径，但仍需查记录确认；如果两者都失败，应先检查代理连接和目标服务，而不是立即扩大 Rule。若 Direct 成功、Proxy 失败，则需要核对代理端是否支持这个目标及端口。每次切换姿态后重新发起请求，避免把旧连接复用后的结果误当作新模式的表现。
On Demand 决定何时按网络条件发起连接，与某个域名最终命中 PROXY 还是 DIRECT 不在同一层。自动连接已经触发，不等于策略已经正确；自动连接没有触发，也不能靠 Rule 修复触发条件。将连接开关、Global Routing、Config 与服务器选择分成四项检查，能显著缩短排查路径。相关界面术语可在术语手册继续查阅。
[Priority]
匹配顺序与常见规则写法
Rule 的关键原则是从上到下检查，先命中的有效条件决定处理策略。它不会先收集所有命中项，再挑选看起来更具体的那条，也不会因为某一行写在后面就自动覆盖前面。整理文件时应把明确例外放在宽泛条件之前，把 FINAL 留在结尾。理解这一点，比记住更多关键字更重要，因为很多“规则失效”实际上只是前面的范围已经覆盖了目标。
指定域名走 PROXY，其余 DIRECT
这种写法适合代理范围明确、希望其他请求沿本地网络访问的情况。先列出确切例外，再放域名后缀，最后使用 FINAL,DIRECT。它不会自动发现一个网站依赖的全部服务；如果登录、图片或接口使用其他域名，需要根据请求记录逐项确认。不要仅因某个页面不完整，就把范围扩大成 DOMAIN-KEYWORD 或把 FINAL 改成 PROXY。
[Rule]
DOMAIN,local.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-SUFFIX,example.net,PROXY
FINAL,DIRECT测试时至少准备三类目标：一个应该走代理的主机、一个应该保留直连的例外、一个完全不在清单中的主机。分别检查它们的命中规则与策略，才能验证整个意图。只测试 example.com 成功，无法证明 local.example.com 的例外或 FINAL 的方向也正确。
私有地址直连，其余 PROXY
另一类配置先保留本地设备访问，再将其他请求交给 PROXY。这里的“其余”非常广，包括未列出的业务域名和应用连接，因此应先确认服务器可用，并理解远程连接带来的路径变化。私有地址条目也应符合实际网络；如果你的业务需要通过代理访问远端同名私有网段，通用的局域网直连规则可能与目标冲突。
[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR,172.16.0.0/12,DIRECT
IP-CIDR6,fd00::/8,DIRECT
FINAL,PROXY这个片段不加入 GEOIP，目的是让意图保持清楚。如果再插入 GEOIP,CN,DIRECT，它就变成另一套范围更宽的分流方案。两者都可以表达需求，但不能把新增条件当成不改变行为的装饰。每一行都应该有可说明的作用，并对应一组可验证的请求。
FINAL 不是网络失败后的备用路线
FINAL 的含义是前面的条件都没有命中时采用此策略，不是前面连接失败后改走它。请求一旦命中 PROXY，随后出现超时，通常不会继续向下尝试 FINAL,DIRECT。若希望设计可用性切换，需要单独理解相应策略配置，不能靠并排写多条 FINAL 实现。日常维护中保留一个清晰的 FINAL，比堆叠多个相同关键字更容易审查。
[Rule]
# 先保留单个主机的例外
DOMAIN,download.example.com,DIRECT
# 再覆盖其余下级域名
DOMAIN-SUFFIX,example.com,PROXY
# 最后处理前面未命中的请求
FINAL,DIRECT合并配置时先消除遮蔽关系
把两份规则复制到一起之前，先比较各自的 FINAL、广域名条件和大范围 IP 条目。第一份的 FINAL 如果留在中间，第二份即使语法正确，也可能根本不会被检查。同样，一条覆盖整个 example.com 的后缀规则可以遮蔽下方多个单独主机；重复条目则让维护者误以为后面的修改已经生效。
建议按“明确拒绝、具体例外、服务域名、地址范围、区域条件、最终策略”的思路审阅，但这只是整理方法，不是客户端强制的优先级。若你的业务需要某个 IP 条件先于域名条件，就应明确调整顺序并留下说明。不要机械地按关键字字母排序，因为排序会改变首次命中的结果。
对于共享服务，尤其不要用一次解析得到的 IP 替代长期域名规则。地址可能变化，也可能同时承载无关业务；将其放在前面会改变其他请求。记录修改前后的差异，并保留能够回退的文件，是维护复杂配置时比“条目越多越完整”更可靠的做法。常见现象的进一步分支可查常见问题。
[Host]
Host 映射与 DNS 路径
Host 与 Rule 经常出现在同一份配置中，但解决的问题不同。Host 指定某个名称应对应哪个地址，Rule 决定请求采用哪个策略。把域名映射到一个 IP，不等于指定 DIRECT；把域名写成 PROXY，也不等于固定它的 DNS 结果。排查域名访问问题时，应把“名称怎样得到地址”和“连接怎样到达目标”分开，否则容易在错误的段落反复修改。
静态映射的基本写法
下面的 Host 示例使用文档地址，展示等号两侧的结构。左侧是完整主机名，右侧是目标 IP；它既不包含协议头，也不包含 URL 路径。应用到真实环境时，应替换成自己确实管理或获准使用的目标地址。不要直接拿示例地址进行连通性测试，也不要把一个来源不明的地址永久固定到常用服务。
[Host]
portal.example.com = 192.0.2.20
[Rule]
DOMAIN,portal.example.com,DIRECT
FINAL,PROXY这里用 DOMAIN 明确选择 DIRECT，再用 Host 指定地址，便于分别解释两个决定。目标即使成功解析到 192.0.2.20，也不代表它可通过当前网络连接。路由、端口监听、访问权限和服务端状态仍然需要成立。实际测试应使用你拥有的有效地址，记录显示映射生效与业务访问成功是两个检查点。
固定地址不会改写证书对应的名称
HTTPS 访问仍然以原域名进行身份验证，服务器通常还会根据 SNI 选择证书与站点。Host 只是改变地址对应关系，不能让错误的证书变得匹配，也不能让不承载该域名的服务器提供正确内容。如果映射后出现证书错误，应核对服务器是否真的为该域名提供服务，而不是通过放宽证书验证来掩盖地址不正确的问题。
同理，浏览器直接访问 IP 与通过域名加 Host 映射访问，不一定获得相同结果。请求中的主机信息可能不同，服务器上的虚拟站点也可能不同。排查时应保持原始域名和访问路径不变，只改变计划验证的那一项映射；否则多项差异叠加后，无法知道究竟是哪项改变带来了结果。
General 中的解析参数要单独核对
General 可以包含 DNS 相关设置，例如 dns-server = system 表示使用系统解析来源。它是理解默认路径的一个简洁示例，不意味着所有环境都必须采用这个值。网络本身、应用独立解析行为和代理端处理方式，都会影响最终可观察到的过程。不要把更换解析服务器视为适用于任何故障的统一措施。
[General]
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT这个片段没有静态映射，便于与 Host 方案做对照。若旧映射仍在生效，修改 DNS 服务器可能不会改变该主机对应的地址；若应用复用已有连接，重新查询 DNS 也未必改变当前连接。应先确认有无 Host 条目、是否创建了新连接，再判断解析设置有没有作用。
缓存、应用解析与多地址结果
DNS 结果可能存在于系统、客户端或应用的缓存中，网站连接也可能长期复用。修改后立即刷新一个页面，不一定能触发完整的新解析过程。可先停止正在进行的任务，重新应用连接，再重新打开目标；必要时按应用提供的缓存操作处理。不要为了清除一个目标的旧结果，顺手重置所有配置与网络设置。
如果同一名称同时返回 IPv4 与 IPv6，固定其中一种地址或只检查一种查询结果，都不足以证明全部连接已经遵循预期。以连接记录中的实际地址为准，分别核对地址族、命中规则及策略。涉及内网名称时，还应在原网络与另一个网络分别测试，因为离开办公室后，原有 DNS 搜索域和私有地址路由可能都不再存在。
维护时为每条固定映射写清用途，并定期确认服务端仍接受该域名。若临时排查已经结束，删除不再需要的映射并恢复基线，避免几个月后把地址过期误判为规则故障。对不可观察的请求，不要只凭猜测增加 Host；先收集请求主机、目标地址和错误类型，再选择修改位置。
[URL Rewrite]
URL Rewrite 的表达式与边界
URL Rewrite 处理可识别的 URL，与 Rule 中按主机或地址选择连接策略不同。它适用于明确的地址改写或跳转需求，不应当被当成整个应用的分流开关。添加之前先问清楚：需要改变的是连接路径、名称对应的地址，还是请求 URL 本身？前两类需求分别优先考虑 Rule 与 Host，只有第三类才进入本节的处理范围。
从可观察的 HTTP 跳转开始
下面的片段把匹配到的明文 HTTP 地址重定向到同域名的 HTTPS 地址，使用 302 表示临时跳转。它只展示语法结构，不用于证明目标站点具备 HTTPS 服务。表达式左侧匹配原地址，中间给出替换目标，最后写处理方式；各部分之间的空格用于分隔字段，不要换成中文标点。
[URL Rewrite]
^http://example\.com/(.*) https://example.com/$1 302^ 把匹配限制在字符串开头，\. 表示域名中真实的点，(.*) 捕获后续内容，$1 在替换目标中引用第一组捕获。若把域名的点直接写成正则中的任意字符，表达式的范围就比预期更宽。若漏掉捕获引用，原路径也可能丢失，最终跳转到不同页面。
限制主机与路径，避免扩大匹配范围
更稳妥的规则通常明确限定协议、主机和路径前缀，而不是对所有包含某个单词的 URL 进行替换。域名中的关键字和路径中的关键字可能同时出现，缺少锚点的表达式也可能在查询参数里意外命中。编写时准备一个应该匹配的地址，再准备几个相似但不应匹配的地址，用边界案例验证，而不是只看一个成功样本。
[URL Rewrite]
^http://example\.com/old/(.*) https://example.com/new/$1 302这个示例只处理指定主机下的 old 路径前缀，不把其他站点或其他路径一起改写。原地址如果含有查询参数，也要核对捕获后的替换结果是否符合预期。包含登录状态、临时授权或提交动作的 URL 尤其需要谨慎，因为改变路径或重定向方式可能影响服务端对请求的解释。
HTTPS 可见性不是由一行规则自动取得
HTTPS 将请求内容置于加密连接中，URL 的完整路径与请求头不一定能够被客户端直接读取。规则中写入 HTTPS 表达式，不代表它就能对所有加密请求执行。是否具有可处理的信息，取决于实际连接方式与相关设置。不要把添加 Rewrite 与获得内容可见性混为一谈，也不要为了让一个示例命中而盲目启用证书相关操作。
部分应用可能采用额外的证书约束或独立网络实现，浏览器中有效的处理方式未必能直接推广到它们。若你只是要让某个站点走 PROXY，域名 Rule 就能表达这一意图，没有必要读取加密内容。将目标限定在必要的连接层，能减少额外依赖，也更容易复核配置的影响范围。
跳转循环与缓存导致的误判
如果客户端把 A 改到 B，而服务器又把 B 跳回 A，就会形成循环。症状可能是反复加载、跳转次数过多或页面无法完成，而不是清晰地指出某条 Rewrite。排查时先停用新增的单条改写，保持 Rule 不变，观察循环是否消失；不要同时切换 Global Routing，否则无法确定是哪项变化影响了结果。
浏览器还可能记住服务端跳转或严格传输策略，导致明文地址在发出前就被升级为 HTTPS。此时看不到 HTTP 规则命中，并不一定是表达式语法错误。验证应使用可控测试地址及新的访问过程，同时观察实际请求的协议与跳转链。对正式业务提交操作，不应反复重放来试验规则，以免产生重复动作。
Rewrite 与 Rule 可能在同一次访问中共同出现：原地址被改写后，新的请求还要按其实际目标进行连接处理。因此“最终走哪条策略”应查最终请求，而不是只查最初输入的 URL。维护时为改写记录业务目的、预期输入和输出，测试完成后删掉临时条目。涉及身份认证或付款等敏感流程时，应保留服务原有地址行为，不把通用示例直接套入实际业务。
[Diagnostics]
验证、维护与故障定位
验证一份配置，需要同时证明“匹配了预期条件”和“连接沿预期路径完成”，只看到页面打开不够。页面可能来自缓存，也可能由已有连接加载；测试工具显示可连接，也不等于目标业务接受了请求。建议固定一个可重复的测试动作，每次仅改一项设置，并保存目标主机、目标地址、命中行、策略与结果这几项事实。
按固定顺序核对六个检查点
- 确认客户端连接已经启用，且当前网络没有刚刚发生切换。
- 检查 Global Routing 是否为本次测试需要的 Config，而不是遗留的 Proxy 或 Direct。
- 在 Config 中确认当前选中的文件，打开后核对修改内容已经保存。
- 检查 Home 中选中的服务器，分别确认连接参数与基本连通性。
- 重新发起目标请求，读取实际域名、地址及命中策略，排除旧连接复用。
- 只修改与观察结果直接相关的一处，再用相同动作复测并记录差异。
这套顺序把连接层与规则层分开。若第一步就不成立，继续修改 DOMAIN-SUFFIX 没有意义；若当前文件不对，语法再正确也不会影响请求。对于不熟悉导入流程的用户，先回到使用教程建立一次成功连接，再开始细化规则，比在空配置上同时调服务器和分流更容易判断。
按现象选择排查分支
| 观察结果 | 先检查 | 不要立即采取 |
|---|---|---|
| 目标没有对应记录 | 接管范围、缓存及连接复用 | 不断添加重复域名规则 |
| 出现记录但命中 FINAL | 实际主机、字段与规则顺序 | 只凭地址栏判断域名 |
| 命中 PROXY 后超时 | 选中服务器与远端可达性 | 把 FINAL 当成失败回退 |
| 主页面正常但接口失败 | 失败资源的独立目标及策略 | 把整个应用归为一个域名 |
| 改 Host 后证书错误 | 目标地址、证书与 SNI 对应关系 | 放宽验证来掩盖地址错误 |
当记录显示命中非预期规则时，沿文件向上查第一个覆盖条件；当记录已经显示预期策略时，转向连接与目标服务检查。若同一域名的不同请求表现不一致，还要比较地址族、端口、实际地址与连接创建时间。不要把这些不同条件混合为“有时规则有效、有时无效”这一句结论。
用一份小配置复现，而不是整份删除
复杂文件难以定位时，复制当前配置，在副本中保留必要的 General、一个目标条件与一个 FINAL，逐步复现。原文件留作回退，不直接清空。下面的片段适合检查某个域名条件是否能够命中；使用时将测试目标替换成已有服务，不应把 example.com 的访问结果当成自己的服务器状态。
[Rule]
DOMAIN,api.example.com,PROXY
FINAL,DIRECT如果最小片段符合预期，再逐组恢复原来的规则，每次观察何时出现差异。这样可以找到遮蔽条目、过宽关键字或提前出现的 FINAL。恢复过程中也要保持 General 与解析条件一致，否则行为变化可能来自 DNS 路径，而不是刚加回的 Rule。不要用一次成功就宣布全文件正确，应覆盖代理、直连、拒绝和兜底各类样本。
订阅更新与本地配置分开维护
Subscribe 更新主要涉及已有服务器信息，Config 更新涉及规则与处理方式；两者可能来自不同位置，也可能有不同刷新行为。更新后先核对到底变了哪一部分，不要默认服务器列表刷新就会同步修正本地规则。订阅链接从你的服务商处获取，单条分享链接与订阅的差别可在分享链接格式说明查阅。
配置、导出文件与日志可能包含服务器地址、账号信息或带授权参数的链接。向他人描述故障时，只保留必要的规则和经过处理的记录，移除认证字段与完整订阅地址。规则示例中的域名可以公开讨论，真实访问记录却可能暴露使用习惯；分享前应逐项检查，而不是直接发送整份配置。
完成修改后的回归检查
最后分别在常用网络下检查目标服务、局域网访问及其他原本正常的应用，确认新增规则没有扩大影响。若设置了 On Demand，还应单独验证网络切换后的连接触发，不把它与域名命中混测。保留修改前文件、修改说明和几个测试样本，后续出现变化时才能区分配置问题、服务器变化与目标服务调整。
本页负责解释配置原理与规则边界；安装和获取渠道归入下载指南，常见错误提示归入常见问题，术语含义归入术语手册。遇到新现象时，先收集可观察事实，再选对应章节复核。配置维护的目标是每条规则都有明确目的、每次修改都能验证、每个失败都能回退，而不是持续增加文件长度。