《Shadowrocket 配置文件（.conf / .json）完整说明》

在前一篇 《Shadowrocket（小火箭）基础知识与入门指南》 中，我已经把 Shadowrocket 的整体定位、使用边界和常见误解讲清楚了。

但在实际工作中，我遇到最多的问题并不是“怎么连上”， 而是： “我拿到一个配置文件，它到底改了系统里的什么？”

我是 Nate，目前在 IPWeb 从事代理网络与数据采集基础设施相关的技术研究工作， 这类配置问题几乎每天都会在工程团队、跨境业务和 SaaS 项目中反复出现。 很多“配置不生效”“结果变了”的问题， 并不是节点质量问题，而是配置文件本身改变了决策结构

这篇文章不会教你“点哪里”“怎么导入”， 而是站在工程视角，解释： 一个 Shadowrocket 配置文件被导入后，系统层面究竟发生了什么变化。

一句话定义：
Shadowrocket 的配置文件不是“一个节点集合”， 而是一次对规则、策略与出口关系的系统级重定义。

核心判断公式：
配置文件内容 → 影响了哪些配置对象 → 是否被规则 / 策略引用 → 是否改变实际流量路径

这篇文章能帮你解决什么：
帮你判断导入一个配置文件后， 是仅新增配置，还是覆盖了原有决策结构， 理解为什么“配置存在”不等于“配置生效”， 避免把结果变化误判为节点或网络问题。

适用边界说明：
本文适用于需要长期维护、多场景复用或团队协作的使用场景； 若你只是临时使用、只关心是否能连接， 配置文件可能并不是最合适的选择。

第 1 章｜什么是 Shadowrocket 配置文件？

在实际工作中，我经常遇到一种非常典型的误解： 只要提到 Shadowrocket 配置文件， 很多人下意识会把它理解成—— “比二维码多一点节点而已”。

但如果你真正从系统层面去看， 这个理解是不成立的。 配置文件并不是节点的“存储容器”， 而更像是一份网络决策说明书。

1.1 配置文件在 Shadowrocket 中扮演的真实角色

从 Shadowrocket 的实现逻辑来看， 配置文件并不只是被“读取”， 而是会被系统整体加载并解析。 它所描述的内容，通常包括但不限于：

• 系统中可以使用哪些节点
• 请求应当如何被匹配
• 命中规则后如何选择出口
• 部分与 DNS 或网络行为相关的全局设置

换句话说， 配置文件定义的是一整套“网络行为逻辑”。 节点只是其中的一个组成部分， 而不是配置文件存在的唯一目的。

1.2 为什么说“把配置文件当成节点集合”是危险的？

在工程实践中， 我见过不少问题都源自一个前提错误：

“我只是导入了一些节点，不可能影响原来的配置结构。”

这个判断在“单节点导入”场景下或许成立， 但在配置文件场景中， 往往并不准确。

原因很简单： 配置文件导入的单位不是‘节点’，而是‘配置结构’。 一旦文件中包含规则或策略定义， 系统就必须将这些定义纳入现有配置环境中进行解析。

即便你只关心“能不能连上”， 系统层面也已经发生了： 决策对象的新增或替换。

1.3 .conf 与 .json 的差异，重要吗？

很多用户在拿到配置文件时， 会第一时间问我： “.conf 和 .json 哪个更高级？”

从系统行为角度， 我的回答通常是：

格式本身并不决定能力，内容结构才决定影响范围。

不论是 .conf 还是 .json， 本质上都只是配置的表达形式。 真正决定系统发生什么变化的， 是文件中包含了哪些配置对象， 以及它们如何被系统引用。

这也是为什么， 在后续章节中， 我更关注“文件里写了什么”， 而不是“文件叫什么名字”。

第 2 章｜一个配置文件里，通常包含哪些“配置对象”？

为了避免任何误解， 我需要先明确一点： 并不是所有配置文件都会包含下面全部内容。 但从结构上看， 它们通常会围绕这些对象展开。

2.1 节点定义

节点，是最容易被理解的一类配置对象。 它描述的是： 如果需要建立代理连接，应当连接到哪里，以及如何连接。

在配置文件中， 节点通常只是“被引用的资源”， 而不是默认生效的出口。 是否真正使用某个节点， 取决于后续的规则和策略选择。

2.2 规则：决定“哪些请求需要被关注”

规则的职责， 是对请求进行匹配与分类。 它回答的不是“用哪个节点”， 而是：

“这个请求，属于哪一类？”

在工程视角下， 规则是整个系统的入口条件。 没有规则， 节点就无法被有选择地使用。

2.3 策略：决定“命中规则后怎么选”

如果说规则解决的是“分流判断”， 那策略解决的就是“出口决策”。

策略位于规则与节点之间， 它定义的是： 当某类请求被识别后，系统应当如何在节点之间做选择。

这也是为什么， 在配置文件场景中， 节点数量的变化， 往往会伴随着策略结构的变化。

2.4 DNS 及其他系统级设置

除了上述三类核心对象， 有些配置文件中还会包含：

• DNS 查询方式的定义
• 是否通过代理进行解析
• 与系统网络行为相关的辅助设置

这些内容通常不直接表现为“节点变化”， 但却可能显著影响最终的访问结果。 也正因为如此， 它们往往是问题排查中最容易被忽略的部分。

2.5 一个重要的工程结论

从系统整体来看， 配置文件并不是在“添加功能”， 而是在重新描述系统应当如何工作。

一旦你意识到这一点， 后续关于“覆盖”“不生效”“结果变化”的问题， 才会有一个正确的判断起点。

第 3 章｜配置文件 vs 二维码 vs 手动配置

在我十多年的代理与配置维护经验中，很多关于 Shadowrocket 的争论其实是跑偏的。 用户常问的是“哪种方式更安全”“新手该用哪种”， 但在工程视角下，我更关心的始终只有一个问题：

一次配置操作，到底在系统里新增了什么、替换了什么？

3.1 手动配置：每一次点击，都是一次显式变更

从系统角度看，手动配置是最“老实”的方式。 你新增的是什么、修改的是什么，全部体现在你的操作路径中：

• 新增一个节点
• 修改一个端口或协议参数
• 手动指定某个策略引用

这也是为什么在调试阶段，我仍然会优先使用手动配置—— 它对系统最温和，对排错最友好。

但代价同样明显：字段一多，人工错误几乎不可避免。 系统本身没有问题，结果却“不符合预期”， 很多时候只是因为某个参数复制错了一位。

3.2 二维码配置：你看到的是“导入成功”，不是“变更清单”

从工程视角看，二维码并不是一种配置类型， 而是一种配置导入载体。

一次扫码操作，可能在系统中同时发生：

• 新增节点或节点组
• 新增策略并自动引用
• 替换原有配置项

问题在于：这些变化在导入前，对用户是不可见的。 用户能确认的只有一件事——“是否导入成功”。

从系统角度来说，二维码不是“改动更少”， 而是改动被封装、被隐藏。

3.3 配置文件导入：一次操作，系统结构整体对齐

在团队使用或长期维护场景中，配置文件几乎是必选项。 它的本质是一份完整的系统状态声明。

导入配置文件时，Shadowrocket 的默认行为是：

• 按文件结构加载节点、规则与策略
• 优先保证配置一致性
• 而不是尽量与现有配置合并

这正是配置文件可维护性强的原因， 也是它容易引发覆盖行为的根源。

第 4 章｜配置文件的「覆盖行为」是怎么发生的？

这是我在实际使用中见过误解最多的一类问题。 很多用户会疑惑：

“我只是导入了一个配置文件，
怎么原来的节点、规则、策略全变了？”

从工程角度看，这种结果其实完全符合配置加载逻辑。

4.1 哪些配置项最容易被替换？

在 Shadowrocket 中，以下内容通常会被整体替换：

• 节点列表（Servers）
• 策略组（Policy Groups）
• 规则集（Rules）
• DNS 与路由相关设置

因为配置文件本身表达的是： “我希望当前系统状态就是这样。”

4.2 哪些配置更可能表现为叠加？

在部分场景下，系统可能表现为叠加，例如：

• 仅包含节点的配置文件
• 未声明的模块，系统可能保留原值

但是否叠加，取决于文件结构本身， 而不是用户的主观理解。

4.3 为什么你会感觉“导入后结果不对”？

从工程实践来看，最常见的原因有三类：

1. 策略引用发生变化，节点还在但不再被使用
2. 规则顺序整体变化，流量命中逻辑不同
3. DNS 或路由设置被重置，请求路径发生改变

4.4 系统行为的权威背景

从 iOS 的配置加载模型来看， 应用在导入完整配置时优先保证一致性而非复杂合并， 这是符合平台设计预期的。

相关背景可参考： Apple Developer 官方文档（配置与数据模型说明） ，以及 Shadowrocket 在 App Store 的官方功能描述 。

如果你把配置文件当成“高级一点的二维码”， 那几乎一定会遇到配置结果不可预期的问题。

第 5 章｜为什么团队和长期项目更偏向使用配置文件？

在实际工程环境中，只要使用场景从“个人临时使用”升级到 “多人协作 / 长期维护 / 可追责”， 配置方式的选择几乎没有悬念。

我在跨境业务、数据采集项目以及内部测试环境中， 见过太多因为配置方式不当而引发的“非技术事故”， 而配置文件，往往是解决这些问题的分水岭。

5.1 可复现：同一份配置，在任何设备上结果一致

在团队环境中，一个最基本的工程要求是： 同一份配置，在不同人、不同设备上，结果必须一致。

配置文件的优势在于，它描述的是完整状态，而不是操作步骤。 你不需要猜测：

• 这个节点是不是后来手动加的？
• 这条规则是不是扫码时顺带进来的？
• 这个策略是不是被谁临时改过？

只要配置文件一致，系统行为就是可复现的。 这对调试、回归测试、问题复盘至关重要。

5.2 可审计：任何变更，都能被明确识别

在长期项目中，“配置发生过什么变化”本身就是一个重要问题。 配置文件天生适合被审计：

• 哪些节点被新增或移除
• 规则顺序是否发生变化
• 策略引用是否被调整

这些变化都可以被直接识别，而不是靠“记忆”或“猜测”。 这也是为什么在工程团队里， 很少有人会接受“我刚刚扫了个码，具体改了什么我也不太清楚”。

5.3 可版本管理：配置不是一次性行为

配置文件的另一个决定性优势，是它可以被纳入版本管理体系。

在真实项目中，配置往往会经历：

• 功能迭代带来的规则变化
• 节点供应商调整
• 业务区域扩展

如果配置不能被版本化， 那每一次调整都可能变成“不可逆操作”。

而配置文件至少保证了一点： 你永远知道当前配置来自哪里。

5.4 可批量分发：规模化使用的前提条件

当使用对象从“一个人”变成“一个团队”， 配置分发方式本身就变成了工程问题。

配置文件允许你做到：

• 统一分发同一份配置
• 降低成员理解成本
• 避免每个人形成“私有配置变体”

这也是为什么在数据团队、跨境业务团队中， 配置文件往往不是“选项”，而是默认方案。

第 6 章｜哪些人不适合直接使用配置文件？

6.1 只偶尔使用 Shadowrocket 的人

如果你的使用场景是：

• 偶尔连一下海外服务
• 不涉及长期配置维护
• 也不需要复现同一环境

那么直接使用配置文件，反而可能增加理解负担。 因为你并不关心系统整体结构， 也不会去追踪配置的演变过程。

6.2 无法判断配置变更影响的人

配置文件的前提假设是： 使用者至少能理解“导入一次配置，可能整体改变系统状态”。

如果你无法判断：

• 哪些配置会被替换
• 哪些可能只是叠加
• 导入后为何结果发生变化

那么配置文件带来的不是效率， 而是更大的不确定性。

6.3 不需要长期维护或多人协作的场景

配置文件的价值，建立在“长期”和“协作”之上。 如果你的使用场景不满足这两个条件， 那它的优势很可能无法被充分发挥。

在这种情况下， 选择更轻量、变更范围更可感知的方式， 反而更符合你的实际需求。

工程实践中最重要的一点是： 工具本身没有优劣，只有是否匹配场景。

第 7 章｜这一页你应该记住的 3 个结论

结论一：配置文件不是“更高级”，而是“更系统”

很多人误以为配置文件是“进阶玩家”才需要的工具， 但在工程视角下，它并不代表水平高低， 而代表是否需要一个可被管理的系统状态。

当使用场景涉及长期维护、多人协作或结果复现时， 配置文件几乎是唯一合理的配置形态。

结论二：它改变的不是一个节点，而是一组决策结构

与手动添加节点或扫码导入不同， 配置文件影响的是 Shadowrocket 内部的整体决策结构：

• 规则的组织方式
• 策略与节点的引用关系
• 默认出口的判断路径

这也是为什么导入配置文件后， 很多用户会感到“结果变了，但说不清哪里变了”—— 因为变化发生在系统层，而不是单一对象。

结论三：可维护性，永远比“快连上”重要

在真实项目中，“能不能马上连上”从来不是最终目标， 真正决定成本的，是后续是否还能被理解、被修改、被追溯。

配置文件的价值不在于第一次使用， 而在于第十次、第一百次调整时， 你依然知道系统为什么会做出当前的决策。

常见问题解答（FAQ）