GUI.for.SingBox配置文件格式详解：JSON结构与字段说明
引言
你是否在配置SingBox时遇到过JSON结构混乱、字段含义模糊的问题？本文将系统解析GUI.for.SingBox的配置文件格式，帮助你掌握从基础结构到高级配置的全流程，读完你将能够：
- 理解SingBox配置文件的整体架构
- 掌握各核心模块的JSON字段含义
- 正确配置日志、入站/出站连接、路由规则和DNS设置
- 解决常见的配置错误
配置文件整体架构
SingBox配置文件采用JSON（JavaScript Object Notation）格式，遵循层次化结构设计。一个完整的配置文件包含以下顶级字段：
{
"log": {},
"experimental": {},
"inbounds": [],
"outbounds": [],
"route": {},
"dns": {},
"mixin": {},
"script": {}
}
配置文件各模块功能
| 模块 | 功能描述 | 重要性 |
|---|---|---|
| log | 日志输出配置 | 基础 |
| experimental | 实验性功能配置 | 高级 |
| inbounds | 入站连接设置 | 核心 |
| outbounds | 出站连接设置 | 核心 |
| route | 流量路由规则 | 核心 |
| dns | DNS解析配置 | 核心 |
| mixin | 配置合并策略 | 高级 |
| script | 自定义脚本 | 扩展 |
详细字段说明
1. 日志配置 (log)
日志配置控制SingBox的日志输出行为，帮助用户调试和监控系统运行状态。
{
"log": {
"disabled": false,
"level": "info",
"output": "",
"timestamp": false
}
}
字段说明
| 字段 | 类型 | 可选值 | 默认值 | 说明 |
|---|---|---|---|---|
| disabled | boolean | true/false | false | 是否禁用日志输出 |
| level | string | trace/debug/info/warn/error/fatal/panic | info | 日志级别，控制输出详细程度 |
| output | string | 文件路径 | 空字符串 | 日志输出文件路径，为空时输出到控制台 |
| timestamp | boolean | true/false | false | 是否在日志中包含时间戳 |
2. 入站连接配置 (inbounds)
入站连接定义SingBox如何接收外部流量，支持多种协议类型。
{
"inbounds": [
{
"id": "mixed-in",
"type": "mixed",
"tag": "mixed-in",
"enable": true,
"mixed": {
"listen": {
"listen": "0.0.0.0",
"listen_port": 20122,
"tcp_fast_open": true,
"tcp_multi_path": false,
"udp_fragment": true
},
"users": []
}
}
]
}
入站类型与字段
SingBox支持多种入站类型，每种类型有其特定配置：
| 类型 | 说明 | 主要字段 |
|---|---|---|
| mixed | 混合协议入站 | listen, users |
| socks | SOCKS协议 | listen, users |
| http | HTTP协议 | listen, users |
| tun | TUN设备 | interface_name, address, mtu |
通用监听配置 (listen)
{
"listen": {
"listen": "0.0.0.0",
"listen_port": 20122,
"tcp_fast_open": true,
"tcp_multi_path": false,
"udp_fragment": true
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
| listen | string | 监听地址，0.0.0.0表示所有网络接口 |
| listen_port | number | 监听端口号 |
| tcp_fast_open | boolean | 是否启用TCP快速打开 |
| tcp_multi_path | boolean | 是否启用TCP多路径 |
| udp_fragment | boolean | 是否启用UDP分片 |
3. 出站连接配置 (outbounds)
出站连接定义SingBox如何发送流量，支持多种代理协议和负载均衡策略。
{
"outbounds": [
{
"id": "proxy-group-1",
"tag": "Proxy",
"type": "selector",
"outbounds": [
{
"id": "sub-1",
"tag": "Subscription 1",
"type": "Subscription"
}
],
"interrupt_exist_connections": true,
"url": "https://example.com/latency-test",
"interval": "3m",
"tolerance": 50,
"include": "",
"exclude": ""
}
]
}
出站类型
| 类型 | 说明 | 特有字段 |
|---|---|---|
| direct | 直接连接 | - |
| selector | 手动选择 | outbounds, include, exclude |
| urltest | 自动测试延迟 | url, interval, tolerance |
4. 路由配置 (route)
路由规则决定流量如何在不同出站连接间分配，是SingBox的核心功能。
{
"route": {
"rules": [
{
"id": "rule-1",
"type": "domain_suffix",
"payload": "example.com",
"invert": false,
"action": "route",
"outbound": "proxy-group-1"
}
],
"rule_set": [
{
"id": "ruleset-1",
"type": "local",
"tag": "blocklist",
"format": "binary",
"path": "blocklist.srs"
}
],
"final": "direct",
"auto_detect_interface": true,
"default_interface": "",
"find_process": false,
"default_domain_resolver": {
"server": "remote-dns",
"client_subnet": ""
}
}
}
规则类型 (RuleType)
路由规则支持多种匹配类型：
| 类型 | 说明 | payload格式 |
|---|---|---|
| domain | 完整域名匹配 | "example.com" |
| domain_suffix | 域名后缀匹配 | ".example.com" |
| domain_keyword | 域名关键字匹配 | "example" |
| domain_regex | 域名正则匹配 | "^.*\.example\.com$" |
| ip_cidr | IP地址段匹配 | "192.168.1.0/24" |
| port | 端口匹配 | "80,443" |
| process_name | 进程名匹配 | "chrome.exe" |
| rule_set | 规则集匹配 | "ruleset-id" |
规则动作 (RuleAction)
| 动作 | 说明 |
|---|---|
| route | 路由到指定出站 |
| route-options | 带选项的路由 |
| reject | 拒绝连接 |
| hijack-dns | DNS劫持 |
| sniff | 流量嗅探 |
| resolve | DNS解析 |
5. DNS配置 (dns)
DNS配置控制域名解析行为，支持多种DNS服务器类型和规则。
{
"dns": {
"servers": [
{
"id": "remote-dns",
"tag": "remote-dns",
"type": "https",
"server": "8.8.8.8",
"server_port": "443",
"path": "/dns-query",
"detour": "proxy-group-1"
}
],
"rules": [
{
"id": "dns-rule-1",
"type": "domain_suffix",
"payload": "example.com",
"action": "route",
"server": "remote-dns",
"strategy": "prefer_ipv4"
}
],
"disable_cache": false,
"disable_expire": false,
"independent_cache": true,
"client_subnet": "",
"final": "local-dns",
"strategy": "default"
}
}
DNS服务器类型 (DNSServer)
| 类型 | 说明 | 示例 |
|---|---|---|
| local | 使用系统DNS | "type": "local" |
| tcp | TCP协议DNS | "type": "tcp", "server": "8.8.8.8", "server_port": "53" |
| udp | UDP协议DNS | "type": "udp", "server": "8.8.8.8" |
| tls | DNS over TLS | "type": "tls", "server": "8.8.8.8" |
| https | DNS over HTTPS | "type": "https", "server": "8.8.8.8", "path": "/dns-query" |
| quic | DNS over QUIC | "type": "quic", "server": "8.8.8.8" |
| fakeip | 伪造IP | "type": "fakeip", "inet4_range": "100.64.0.0/10" |
6. 实验性功能配置 (experimental)
实验性功能包含高级选项和不稳定特性。
{
"experimental": {
"api": {
"external_controller": "127.0.0.1:20123",
"external_ui": "",
"secret": "your-secret",
"default_mode": "rule"
},
"cache_file": {
"enabled": true,
"path": "cache.db",
"store_fakeip": true,
"store_rdrc": false
}
}
}
配置文件生成流程
GUI.for.SingBox采用结构化方式生成最终配置文件，流程如下：
配置生成过程中，系统会根据内核版本自动调整配置格式，例如为稳定版分支适配不同的DNS配置：
// 稳定版分支DNS配置适配逻辑
const _adaptToStableBranch = (config: Recordable) => {
config.dns.rules.unshift({
action: 'route',
server: config.route.default_domain_resolver.server,
outbound: 'any',
})
delete config.route.default_domain_resolver
// ...其他适配逻辑
}
完整配置示例
以下是一个包含主要功能的完整配置示例：
{
"log": {
"disabled": false,
"level": "info",
"output": "",
"timestamp": false
},
"experimental": {
"api": {
"external_controller": "127.0.0.1:20123",
"external_ui": "",
"external_ui_download_url": "",
"secret": "",
"default_mode": "rule",
"access_control_allow_origin": ["*"]
},
"cache_file": {
"enabled": true,
"path": "cache.db",
"store_fakeip": true,
"store_rdrc": false
}
},
"inbounds": [
{
"id": "mixed-in",
"type": "mixed",
"tag": "mixed-in",
"enable": true,
"mixed": {
"listen": {
"listen": "0.0.0.0",
"listen_port": 20122,
"tcp_fast_open": true,
"tcp_multi_path": false,
"udp_fragment": true
},
"users": []
}
}
],
"outbounds": [
{
"id": "direct",
"tag": "direct",
"type": "direct",
"outbounds": []
},
{
"id": "proxy-group",
"tag": "Proxy",
"type": "selector",
"outbounds": [
{
"id": "sub-1",
"tag": "Subscription 1",
"type": "Subscription"
}
],
"interrupt_exist_connections": true
}
],
"route": {
"rules": [
{
"id": "rule-1",
"type": "domain_suffix",
"payload": "example.com",
"invert": false,
"action": "route",
"outbound": "proxy-group"
}
],
"rule_set": [],
"final": "direct",
"auto_detect_interface": true,
"find_process": false
},
"dns": {
"servers": [
{
"id": "remote-dns",
"tag": "remote-dns",
"type": "https",
"server": "8.8.8.8",
"server_port": "443",
"path": "/dns-query",
"detour": "proxy-group"
},
{
"id": "local-dns",
"tag": "local-dns",
"type": "udp",
"server": "114.114.114.114",
"server_port": "53"
}
],
"rules": [],
"disable_cache": false,
"final": "local-dns",
"strategy": "default"
},
"mixin": {
"priority": "gui",
"config": "{}"
},
"script": {
"code": ""
}
}
常见问题解决
1. 配置文件验证失败
问题表现：启动时提示JSON格式错误或字段缺失。
解决方法：
- 使用在线JSON验证工具检查语法错误
- 确保所有必填字段都已提供
- 检查字段类型是否正确（如数字类型不要加引号）
2. 无法连接到入站端口
问题表现：客户端无法连接到配置的入站端口。
排查步骤：
- 检查端口是否被其他程序占用
- 确认"enable"字段设置为true
- 检查防火墙设置是否允许该端口
- 验证监听地址是否正确（0.0.0.0表示所有接口）
3. DNS解析异常
问题表现：域名无法解析或解析结果不正确。
解决方法：
- 检查DNS服务器地址是否可达
- 验证DNS规则配置是否正确
- 尝试禁用DNS缓存（"disable_cache": true）
- 检查是否启用了fakeip功能并正确配置
总结与展望
本文详细介绍了GUI.for.SingBox配置文件的JSON结构和各字段含义，包括日志、入站/出站连接、路由规则和DNS配置等核心模块。通过合理配置这些字段，用户可以灵活控制SingBox的行为，实现高效、安全的网络流量管理。
随着SingBox的不断发展，配置格式可能会引入新的字段和功能。建议用户：
- 定期查看项目更新日志
- 使用GUI界面进行配置，减少手动编写JSON的错误
- 备份重要配置文件，以便在更新或出现问题时快速恢复
希望本文能帮助你更好地理解和使用GUI.for.SingBox，如有任何问题或建议，请在项目仓库提交issue反馈。
请点赞、收藏本文，关注项目更新，不错过新功能和最佳实践！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
