Node HandbookNODE HANDBOOK中文
Surge · Apple platforms

Surge: how a configuration actually decides traffic

Surge is a rules engine with a proxy layer attached. Reading it means reading four sections in order, because the last one decides where each connection goes.

Node Handbook editorial team ·

The four sections

SectionResponsibilityFailure it causes
[General]Global behaviour, DNS, capture optionsResolution problems, capture not applying to an app
[Proxy]Defines the available proxiesNothing to select from
[Proxy Group]Groups proxies with a selection methodA group that resolves to direct or to an unavailable member
[Rule]Matches connections and picks a policyTraffic going direct despite a working node

Read them in that order. Most confusion comes from starting at the proxy list, which is the third thing that matters.

Policy groups are not nodes

  • Manual selection: you choose the member; it stays until you change it.
  • Latency-based: the group picks by a test result, which changes over time.
  • Priority-based: the first available member is used.

Each of these resolves to exactly one member at a given moment. “The node is connected” and “the group resolves to that node” are different statements, and the second one is what routes traffic.

Rules decide, top to bottom

Rules are evaluated in order and the first match wins. Two consequences follow, and they explain most single-site failures:

  1. A broad rule placed above a specific one makes the specific one unreachable.
  2. A specific rule that points at a group whose selection is DIRECT sends exactly that traffic around the proxy.

When one site fails and others work, find its matching rule and the policy that rule resolves to. That is a configuration lookup, not a network investigation.

Importing a provider configuration

  1. Confirm the provider supplies a format Surge accepts; “supports Surge” is a claim worth verifying against what you actually receive.
  2. Add the configuration and confirm it loads without a syntax error.
  3. Check that [Proxy] has entries and [Proxy Group] resolves to something usable.
  4. Read the last few rules and confirm where the default goes.
  5. Test one real HTTPS request and observe the exit.

Capture scope

Surge captures traffic on the platforms it runs on, subject to how it is configured. Applications that use their own network stack, or connections that bypass the system's proxy path, may behave differently. When one application fails while Safari works, check that application's own settings before changing rules.

When it fails

SymptomFirst check
Configuration will not loadThe syntax error line; the section it names
No proxies available[Proxy] contents and whether the provider's format matched
Connected, pages failThe matched rule and the policy it resolves to
One site failsThat site's rule and the group behind it
Name resolution errorsDNS settings in [General], and correct system time

Scope

This page explains the configuration model using the vendor's official documentation. It names no provider, evaluates no plan, and does not describe capability that requires additional trust decisions as if it were routine.