Surge 配置说明文档

General

[General]
ipv6 = false
ipv6-vif = auto
geoip-maxmind-url = https://raw.githubusercontent.com/Loyalsoldier/geoip/release/Country.mmdb
loglevel = warning

ipv6：是否处理 IPv6 流量。
ipv6-vif：TUN 虚拟网卡的 IPv6 行为。
- disabled：虚拟网卡不处理任何 IPv6 流量（默认）。
- auto：仅当当前网络支持 IPv6 时才启用。
- always：强制启用，可能引发部分 App 兼容问题并触发配置校验警告。
geoip-maxmind-url：GeoIP 数据库来源。
loglevel：日志级别。

Remote Access

参考手册：HTTP API

Proxy Service

[General]
http-listen = 0.0.0.0
socks5-listen = 0.0.0.0
proxy-restricted-to-lan = true

http-listen / socks5-listen：HTTP、SOCKS5 代理的监听地址，设为 0.0.0.0 表示监听所有网卡、供局域网其他设备使用。
proxy-restricted-to-lan：仅允许局域网内地址连接代理端口，阻断公网访问。

Remote Controller

兼容 *** Dashboard 等工具

external-controller-access = your-secret-key@127.0.0.1:6170

*** 兼容的外部控制器接口，可接入 *** Dashboard、Stash 等第三方面板。
格式为 key@host:port，此处绑定 127.0.0.1，仅本机可访问。

HTTP API

http-api = your-secret-key@127.0.0.1:6171
http-api-tls = false
http-api-web-dashboard = false

http-api：Surge 自有的 HTTP API，同样 key@host:port，仅绑定本机。
http-api-tls：API 是否走 HTTPS。
http-api-web-dashboard：是否启用内置 Web 控制面板。

Advanced

Connectivity Test

internet-test-url = http://wifi.vivo.com.cn/generate_204
proxy-test-url = http://cp.cloudflare.com/generate_204
proxy-test-udp = cloudflare.com@1.1.1.1
test-timeout = 3

internet-test-url：检测本机是否真正联网，用国内 generate_204 端点，避免被墙误判离线。
proxy-test-url：测试代理节点 TCP 延迟，用境外 generate_204 端点。
proxy-test-udp：UDP 连通性测试目标，格式为 domain@dns。
test-timeout：所有连通性测试的超时时间，单位秒。

Error Page

show-error-page = true
show-error-page-for-reject = true

show-error-page：请求失败时是否向客户端返回错误页面。
show-error-page-for-reject：被 REJECT 拦截的请求是否也返回错误页，便于确认是规则命中而非网络故障。

UDP

udp-policy-not-supported-behaviour = REJECT

当选中的策略不支持 UDP 转发时直接拒绝，而不是回退直连，避免 UDP 流量泄漏真实 IP。

Compatibility

always-real-ip = *.msftconnecttest.com, *.msftncsi.com, *.srv.nintendo.net, *.stun.playstation.net, xbox.*.microsoft.com, *.xboxlive.com, *.logon.battlenet.com.cn, *.logon.battle.net, stun.l.google.com
hijack-dns = *:53
tun-excluded-routes = 224.0.0.0/4, 169.254.0.0/16, 100.64.0.0/10, 10.0.0.0/8, 172.16.0.0/12
skip-proxy = 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, *.local, *.lan
exclude-simple-hostnames = true

always-real-ip：列出的域名始终返回真实 IP、不做 DNS 映射，主要是各类联网检测与游戏主机 STUN / 登录域名，保证 NAT 类型检测和联网检测正常。
hijack-dns：拦截发往指定地址的明文 DNS 查询并由 Surge 自行应答，使硬编码 DNS 的设备 / 软件也能纳入分流。仅增强模式生效。
tun-excluded-routes：从 VIF 排除的网段，仅增强模式生效。
skip-proxy：让指定网段绕过代理。macOS 写入系统代理绕过列表；iOS 走 VIF 而非代理接管。
exclude-simple-hostnames：同 skip-proxy，作用于不含点号的主机名（如 nas、router）。

DNS

参考手册：DNS Overview、DNS Servers、Encrypted DNS

dns-server = 223.5.5.5, 8.8.8.8, system
encrypted-dns-server = https://1.1.1.1/dns-query
read-etc-hosts = true

dns-server：覆盖系统默认的 DNS。可填 IP、tcp://主机名 或 system（并入系统 DNS）；并发查询，取最快应答。
encrypted-dns-server：加密 DNS，支持 https://（DoH）、h3://（DoH3）、tls://（DoT）、quic://（DoQ）。配置后域名解析全部走加密 DNS，dns-server 仅作 bootstrap（解析加密 DNS URL 中的主机名）及连通性探测。
read-etc-hosts：是否读取本机 /etc/hosts 中的映射（仅 macOS，默认开）。

iOS 专用参数

以下参数仅在 Surge iOS 生效，macOS 忽略。

wifi-assist = false
all-hybrid = false
allow-hotspot-access = false
compatibility-mode = 0
hide-vpn-icon = false

wifi-assist：Wi-Fi 弱时是否用蜂窝网络辅助建连。
all-hybrid：是否始终同时用 Wi-Fi 和蜂窝建连（而非仅在 Wi-Fi 差时）。
allow-hotspot-access：开个人热点时，是否允许接入的设备使用本机代理。
compatibility-mode：整数 0–5，选择 iOS 的接管工作模式（0 Auto）。
hide-vpn-icon：是否隐藏状态栏的 VPN 图标（网络切换时可能引发系统问题，慎用）。

节点

参考手册：Policy Overview

[Proxy] 定义所有基础节点。共有 4 种类型，每种给出一个示例。

HTTP 节点

参考手册：HTTP and HTTP/2

Proxy-HTTP = http, 192.0.2.10, 8080, test-url=http://example.com/

格式：name = http, host, port [, username, password] [, key=value ...]。username / password 可作位置参数跟在端口后，或写成 username= / password=。
test-url：为该节点单独指定测速地址，适合内网或特定集群资源。

带前置代理的 HTTP 节点：

Proxy-Chain = http, proxy.example.com, 3128, user, pass, underlying-proxy=Proxy-Group

underlying-proxy：出站前先经过指定策略组当前选中的节点，形成链式代理。

SSH 隧道节点

参考手册：SSH

Proxy-SSH = ssh, 192.0.2.11, 22, username=root, private-key=key1

格式：name = ssh, host, port, username=..., password=... | private-key=...（password 与 private-key 二选一）。
private-key：[Keystore] 中的私钥条目名。

SOCKS5 节点

参考手册：SOCKS5

Proxy-SOCKS5 = socks5, 192.0.2.12, 1080, user, pass, underlying-proxy=Proxy-Group

格式：name = socks5, host, port [, username, password] [, key=value ...]。

Snell 节点

参考手册：Snell

Proxy-Snell = snell, 192.0.2.13, 8000, psk=your-psk, version=4, reuse=true

格式：name = snell, host, port, psk=..., version=...。
psk：预共享密钥，需与服务端一致。
version：Snell 协议版本，需与服务端一致；省略时按旧版 v1 处理，应显式声明。
reuse：复用 TCP 连接以降低握手开销（true / false，默认 false）。

策略组

参考手册：Policy Group Overview、Common Group Parameters

[Proxy Group] 定义分流用的策略组。常用参数：

hidden：是否在客户端选择界面隐藏该组（true / false，默认 false）。
no-alert：连接异常时是否弹出提醒（true / false，默认 false）。
include-all-proxies：是否自动纳入 [Proxy] 里的全部节点（true / false，默认 false）。
include-other-group：纳入其他策略组的成员节点，多个组用逗号分隔。
policy-regex-filter：用正则从候选中筛选纳入的节点。
update-interval：远程订阅的自动更新间隔（秒），-1 表示仅手动更新。

select（手动选择）

参考手册：Manual Selection Group

Manual = select, Auto, DIRECT, node-a, node-b
Sub = select, policy-path= https://example.com/sub?target=Surge , update-interval=86400

在候选策略间手动切换；常作为全局总开关，由 FINAL 兜底指向。
policy-path：指向 Surge 格式的节点列表（本地路径或 URL），Surge 不做格式转换。

fallback（故障转移）

参考手册：Fallback Group

Fallback = fallback, node-a, node-b, node-c

按顺序选择第一个健康的节点，前一个不可用才切到下一个。

smart（自动择优）

参考手册：Smart Group

Auto = smart, include-other-group=Sub
Region = smart, include-other-group=Sub, policy-regex-filter=<keyword-regex>

由 Surge 根据延迟、丢包等自动挑选节点。
配合 policy-regex-filter 可从来源中筛出子集（如按地区分组）。

分流规则

参考手册：Rule System Overview、IP Rules、Rule Sets、FINAL Rule

[Rule] 自上而下匹配，命中即停止。涉及的规则类型：

IP-CIDR,cidr,policy,no-resolve：按目标 IP 段匹配，no-resolve 表示不触发 DNS 解析。
RULE-SET,source,policy：加载规则集，source 可为远程 URL，或 SYSTEM / LAN 等内置集。
GEOIP,country,policy：按 GeoIP 归属地匹配。
FINAL,policy[,dns-failed]：兜底规则；dns-failed 允许本地 DNS 解析失败时仍交给代理解析。

示例（每种类型一条）：

IP-CIDR,192.168.6.0/24,dorm,no-resolve
RULE-SET, https://example.com/rules/cn.list ,CN
RULE-SET,SYSTEM,DIRECT
GEOIP,CN,CN
FINAL,GLOBAL,dns-failed

HTTPS 解密

参考手册：HTTPS Decryption (MITM)

[MITM]
h2 = true
ca-passphrase = your-passphrase
ca-p12 = <base64-encoded-pkcs12>
hostname = *.example.com, api.example.org, -pinning.example.com

h2：是否对被解密流量启用 HTTP/2。
ca-passphrase：CA 证书（p12）的密码。
ca-p12：Base64 编码的自签 CA 证书 + 私钥（PKCS#12）。
hostname：需要解密的域名白名单，逗号分隔，支持 * 通配，- 前缀表示排除（如做了证书固定的域名）。

surge-cli 用法

参考手册：Surge Mac CLI

Surge Mac 附带的命令行控制工具（/Applications/Surge.app/Contents/Applications/surge-cli）。本地命令直接控制运行中的 Surge，无需额外配置；-r / --remote 操作远程实例，需对方开启 external-controller-access。

全局参数

surge-cli                            # 无命令进入交互模式（补全 + 历史）
surge-cli <command> --raw           # 输出原始 JSON（自动化用）
surge-cli <command> -r <host:port>  # 操作远程实例；密码经 SURGE_CLI_PASSWORD / --password-stdin / 安全提示符
surge-cli -c <path>                 # 校验 profile 是否合法
surge-cli help <command>            # 某命令的详细用法

控制

surge-cli reload                  # 重新加载配置
surge-cli switch-profile <name>   # 切换配置文件
surge-cli kill <connection-id>    # 断开某个连接
surge-cli stop                    # 关闭 Surge
surge-cli unattended-upgrade      # 静默升级

状态

surge-cli status   # 活跃 profile、出站模式、功能开关、运行时长、版本
surge-cli version  # Surge / Core / 控制器协议 / 系统 / 设备版本
surge-cli summary  # 网络概况：接口、地址、路由、DNS、Wi-Fi/蜂窝、配置告警

路由

surge-cli mode [rule|direct|global]        # 查看或切换出站模式
surge-cli global-policy [<policy>]         # 查看或修改 Global 模式使用的策略
surge-cli policy-group ...                 # 列出组、查看/切换选择、清除自动组覆盖
surge-cli rule match <host|url> [k=v ...]  # 不建连，评估规则命中与最终策略
surge-cli rule explain <host|url>          # 解释某请求为何选中该策略（逐组决策、链路）
surge-cli rule temp ...                    # 临时规则增删改查（即时生效、优先于 profile、重启即弃）

配置与模块

surge-cli profile [diff|list|validate|switch]  # 查看/对比/列出/校验/切换 profile
surge-cli module ...                            # 列出模块、批量启用/禁用
surge-cli feature ...                           # 查看/控制 MitM、Rewrite、Scripting、抓包、系统代理、增强模式等
surge-cli managed-profile update                # 强制检查并更新托管 profile
surge-cli external-resource list                # 列出外部资源
surge-cli external-resource update <key|all>    # 强制重新拉取

网络诊断

surge-cli dns lookup <domain>   # 走 Surge DNS 管线解析，显示应答、服务器、接口、耗时、缓存
surge-cli dns trace <domain>    # 同上，附完整解析器 trace
surge-cli geoip <ip>            # 查 GeoIP / ASN（与 GEOIP、IP-ASN 规则同源）
surge-cli http probe <url>      # 经指定策略或规则系统发 HEAD，报状态、延迟、命中规则、响应头
surge-cli test-policy <policy>  # 测节点延迟
surge-cli test-all-policies     # 测所有节点
surge-cli test-group <group>    # 立即重测某策略组
surge-cli test-network          # 测网络延迟
surge-cli diagnostics           # 网络诊断
surge-cli flush dns             # 刷新 DNS 缓存

检查与观测

surge-cli dump active                        # 当前活跃连接
surge-cli dump request                       # 最近请求
surge-cli dump rule                          # 当前生效的 [Rule]
surge-cli dump policy                        # 所有代理与策略组
surge-cli dump dns                           # DNS 缓存
surge-cli dump profile [original|effective]  # 原始 / 生效后的配置
surge-cli dump performance                   # 引擎内存、运行时长、活跃请求、各表大小
surge-cli dump rule-usage                    # 每条规则的命中计数
surge-cli dump virtual-ip <ip|domain>        # 查虚拟 IP 映射
surge-cli watch request                      # 实时追踪新请求
surge-cli watch speed                        # 实时上下行速度
surge-cli log [watch]                        # 读取 / 流式查看日志
surge-cli logbook                            # 结构化 Logbook 记录
surge-cli proxy-runtime-status               # 协议运行时详情（含 Tailscale / WireGuard 状态）

自动化

surge-cli script list                              # 列出已配置脚本
surge-cli script run <name>                        # 按名运行 cron 脚本
surge-cli script evaluate <path> [type] [timeout]  # 从文件加载并执行脚本
surge-cli script-log                               # 某次脚本执行的日志
surge-cli benchmark encryption                     # 加解密性能
surge-cli benchmark rule-matching                  # 规则匹配平均耗时

环境

surge-cli environment            # 查看 ProxyMode / ProxyGroupSelection 等底层状态
surge-cli set <key-path> <value> # 修改 environment 设置项
surge-cli set-log-level <level>  # 改日志级别（不写入 profile）

网关（macOS）

surge-cli device        # 列出 / 查看网关模式设备
surge-cli vmnet         # 网关虚拟网卡：状态、ARP、NDP、RA 接管
surge-cli security ban  # 查看 / 清除因反复未授权访问触发的封禁

参考资料

Surge Manual：官方手册，配置写法与各参数取值、默认值的权威参考。
Surge Knowledge Base：知识库，常见问题、故障排查、进阶功能教程与 iOS / Mac 版本更新说明。

posted @ 2026-09-04 19:12 undefined443 阅读(16) 评论(0) 收藏举报

刷新页面返回顶部

undefined443