This guide is for anyone reviewing or editing a local Shadowrocket configuration. First check which file is active and whether Global Routing is set to use it. Then choose a section based on the issue: check [Rule] if a connection takes the wrong route, [Host] and [General] if a hostname resolves to the wrong address, or [URL Rewrite] if you need to redirect based on a URL path.
.conf Sections and Syntax
A section name in square brackets determines how the following lines are parsed, up to the next section name. Both [General] and [Host] can contain an equals sign, but the text to its left means something different: a setting in the former and a hostname in the latter. [Rule] entries typically use commas to separate the type, match value, and policy; [URL Rewrite] redirect entries use spaces to separate the match expression, target URL, and action.
To add a rule to an existing file, find its [Rule] section first, then choose where to insert the new entry. Don't append the entire example to the end of the file: the last lines may belong to another section, so the entry won't be read as a rule even if it looks like one.
Edit and Enable a File in Config
Seeing a file in the configuration list doesn't mean it's being used for the current connection. The steps below use the iPhone and iPad interface labels. For your first change, edit just one line and keep an untouched copy of the file so you can restore it and retest under the same conditions.
Check the File
Open
Config, confirm the file you want to edit, and save an untouched copy first. If a remote configuration may update, test a local copy to avoid losing your changes when it refreshes.Edit the Source
In
Config, tap the file name and chooseEdit Plain Text. Find the relevant section and add or change just one entry. Keep the original English punctuation and delimiters, then save.Enable the Configuration
Go back to
Config, tap the edited file, and chooseUse Config. Make sure the edited file is active, not the backup copy.Start a New Request
Go to
Home→Global Routing→Config. Reconnect to the same destination. If the app reuses an existing connection, end it before testing again.
Config is both the name of the configuration screen and a mode under Global Routing. Use the screen to select a file; the mode determines whether traffic is routed according to that file's rules. When troubleshooting [Rule], check both locations.
Config
RecommendedChoose a connection policy based on the rules in the selected configuration. The order of exception entries, suffix entries, and FINAL can affect the result.
Best for: checking whether a rule in the active configuration matches.
Direct
Use direct mode. A successful direct connection only shows that the destination is reachable directly on your current network; it doesn't prove that a particular DIRECT rule in the configuration matched.
Best for: checking whether a destination is reachable directly, using the same target.
Proxy
Use proxy mode for connections handled by the client. Before testing, make sure your own server is selected in Home, then start a new connection to the same destination.
Best for: checking the proxy route without relying on routing rules.
[General] and [Host]: DNS Settings and Per-Hostname Mappings
[General] contains configuration-wide settings. For example, dns-server = system specifies the system DNS. [Host] assigns an address to a specific hostname. The former sets the usual DNS behavior; the latter creates a dedicated mapping when Shadowrocket handles resolution. Neither section replaces [Rule] for choosing a connection policy.
[General]
dns-server = system
[Host]
docs.example.com = 192.0.2.10
192.0.2.10 is a documentation-only example address, not for connectivity testing. The mapping above covers docs.example.com, not api.example.com. To test the mapping, send a request to the original hostname rather than changing the browser address to an IP. Doing so changes the hostname used for the request and may also affect HTTPS certificate validation.
Choose Checks Based on the Scope of the Issue
Several hostnames fail to resolve
- Check
dns-serverin[General]and note whether the issue occurs only on a particular network. - With the same configuration, send a new request on each of two networks. Check whether the issue changes with the network used by system DNS.
Only one hostname fails
- Check whether
[Host]contains that exact hostname, paying particular attention towwwand other subdomains. - In a copy of the file, remove the mapping and retry the same hostname to rule out interference from an old connection or cached data.
First determine whether the name resolves incorrectly or the address is correct but the connection fails. Each issue calls for different checks.
[Rule]: Top-to-Bottom Matching; First Match Wins
Rules aren't automatically sorted with the most specific entries first. To make a hostname an exception to a suffix rule, put its DOMAIN rule before the broader DOMAIN-SUFFIX rule. Connections that don't match earlier entries fall through to the final FINAL rule.
[Rule]
DOMAIN,docs.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
docs.example.com: Matches the first line and usesDIRECT; the suffix rule isn't checked.api.example.comandexample.com: Don't match the first line, so they match the second and usePROXY. Before using this rule, select your own server inHome.example.net: Matches neither of the first two lines, so it usesFINAL,DIRECT.
If you swap the first two entries, docs.example.com matches DOMAIN-SUFFIX first, so the later exact-match rule never takes effect. FINAL,DIRECT is only the fallback for this example configuration. Before editing an existing file, check its current fallback policy; don't change the route for other connections just to add an exception.
IP-CIDR matches the subnet containing the destination IP, for example IP-CIDR,192.0.2.0/24,DIRECT. GEOIP matches based on the IP's geographic location, not the domain suffix. When troubleshooting a domain request, first check whether a domain rule above has already matched, then check whether an IP rule has a destination address to match.
[URL Rewrite]: Redirect by URL Path
[Rule] determines how a connection is routed; [URL Rewrite] matches HTTP request URLs the client can process. The example below specifies the protocol, hostname, and path, then uses 302 to redirect to a new address. It demonstrates the syntax only and doesn't rely on a live page at the example domain.
[URL Rewrite]
^http://docs\.example\.com/old$ http://docs.example.com/new 302
^and$match the entire URL;\.matches a literal dot in the hostname. When substituting your own test domain, keep the backslash before the dot.- This expression matches only
http://docs.example.com/old. It won't match/old/or/old?from=help. To verify the match, request both the original path and the path with a query string, and confirm the results are as expected. - The target URL uses
/newon the same host, so it won't match this expression again. To check the redirect, first confirm that the initial response is302and the target URL is correct, then check whether the new request succeeds.
An HTTPS request's path is encrypted, so knowing the destination hostname alone isn't enough to match it. If your test tool upgrades HTTP to HTTPS before sending the request, the expression above won't match as written. Check the actual protocol and URL being sent before deciding whether to change the expression.
Why Changes May Not Take Effect
Why does traffic still use the proxy when I added DIRECT?
First check whether Home → Global Routing is set to Config, then inspect [Rule] in the active file. If a DOMAIN-SUFFIX rule above already covers the hostname, move the exact DOMAIN exception ahead of it and reconnect to test.
Can I paste a new rule directly below FINAL?
Don't put regular rules after the fallback. If the file has a FINAL rule, insert the new entry before it, then check whether an earlier rule also covers the destination. After saving, test one destination that should match the new rule and another that should fall through to the fallback.
Why doesn't the browser address change after I edit Host?
[Host] changes the address mapped to a hostname, so it's normal for the browser's address bar to keep showing the original URL. To verify the mapping, use a destination service you control and check whether the new connection reaches the expected address. To redirect /old to /new, check URL rewriting, not hostname mapping.
After switching back to the original file, how can I find which change caused the issue?
On the same network, send the same request with the original file and the edited copy, keeping Global Routing and the selected server unchanged. If the issue occurs only with the copy, start with the section you edited most recently and revert it one line at a time. Change one thing and retest each time until you find the entry that triggers the issue.