Shadowrocket .conf files organize settings into sections; they are not server lists. This guide is for users who already have their own servers or subscription and want to understand an existing configuration. First check which config is active and review Global Routing, then inspect global settings, rule order, local mappings, and request rewriting. Verify the result by changing one setting at a time.
1. Check Whether the .conf File Is Used for the Current Connection
Editing a file does not mean the current connection is using its routing rules. In Config, check which config is selected, then return to Home and review Global Routing. To test [Rule], select Config. Proxy and Direct apply an overall routing mode, so they cannot tell you whether an individual rule is working.
Home is where you select a server and control the connection, Config manages configuration files, and Settings manages app preferences. Updating a server subscription and editing a .conf file are separate tasks: the former mainly refreshes server entries, while the latter defines behavior such as parsing and traffic routing. A subscription importing successfully does not guarantee that a policy name referenced in a config exists.
| Global Routing Options | What to Check |
|---|---|
| Proxy | Tests the selected server using an overall proxy mode; not suitable for verifying individual routing rules. |
| Direct | Tests the network using an overall direct-connection mode; this does not mean a PROXY rule is broken. |
| Config | Routes traffic according to the active config; use this option to test the rules in this guide. |
| Scene | Routing behavior is determined by the selected scene. When troubleshooting, first check which scene is active. |
- In Config, back up the current file, then open the copy you want to edit.
- In Home, select a known-working server and use Connectivity Test to check basic connectivity.
- Set Global Routing to Config, save your changes, and confirm that the test file is still selected.
- Reconnect and compare the results for the same destination before and after the change.
2. Section Headers and Basic Syntax: Understand the Structure Before Editing
Section headers use English square brackets. Lines below a header belong to that section until the next header. [General] commonly uses key-value pairs, while [Rule] uses comma-separated rule fields. Not every section has the same format, and commas must be English commas, not Chinese punctuation.
[General]
dns-server = system
ipv6 = false
[Rule]
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
[Host]
lab.example.com = 192.0.2.10
[URL Rewrite]
^http://www\.example\.com/ https://www.example.com/ 302This snippet illustrates the syntax; it is not a recommended config for every network. example.com is a sample domain, and 192.0.2.0/24 is a documentation-only address range, not a real, reachable server. In practice, use domains and networks you control. Delete any Host or URL Rewrite lines you do not need.
Save the file as plain text with a .conf extension to prevent rich-text editors from changing punctuation. Put comments on separate lines to make them easier to review; when copying rules, do not include explanatory text in the fields. Successful import only confirms that the basic format was accepted. You still need to check policy references and runtime behavior.
3. [General]: Global Settings Are Not Routing Rules
[General] affects the overall behavior of the config. In the example above, dns-server = system uses the system DNS, while ipv6 = false controls IPv6 behavior for this config. Disabling IPv6 is not a universal fix. Avoid changing DNS, rules, and servers all at once, or you will not know which change affected the result.
General Checks
- Section header
- [General]
- DNS example
- dns-server = system
- IPv6 example
- ipv6 = false
- Field format
- Key = value
Change one parameter at a time, noting its original value before testing.
Connection Checks
- Connection control
- Home switch at the top
- On-demand connection
- Settings → On Demand
- Rule testing
- Home → Global Routing → Config
- Config selection
- Confirm the active file in Config
On Demand manages conditional connections; it does not replace Rule-based routing.
A successful DNS lookup, a successful connection to the destination, and the use of the correct policy are three separate checks. If a domain will not load, first confirm that it resolves to the expected address, then check the connection log. A successful lookup does not rule out an unreachable server, a blocked destination port, or an incorrect policy.
- When testing DNS, keep the network and server unchanged. Avoid switching back and forth between Wi-Fi and cellular.
- After changing DNS or Host, reconnect to the destination and account for cached DNS results in the app or operating system.
- If Settings → On Demand triggers an automatic connection, note the conditions before troubleshooting so an automatic reconnect is not mistaken for an unsaved config.
4. [Rule]: Rules Match from Top to Bottom; Put FINAL Last
[Rule] determines which policy a connection uses. A standard rule typically contains a rule type, a match value, and a policy; FINAL has no match-value field. Rules are checked in order. Once a connection matches a rule, a more specific rule below it will not be considered. Put specific exceptions before broader conditions.
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY| Keyword | What the example does |
|---|---|
| DOMAIN | Matches api.example.com exactly, before the domain-suffix rule below it. |
| DOMAIN-SUFFIX | Matches example.com and its subdomains, not text containing the string anywhere. |
| IP-CIDR | Matches the specified IPv4 range; no-resolve avoids triggering a DNS lookup to evaluate this rule. |
| GEOIP | Matches CN using an IP geolocation database; results depend on the IP address and database data. |
| FINAL | Uses PROXY when none of the preceding rules match; place it at the end of the rule list. |
With this order, api.example.com matches DOMAIN first, while other subdomains that match the suffix rule use DIRECT. If you swap the first two lines, the broader suffix rule matches first and the exact exception will never take effect. Here, PROXY is a policy reference, not a protocol or server address.
Takeaway: Fix Rule Order Before Adding Exceptions
If a domain consistently uses the wrong policy, check whether a DOMAIN-SUFFIX or FINAL rule above it already matches. Move the exact-match rule before broader rules, then reconnect to test it. Do not add duplicate rules.
If you use a custom policy group name, make sure it is defined in the active config. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard are server connection protocols; putting a protocol name at the end of a rule does not create an outbound route for it. Rules select policies, while server entries hold protocol settings. Check them separately.
5. [Host]: Local Mapping Does Not Force a Direct Connection
[Host] defines a local mapping for a domain, often for testing a fixed address in a controlled environment. The example maps lab.example.com to the documentation-only address 192.0.2.10. It specifies neither a port nor DIRECT or PROXY; the final outbound route still depends on the routing mode and rules.
[Host]
lab.example.com = 192.0.2.10- Enter the domain on the left; do not include
https://, a path, or query parameters. - Enter the destination IP on the right; do not include
:443as part of the address. - HTTPS still validates the certificate against the original domain. Mapping the domain to another address does not automatically fix a certificate mismatch.
- Reconnect before testing. The app's own cache or custom DNS resolution may affect what you observe.
If the connection times out after adding a mapping, first confirm that the destination IP is reachable, then check the port and which rule matched. A changed DNS result alone does not mean the config is correct. Remove temporary mappings after testing so an old fixed address does not override normal resolution if the server's address changes.
6. [URL Rewrite]: Match URLs, Not Outbound Routes
[URL Rewrite] uses a regular expression to match a request URL, then specifies a replacement target and action. The example redirects requests starting with http://www.example.com/ to a fixed HTTPS homepage with a 302 response. 302 is an HTTP status code, not a port number; this rule does not preserve the original path or query parameters.
[URL Rewrite]
^http://www\.example\.com/ https://www.example.com/ 302^anchors the match to the start of the URL, preventing a match against the same text elsewhere.\.matches a literal period in the domain name. An unescaped.in a regular expression matches any character.- The second field is the fixed destination URL; the third field,
302, specifies the redirect action. - Test the rule with a controlled URL and confirm it does not create a redirect loop before keeping it.
A rewrite rule is not a proxy policy and cannot fix a failed server connection. The example matches HTTP requests; do not assume that the full path of every HTTPS request can be read and rewritten directly. Visibility into encrypted requests and certificate handling are separate configuration concerns. Do not change certificate settings just to test this HTTP example.
To preserve the path, explicitly define capture groups and replacement references, then test the homepage, subpaths, and requests with query parameters separately. Do not apply a broad regular expression to every site. Login, payment, and signed URLs can be sensitive to changes in paths or parameters, and incorrect replacements may cause request validation to fail.
7. How to Verify Changes: Troubleshoot by Symptom, Not by Replacing the Whole File
For each test, keep the network, server, and destination the same, and change only one setting. Use Connectivity Test to rule out basic connectivity issues, then check the destination request's connection log and matched policy. A successful latency test does not guarantee that the destination site is accessible. Existing connections may also reuse old state, so close the destination page and make a fresh request.
Why Aren't My Rules Working After I Save the File?
In Config, confirm which file is selected, then go to Home → Global Routing and select Config. Reconnect and visit the same destination. If it still uses the wrong policy, check whether a broader rule above the one you expect has already matched.
Why Does HTTPS Still Fail After I Add a Host Mapping?
Check that the service at the mapped IP accepts the original domain and presents a certificate valid for that domain. Host changes the address mapping, not the certificate identity. Remove the mapping and compare results first; do not hide a config error by disabling certificate verification.
Why Does PROXY Still Fail to Connect After a Subscription Update?
Return to Home, check which server is selected, and run Connectivity Test. A successful subscription update only means the entries were retrieved. Check server reachability, authentication settings, and whether the policy referenced by the rule exists.
URL Rewrite Causes a Redirect Loop. Which Rule Should I Remove First?
First remove the rewrite rule you just added and test with the rest of the config unchanged. Then check whether the replacement target still matches the same expression and whether the website redirects back to the original URL. Narrow the match pattern, then enable the rule by itself.
Finally, distinguish between two types of updates. After a server subscription update, check whether the selected entry changed; after a remote config update, check whether your local edits were overwritten. Keep long-term changes in a separate local copy and record why you made them. To roll back, restore the last verified config rather than adding more untested settings, which makes the cause easier to find.