Shadowrocket 配置文件 .conf 结构详解:General、Rule、Host、URL Rewrite 各段作用

按段拆解 .conf 配置文件:General 管全局行为,Rule 管分流,Host 管本地映射,URL Rewrite 管地址改写,说明各段写法与生效顺序。

本文速览

Shadowrocket(小火箭)的 .conf 文件不是节点清单,也不是按行执行的脚本。本文适合已经有自己的服务信息、需要阅读或修改配置的用户:先区分四个配置段的职责,再通过规则样例、模式对比和验证步骤,判断修改应放在哪里,以及保存后为何可能没有生效。

一、.conf 的段落结构与读取边界

配置文件以方括号标记段名,例如 [General]。从这个段名开始,到下一个段名之前的内容属于同一段。段内语法并不统一:General 常见的是键值对,Rule 是逗号分隔的匹配规则,Host 是主机名与地址映射,URL Rewrite 则使用匹配表达式和处理动作。不能把一种段落的写法直接移到另一段。

以下是阅读结构的最小示例,不包含代理服务器参数,也不保证适合当前网络。两个文档示例域名用于讲解匹配行为,不应作为真实业务连通性测试目标。以 # 开头的独立行是注释;注释不会建立连接,也不会改变策略。

# 结构示例:使用前先备份当前配置
[General]
dns-server = system

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

[Host]
example.com = 192.0.2.10

[URL Rewrite]
^http://example\.org/(.*)$ https://example.org/$1 302
4 个段
General / Rule / Host / URL Rewrite,分别承担不同职责
3 种策略
本文规则使用 PROXY / DIRECT / REJECT
1 条兜底
示例的 FINAL 位于 Rule 最后一行

段落排列顺序不等于请求处理顺序。把 Host 写在 Rule 后面,不代表必须先分流再查 Host;把 URL Rewrite 移到文件开头,也不会令所有网络连接先执行改写。各段由对应功能读取,只有 Rule 内部的规则顺序具有这里所说的“自上而下,命中即停”的分流含义。

二、General:全局选项不是分流规则

[General] 承载配置级的通用行为,例如 DNS 相关选项。示例中的 dns-server = system 表示采用系统 DNS 设置。它不表示“所有连接直连”,也不表示“所有域名走代理”;连接策略仍要结合 Global Routing、Rule 和当前可用的代理设置判断。

编辑这一段时,应保留选项名原文,并核对值的类型。布尔值、地址列表和文本参数不能互换。不要为了套用其他文件而一次替换整段:已有配置中的网络例外、DNS 行为或其他通用设置可能因此变化,最终表现为局部应用异常,而不是明显的语法报错。

General 阅读要点

段名
[General]
键名示例
dns-server
赋值示例
dns-server = system
检查对象
当前选中配置中的通用选项

先确认每个键的用途,再决定是否修改;不依靠段落位置推断优先级。

应用设置边界

分流姿态
Home → Global Routing
配置选择
Config → 当前使用的配置文件
自动连接
Settings → On Demand
代理参数
Home → 用户已有的服务器条目

On Demand 决定连接触发条件,不是 Rule 的替代品,也不是配置段的执行开关。

常见误区是修改 General 后,又在 Settings → On Demand 中调整自动连接条件,随后无法判断是哪项改变了结果。验证配置时先固定连接状态和网络环境;自动连接行为应另行测试。本文路径以 Home、Config、Settings 界面组织为参照,不同平台的按钮布局可能不同。

三、Rule:按顺序匹配,FINAL 放在末尾

[Rule] 决定符合条件的请求采用什么策略。一般规则由类型、匹配值、策略组成;FINAL 不需要匹配值。PROXY 将请求交给代理路径,DIRECT 使用直连路径,REJECT 拒绝请求。PROXY 本身不会创建可用服务器,仍需要用户已有且可连接的服务信息。

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT,no-resolve
FINAL,PROXY
规则类型示例含义检查重点
DOMAIN只匹配 api.example.com 这个完整域名。不包含其他子域名。
DOMAIN-SUFFIX匹配 example.com 及其子域名。更具体的例外应放在它前面。
IP-CIDR匹配 192.0.2.0/24 地址段。no-resolve 避免仅为该规则触发域名解析。
GEOIP按地址归属数据库判断是否属于 CN。依据 IP 数据,不依据网页语言或域名后缀。
FINAL前面的规则均未命中时采用 PROXY。放在末尾,避免提前截住后续规则。

按上面的排列,api.example.com 首先命中 DOMAIN,因此采用 DIRECT;www.example.com 跳过第一行,随后命中 DOMAIN-SUFFIX,采用 PROXY。这是依据规则推导的预期结果,不是对示例域名进行网络实测的记录。如果把后缀规则放在最前,完整域名例外便不会被执行。

no-resolve 不等于关闭整个应用的 DNS。它约束相应 IP 类规则是否主动触发解析;请求本身已有 IP 时,仍可能参与匹配。使用它时要接受一个边界:尚未得到目标地址的域名请求,可能继续落到后面的规则或 FINAL,不能假定所有地址归属都已完成判断。

四、Host:地址映射不等于连接策略

[Host] 用于本地静态主机名映射。下面这一行把 example.com 对应到 192.0.2.10。该地址属于文档用途的地址段,不是本文提供的服务地址。实际使用时,必须改为用户有权使用且确认正确的目标地址。

[Host]
example.com = 192.0.2.10

区分“连接到哪里”与“通过什么路径连接”

Host:地址映射
  • 为指定主机名提供本地地址映射。
  • 不把页面地址自动改成另一个域名。
  • 不自动选择 DIRECT 或 PROXY。
Rule:路径选择
  • 按域名或地址等条件选择策略。
  • 可以用 DOMAIN 精确指定域名策略。
  • 不会单独替换网站的目标主机名。

需要固定地址并指定路径时,分别配置 Host 与 Rule,再分别验证映射结果和策略命中。

Host 也不等于证书修复。访问 HTTPS 时,即使连接地址来自静态映射,网站仍需提供与访问主机名相符的证书。若映射到错误服务器,可能出现证书不匹配、连接被关闭或网站内容不符;这时应先检查映射,不应通过放宽证书验证来掩盖目标错误。

若应用直接连接 IP,或使用自身的解析方式,观察到的行为可能与普通域名请求不同。排查时应记录实际请求的主机名和目标地址,不能只凭浏览器地址栏判断 Host 已经参与解析。旧连接也可能继续复用原地址,修改后应以新建连接验证。

五、URL Rewrite:匹配请求地址并指定动作

[URL Rewrite] 处理的是 URL 匹配与改写,不是网络路由。以下示例用正则表达式匹配指定域名的明文 HTTP 地址,再返回到 HTTPS 地址的 302 重定向。示例以 http:// 开始,是为了说明明文请求的可见性,并不意味着所有 HTTPS 请求内容都可以直接读取。

[URL Rewrite]
^http://example\.org/(.*)$ https://example.org/$1 302

按表达式推导,http://example.org/docs 对应的目标为 https://example.org/docs。新的请求仍需解析、匹配连接策略并建立连接,因此 Rewrite 不是“绕过 Rule”的快捷方式,也不会凭空使不可达目标变得可达。

出现循环跳转时,先核对替换后的地址是否又满足同一条或另一条改写表达式。出现路径丢失时,核对捕获组与 $1 是否对应。出现完全未触发时,先确认真实请求是否已经由浏览器直接升级为 HTTPS,而不是立即修改分流策略。

六、Config 与 Global Routing:选中文件后还要选对姿态

Config 页面管理配置文件,Home → Global Routing 选择当前分流姿态。这两个名称相近,但作用不同:文件已经出现在 Config 列表里,不代表它已经被选中使用;文件已经选中,也不代表当前采用按该文件规则分流的姿态。

Config

推荐

按当前配置的规则选择连接策略,未命中请求的处理取决于末尾规则。FINAL 可以是 DIRECT,也可以是 PROXY,不能一概理解为“其余直连”。

适合:验证 Rule 顺序,以及固定域名的分流结果。

Proxy

使用全局代理姿态,不按 Rule 中的日常分流安排选路。仍可能受系统流量范围、网络例外及协议可用性影响。

适合:短时对照代理路径是否可用,不能用来证明 Rule 已生效。

Direct

采用直连姿态,用于观察本地网络路径。它不是把配置文件中的每一条 PROXY 文本改写为 DIRECT。

适合:对照同一目标在直连环境下的表现。

Scene

按已设置的场景条件切换相应行为。结果依赖场景定义;使用前应确认当前网络命中了哪一个场景。

适合:已有明确场景配置的环境;固定规则排查时先减少这项变量。

测试规则时选择 Config,更容易把请求结果对应到具体 Rule。切换到 Proxy 后能访问、回到 Config 后失败,只能提示两条路径或策略选择存在差异;还需要核对实际命中行、目标解析结果和可用服务器,不能直接得出“配置文件损坏”的结论。

七、保存、启用与排查:一次只改变一个变量

编辑前先保留原始文件,尤其是通过远程地址获取的配置。远程更新可能覆盖本地修改;服务器订阅刷新与配置文件更新也不是同一件事。前者通常更新服务条目,后者可能改变 General、Rule 等内容,不能因为订阅更新成功就认定 Rule 已经重新载入。

  1. 保留副本

    在 Config 中确认当前使用的文件,先保留一份可恢复的原始副本,再进入该文件的编辑入口。不要直接覆盖唯一可用的配置。

  2. 只改一处

    例如只调整 Rule 中一条 DOMAIN 规则的位置。保持 General、Host、URL Rewrite 不变,记录修改前后的完整行。

  3. 确认启用

    保存后回到 Config,确认选中的是刚才修改的文件;再到 Home → Global Routing 选择 Config,检查连接已启用。

  4. 新建请求

    在相同网络下重新发起目标请求,并查看请求记录中可用的域名、目标 IP 和策略信息。必要时重建连接,避免旧会话影响判断。

  5. 对照恢复

    若结果不符合预期,恢复原行再测。需要核对自动连接行为时,再单独进入 Settings → On Demand,避免同时调整多项设置。

观察现象先检查下一步动作
保存规则后策略没有变化当前选中文件与 Global Routing 姿态。确认使用 Config,再检查前面是否已有更宽泛的命中规则。
特定域名出现证书错误Host 是否映射到了错误地址。移除该条映射并新建连接,对照证书与目标主机名。
URL Rewrite 没有触发请求是否为表达式匹配的协议、域名和路径。先验证明文 HTTP 样例逻辑,再检查实际请求的可见性。
更新后自定义规则消失更新的是远程配置还是服务器订阅。对照备份恢复修改,并明确后续维护的文件来源。
命中 PROXY 仍连接失败已有服务器的协议参数与连通性。将规则命中正确与代理连接成功分开排查,不反复重排 Rule。

最终判断应拆成四个问题:配置是否被选中、请求是否命中预期规则、解析地址是否正确、所选路径是否能够连接。General、Rule、Host、URL Rewrite 分别解释其中不同部分,不能用调整某一段来替代全部排查。有关界面设置可继续查阅设置说明,协议字段可查阅协议参考。

下载 Shadowrocket