官方手册 · 设置项参考

Shadowrocket 设置手册

以 iPhone / iPad 的界面为操作基准。尚未导入自己已有的订阅或服务器信息,请先按使用说明完成首次连接;需要查某项设置何时生效、改动后如何验证或恢复,请按本页目录查阅。其他平台以各自界面提供的选项为准。

设置基线
先记原值,再分清生效范围
调整与验证
一次只改一项,用同一请求复测
恢复
先还原本次变更,再扩大排查
01 设置基线

Settings 与生效范围

调整前先分清三件事:连接是否已经建立,新请求应当采用哪种转发姿态,设置是跟随当前配置还是作用于整个客户端。先从 Home 核对连接和 Global Routing,再到 Config 核对启用的文件,最后才在 Settings 查相应项目。文件名称出现在列表里不代表已启用,编辑过文件也不代表当前请求一定经过它。若能登录但某项内容加载失败,先记下具体失败的操作,不要把一整页的表现当成一个请求的结果。

记录默认来源和恢复依据

本手册区分出厂预设、文件指定值和设备当前值。首次使用看到的值可能已受导入配置、系统权限或恢复数据影响;清空一个输入框,也可能表示继承其他来源,而不是关闭该功能。对于没有可核实的统一默认值的项目,以下各章给出可重复的测试起点,不把建议值说成预设。要保留的是修改前实际显示的状态,包括空白、自动取值或显式填入的值,不只是一个看起来能用的数字。

Global Routing 三种姿态

姿态处理原则适合验证
Config(配置)按照启用的配置匹配规则。核对某个目标是否命中预期条目。
Proxy(代理)由代理处理进入客户端转发范围的流量。在同一网络下判断走代理时是否能访问。
Direct(直连)进入客户端转发范围的流量直接访问目标。判断同一目标在直连路径下是否可用。

Direct 不是断开连接。做对照时,先让客户端保持连接,在两种姿态下分别发起新请求;需要核对客户端介入前后的差异,再单独做断开测试。有些应用会复用现成连接,也可能直接显示缓存。切换姿态后用新标签页或重新打开相关功能,并在 Log 里确认确实出现了新记录。排查结束要切回日常使用的姿态,否则规则文件即使写得正确,也可能因测试后遗留的姿态而不参与匹配。

用副本验证规则与兜底

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

把测试规则加到可恢复的副本,先定位它上方是否有更宽的匹配条件,再确认它没有落在兜底条目之后。若面板显示的动作是 PROXY,还要找出实际使用的服务器;匹配到规则只表示选了出口,不表示服务器已经成功建立连接。如果日志里出现的目标不是地址栏里的域名,先判断失败的是主请求、登录跳转还是页面附带的资源,避免给错误的目标加例外。文件各段的用途可参阅配置文件结构说明。

排查时先记下操作时间、网络类型、启用的文件和姿态。临时改值后立即复测,没出现可解释的差异就恢复原值,再换下一项。这样即使问题在切换网络后消失,也能分清究竟是设置改变起效,还是原来的网络条件已经不存在。若同一结果再也无法复现,保留当时的条件,不要把一次偶然恢复当成长期修复。

02 域名解析

DNS:来源、回退与验证

DNS 把域名解析为客户端或下一跳可以使用的地址。连接开关已经开启,或 Ping 已返回结果,都不能证明某个网站的域名解析正常。看到域名解析失败,先区分是所有目标都失败,还是只有同一个域、某类内网名称或刚刚变更地址的服务失败。记录具体域名和发生网络,再核对正在使用的 Config 中是否声明了解析方式;只凭 Settings 里看到的一项选择,不足以判断每条请求使用的解析来源。

先查来源,不以空白推断结果

核对启用文件的 [General] 与 [Host]。前者可能指定解析服务,后者可能把某些名称映射到固定地址。映射不是备用解析器,也不会跟随目标自动更新地址;当网站迁移后只有少数名称仍然连到旧地址,应先查映射和缓存。导入文件还可能带来原本没有的指定值。若有系统提供的解析设置、配置文件指定值和应用内显示值同时存在,不要从填写顺序推断最终优先级,应结合实际请求记录、域名返回结果和单项变更对照确认。

日常使用建议从原有解析设置开始。在家庭或办公网络访问本地设备时,先保留该网络提供的解析方式,因为公共解析服务通常不掌握内网名称。需要改用自己已核对的解析服务时,确认它能在当前网络上到达,并按客户端实际支持的输入格式填写。若选择的是加密 DNS,服务地址、加密方式与证书所用名称需匹配;有些服务地址本身也要先完成解析。不能把改用加密 DNS 和修复访问故障画等号,也不要用忽略证书错误来验证常用配置。

用两个目标测试,只替换一个条件

  1. 保持当前网络、服务器和 Global Routing 不变。选一个可正常访问的普通目标作对照,再选一个失败目标,分别发起新请求。记录是否返回地址、是否随后出现连接错误,以及查询和连接错误各自对应的目标。
  2. 仅在配置副本中改动解析设置,不同时删除 [Host] 条目或修改分流规则。按原顺序复测两处;若结果进入不同转发路径,先解释路径差异,再评价解析结果。只有内网目标受影响时,先恢复原解析设置,回到能复现问题的网络验证。
  3. 看似仍用旧地址时,确认应用没有复用旧连接。重新建立测试会话;必要时等待名称缓存到期,再做一次对照。测试后恢复启用的文件和原值,避免下次把测试设置误当成日常基线。

识别回退成功与后续失败

设置多个解析服务并不保证它们只按填写顺序工作。不同设置可能允许重试、回退或并行查询,解析成功也可能出自另一个服务。判断单个服务是否可用,应在可恢复的测试副本里单独检查,不用最终页面成功作为唯一证据。把解析服务换掉后,若域名有结果但仍连不上,应转查规则动作、地址族、连接或证书,继续换 DNS 往往会丢失更有价值的线索。

如果域名能打开首页,登录或图片却失败,应检查跳转后的域名与资源域名。它们可能以不同方式解析,也可能命中不同路径。直接把域名换成 IP 访问常常改变证书验证和服务端识别条件,不能作为“只有 DNS 出问题”的结论。对于时好时坏的情况,可记录失败是否总在网络切换后出现,以及相同条件下是否可以再次观察;这一信息比零散的几次成功截图更适合与 On Demand 的触发记录一起对照。

03 自动连接

On Demand:触发条件与退出

On Demand 解决的是何时由系统按条件尝试建立连接,不负责选择某个请求应走 PROXY 还是 DIRECT,也不负责验证服务器是否可用。先在 Home 手动连接并完成实际访问,再打开 On Demand 做测试。手动连接本身就失败时,自动触发只会重复尝试同一条不通的路径,容易把服务器问题误判成触发条件写错。

把当前开关和触发条件分开记

测试起点建议为关闭 On Demand 并使用手动连接,而不是把关闭写成所有设备的预设。系统恢复、设备管理配置和既有设置都可能使当前状态与另一台设备不同。打开前先记下开关、界面列出的网络条件和例外。确认系统已允许 Shadowrocket 使用对应的 VPN 配置;如果设备由组织管理,某些设置可能受限制,应按管理要求核对,不要移除其他配置来试图获得相同界面。

把使用场景写成可验证的话,例如“在指定的 Wi-Fi 上手动操作,不自动接入;离开该网络后再检查是否按条件尝试连接”。先从一个确实需要的网络场景开始,保持规则尽可能少;若界面提供网络类型或 Wi-Fi 名称条件,再按实际项选择。系统所识别的是当前接入条件,而不是路由器外观或物理位置。名称相似、同一名称在多处出现,或者设备自动选择了另一张网络,都可能使实际命中与预期不同。

分别验证满足条件、不满足条件和恢复

  1. 在手动连接已验证的网络上启用所需条件。切到满足条件的环境,发起一次新请求,比较切换前后的连接状态。记录变化开始的时间以及当时实际使用的网络,避免把尚未切换完毕的状态当成最终结果。
  2. 再到一个不满足条件的网络做反例。查看是否出现新的自动尝试,同时区分已有连接继续存在和系统发起了新连接:某个条件不触发,不一定意味着它会主动断开先前建立的连接。
  3. 测试结束先关闭 On Demand,再在 Home 手动断开,随后发起相同的访问。若断开后又出现连接,核对触发设置是否真正关闭,以及系统显示的活动连接是否属于 Shadowrocket。只操作当前测试涉及的配置。

自动尝试已发生,业务仍不通

若界面显示有连接尝试,先查请求发生时能否到达服务器,而不是继续扩大触发范围。公共 Wi-Fi 可能要求先在浏览器完成接入确认;移动网络刚恢复时,系统显示已有信号也不总等于目标已可达。可暂时关闭 On Demand,按当前网络的正常接入流程操作,再用手动连接确认。成功后复测同一个触发条件;若手动方式仍然不通,优先排查网络、DNS 和已有服务器参数。

遇到仅在锁屏后、回到前台后或切换网络途中出现的现象,应把这几个动作分开测,避免把时间上的先后当成设置因果。记录是否有新请求、旧连接是否已经结束、界面恢复显示时的状态是否与系统一致。如果同一条件在不同设备上的结果不同,先对照系统接入设置和管理限制,而不是复制整份配置。若需要把自动连接恢复为长期使用的方式,先在常用网络验证一次进入条件和一次退出条件,再逐条加入例外;每次验证只保留一项新变化。

04 连通性探测

Ping:测试方法、超时与读数

Ping 或 Connectivity Test 的结果只说明本次探测在所选条件下的表现,不等于所有应用都能通过这条路径访问,也不等于日常下载速度。先看设备上实际提供的测试方式,再解释读数。不同探测可能检查的是服务器地址响应、端口连接或一次针对指定目标的应用层请求。即使都以毫秒显示,探测的起止点不同,数值也不能直接排成一张优劣榜。

区分探测方法、目标与等待时间

观测结果可得结论不能据此判断
端口可以连接本次至少能与目标建立对应的传输连接。代理协议参数正确,或业务网站可访问。
测试请求返回该目标在本次探测条件下给出了响应。其他域名、协议或更长连接同样正常。
本次超时截止等待时间,没有得到本项预期的响应。服务器已经停用,或问题必然发生在服务端。

默认核对以设备实际显示的方式、测试地址和超时设置为准。有些界面只提供触发入口,不提供每项参数,不能据此猜测底层方法。若有可编辑的测试地址,选择自己有权使用、响应稳定且不要求登录的目标。带登录挑战、会跳到接入确认页或需要会话信息的地址,不适合当作长期基准。没有特殊需要时保留原超时;若网络确实波动且界面支持调整,可临时放宽一次,检验原结果是否受等待时间影响。不要把等待更久误写为连接更快。

建立一组可比记录

  1. 使用同一台设备,固定当前网络、测试方式和目标。挑一个已有服务器单独测量,记录成功、超时或明确错误,不只抄成功时的最小值。切换设置前标出原结果,便于恢复后判断变化是否持续。
  2. 用相同条件复测几次,分开描述持续失败、偶发失败和成功耗时波动。测试大量服务器时,设备网络负载和服务端响应都可能变化;要分析单一问题,先停止成批探测,再对可疑条目复测。
  3. 回到 Home 做一次真实访问,并查看对应的 Global Routing 和 Log。若探测正常但业务失败,继续区分规则选路、域名解析、协议协商和业务响应,不以探测结果否定业务故障。

什么时候不该继续调 Ping

看到端口连接迅速,但业务始终无法访问,先核对已有服务器信息中的地址、端口、协议和对应的验证参数。端口打开不代表该端口提供的服务与所选协议一致;直连测试与经过代理访问的目标也可能处在不同路径上。若从 Wi-Fi 切到移动网络才恢复,应把该结果记录为网络对照,而不是说延迟设置已经修复故障;回到原网络用同一组条件复测,才能判断差异是否稳定。

业务已正常、只有探测失败时,先确认测试地址是否适用于当前网络和测试方式。有些网络允许实际业务,却不响应另一种探测;反过来,简单测试能返回,也可能掩盖长时间连接中的中断。对于间歇问题,记录复现所需的网络、操作和时间,比把超时阈值一直加大更有用。若需要比较两次设置变更,只把在同一方法、同一目标和相近网络条件下得到的结果放在一起;达不到这些条件,就分别记录,不直接比较数字。

05 请求诊断

Log:按时间定位失败阶段

Log 用于回答某次操作访问了哪里、选了什么路径、在哪一步停止。开始之前,先把问题缩小到一个可以重复的动作,例如打开某个页面或点击应用里同一个功能。记录大致时间,停止与测试无关的刷新,再发起一次请求。一个操作可能同时联系登录服务、资源服务和业务服务;把日志里最后出现的错误直接等同于主请求失败,常常会把偶然出现的后台请求误认为故障原因。

从现有日志级别开始

默认先以当前显示的记录级别为准。只有当现有记录不足以区分解析、匹配和连接阶段,而且界面提供更详细的选项时,才在短时间内提高详细程度。测试前记住原级别,完成后恢复,避免长期累积与排查无关的内容。需要保留前后对照时,可以记下测试时间以划定观察区间,不必先清空整个历史;只有确知旧记录不再需要时,才考虑使用界面提供的清理操作。

按阶段阅读,不把上一阶段成功当成全程成功

  1. 先定位目标。用时间加域名缩小范围,核对日志中的实际目标是否与失败功能吻合。如果只有资源请求出错而主请求成功,就针对该资源检查;如果缺少预期条目,先确认应用确实发出了新请求而不是读取本地缓存。
  2. 再看路径。若看到 DIRECT 或 PROXY,结合当前 Global Routing 和已启用的文件理解这次结果。如果经规则匹配进入某条路径,核对目标是否被前面的条目提前匹配,或是否落入 FINAL,不要直接从文件最后一行反推实际路径。
  3. 最后查终止位置。解析错误、连接拒绝、连接超时、协议验证失败与业务响应异常分别指向不同检查面。某些路径上的解析可能发生在另一端,本地记录不一定展示完整过程;有缺失就标明未观察到,不填补不存在的证据。

例如,页面文字能显示,但图片始终失败。先对照两者实际使用的域名、选择的路径和终止位置。若图片请求命中比预期更宽的规则,可在副本中只调整这一匹配关系,再做前后对照;若它本来就选中了预期路径,却显示目标拒绝连接,就应该查端口和实际服务。只有确定问题发生在解析阶段,才值得回到 DNS 调整,而不是顺手把代理、解析和规则一起换掉。

缺少记录和需要分享时的处理

完全找不到目标记录时,先确认正在看的是正确的时间段,设备时钟和记录没有错位。接着对照 Home 连接状态和本次操作所属的应用,检查它是否真正产生了网络请求。有些记录因级别、筛选或流量处理范围而未出现在当前视图。可改用一个已知能复现的目标确定观察方法有效,再对照目标故障。没有看到条目,只说明当前视图没显示对应信息,并不能单独证明请求没有发生。

如果准备交给同事复核,可把复现步骤写成“固定网络、保持同一文件和姿态、发起一个新请求”,附上预期结果与实际结果。说明期间仅改动了哪一项,以及旧值还原后能否重现。这样读者才能区分偶发异常和可重复的配置差异。结束后恢复记录级别,断开仅为排查临时建立的连接,并确认没有留下为读取日志而开启的额外设置。

06 系统入口

Widget:显示状态与操作边界

Widget 是查看信息或触发操作的系统入口,不是另一套配置。实际可用的尺寸、位置和操作取决于设备、系统以及 Shadowrocket 在该设备上提供的内容。判断当前连接和 Global Routing 时,应回到 Home 核对;Widget 的显示可能受系统刷新时机影响,不能把它当成实时日志或应用内状态的逐帧镜像。

默认以未添加为测试起点

Widget 是否已添加由系统布局决定,设备恢复后也可能带回此前的布局。无需快捷入口时,维持系统当前布局即可,不影响在应用内连接。需要使用时,先确认 Shadowrocket 能正常打开,并已完成首次连接所需的系统确认;再进入系统支持的 Widget 添加界面,搜索 Shadowrocket,按系统显示选择尺寸和位置。不要从其他设备的截图推断本机必定有同样的选项,也不要把系统里的添加和移除当成修改 Config 的操作。

选择布局时先明确用途:只需在主屏幕查看平时的连接状态,还是需要从系统支持的位置执行快捷操作。尺寸不同可能展示不同信息,如果只需要状态,不必为了额外字段占用更大空间。设备会被他人使用,或屏幕在公共场所容易被看到时,应检查实际会显示哪些信息,再决定是否放在容易看到的位置。推荐先添加一个实例,完成一次对照后再考虑其他位置,以免两个组件因刷新时间不同造成误读。

一次对照,区分显示与动作

  1. 打开 Home,记下连接状态、当前 Global Routing 和所选服务器。返回系统的 Widget 所在位置,先不点击,观察显示是否与刚刚看的状态一致。状态晚于应用内变化时,先把它当成显示差异,而不是新的连接失败。
  2. 如果当前 Widget 提供可操作入口,只触发一次。返回 Home 核对是否确实发生了预期动作,再通过一个真实请求验证。若出现系统确认,先按提示核对是否要继续,不反复点击试图强制刷新。
  3. 在手动连接和启用 On Demand 的场景分别做一次对照。若手动断开后又自动连接,先按触发条件与退出检查系统行为,不能仅从 Widget 先后显示的文字判断是哪个入口建立了连接。

找不到入口、显示滞后或动作无效

若系统搜索不到 Shadowrocket,先打开应用确认它已完成基本设置,再回到系统的添加列表检查当前入口是否提供相应 Widget。若应用内运行正常、系统端状态只在切换连接后短暂不同,先等待系统刷新,或回到应用核对;不要为修复显示延迟而恢复配置或更换服务器。若多次对照均无法更新,可只移除该 Widget,再从系统列表添加一份,观察问题是否只伴随原来的实例。

如果点击后只打开应用而没有改变连接,先确认该入口设计上是否支持直接操作,以及系统是否要求解锁或进一步确认。若回到 Home 可以手动连接,并且实际流量正常,就把问题留在 Widget 层排查。只有手动连接也失败,才转查 DNS、服务器或规则。不使用该入口时,在系统布局中移除 Widget,再到 Home 确认日常设置仍在。移除 Widget 不等于退出连接,也不等于关闭 On Demand;这两项都应分别检查。

07 数据同步

iCloud 同步:范围、冲突与恢复

iCloud 同步用于在支持该功能的设备之间同步客户端允许纳入的数据。不要据此推断所有配置、订阅状态、系统权限和正在运行的连接都会一致。新设备同步到某个条目后,仍需核对启用的 Config、当前 Global Routing 以及系统连接许可。若只想一次性迁移可读的配置文件,可先确认应用提供的导出范围,不必为了搬运一个文件就开启持续同步。

区分三个条件:系统、客户端和资料范围

先确认各设备登录的是同一个用于 iCloud 的账号,系统设置允许对应应用使用 iCloud,最后在 Shadowrocket 中核对实际显示的同步状态和支持范围。系统允许应用访问 iCloud,不代表客户端已经开始同步;客户端有同步选项,也不代表每种资料都在范围内。默认判断以两台设备当前实际显示为准,单设备没有同步需要时可维持现状;首次测试则建议由一台资料完整的设备作为基准,不在两边同时整理数据。

iCloud 同步和从 App Store 找回已购应用是两项不同操作。前者涉及应用数据与云端状态,后者涉及账号中的应用购买记录。看到可以重新安装应用,不代表本地的配置文件或导入内容已经找回。系统连接许可也应在新设备上按实际提示核对,不预期它从旧设备直接复制。涉及获取渠道时,按下载页的已购恢复说明区分应用获取和资料迁移,再回来验证同步。

启用前备份,首次仅验证一项

  1. 确定哪台设备上的资料最完整,利用客户端实际提供的方式保存需保留的配置副本,并记录未纳入导出范围的项目。能导出配置不等于能导出全部状态。若文件含有自己的服务器或订阅资料,应存放在自己控制的位置,不为了对照而上传到公开目录。
  2. 先让另一台设备停止同时编辑,分别核对两端的系统与应用选项。选择一个不含凭据、容易辨认的测试配置副本,若该类资料在同步范围内,仅观察这一个项目是否出现。没有确认结果之前,不用删除旧文件来判断同步是否开始。
  3. 目标设备收到测试副本后,比较文件内容和启用状态,检查是否还需手动启用。再用相同目标做一次实际访问。若只是名字一致、内容却不同,先保留两份副本,不忙于替换或重复开启同步。

同名文件、传播延迟与误删

同名不等于同一项目,也不能凭列表顺序判断哪个更新。出现冲突时,先暂停两端编辑,把需要保留的候选文件分别保存,再比较实际内容,尤其是 [General] 和 [Rule]。如果暂时看不到同步动作,先检查系统是否允许访问、网络是否可用、云端空间是否充足,以及测试资料是否属于已确认的范围。不要把反复登出账号、删除应用或清空云端当作首轮操作,这些操作会让原始状态更难确认。

需要返回原状态时,以变更前保存的那份文件为准,而不是在可能仍有变更待处理的两台设备上轮流修改。先建立一台设备的本地基线,确认文件重新启用后能恢复工作,再决定是否让它继续同步。最后记录哪些内容已经确认可以跨设备同步,哪些项目必须手动核对。下次换机先按这张清单验证,不把上一次某个条目成功出现当成全部数据都已恢复。

08 本地代理入口

Proxy 端口:监听范围与最小配置

Proxy 端口若出现在本地代理设置中,指的是其他应用向本机代理入口发起连接时使用的端口,不是已导入服务器在远端使用的端口,也不是 Global Routing 的 Proxy 姿态。先确认是否真的有应用需要手动填写代理。仅在设备上正常使用 Shadowrocket 时,不必为了让 Home 能连接而打开额外的监听入口;修改本地端口也不会修好本身已经失效的远端连接。

确认协议、绑定地址和端口三项

先看当前平台是否提供相应设置,再核对它标明的本地代理协议、实际监听范围和端口。HTTP 与 SOCKS5 不是同一种接入方式;使用方填错协议时,即使能连到该端口,也可能无法完成有效请求。端口号的默认值应以界面显示为准,不能从远端服务器条目倒推,也没有必要为了和其他设备保持数字一致而改值。若需变更,用客户端明确支持且当前未被其他程序占用的端口,并同步修改实际使用该入口的应用。

同机使用时,建议优先选择只在本机回环范围可达的监听方式,使用方按同一地址族填写。只有在界面确实允许本机以外设备访问,且你能控制测试网络和访问范围时,才为明确的需求临时启用局域网使用。公共或共享网络上不应扩大监听范围,不在路由器上为该入口做公网端口转发,也不为一次测试关闭系统防护。若界面没有提供所需的绑定控制,应使用可确认范围的方案,不能用猜测的地址代替。

按失败位置逐项排除

现象先查什么
本机无法连到入口监听是否启动、地址族是否一致、端口是否填对或已被占用。
端口可达但请求失败使用方协议与监听协议是否一致,再查目标请求是否进入 Log。
本机正常,另一台设备失败监听范围、两台设备所在网络和局域网隔离策略。

从本机做一项可撤销的测试。在一个明确支持手动代理的应用里记下原设置,填写已确认的协议、监听地址和端口,随后只发起一次新请求。如果无法建立连接,先检查入口是否存在,不要修改远端端口。如果已到达入口但请求仍失败,再看 Log 是否出现与测试时间吻合的目标。确认请求已经进入客户端后,才继续区分是规则路径、DNS 还是远端协议问题。连通入口和访问目标是两项独立验证。

本机使用的回环地址不能直接作为另一台设备访问此入口的地址,因为另一台设备会把它解释成自己的本机。如果确有获准的局域网使用需求,应核对监听设备在当前网络中的实际地址,以及两台设备是否被访客网络或组织策略隔离。换了网络之后旧地址可能已失效;不应把因此产生的失败归因于服务器参数。对受管理的网络按其使用规则处理,不通过扩大开放范围来跳过限制。

本手册以 iPhone / iPad 为界面基准;Mac(Apple 芯片与 Intel)、Windows、安卓和 Linux 上是否显示相同选项,以对应客户端为准。获取分两档:iPhone / iPad 版从 App Store 获取,美区 $2.99 一次性付费,系统要求以 App Store 页面标注为准;Mac / Windows / 安卓 / Linux 版免费,安装包从本站分发。客户端一次性买断 ≠ 线路套餐。本站不提供、销售或推荐节点及订阅;连接和测试都使用自己已有的资料。各平台的获取入口与系统提示处理见客户端下载。