实验性

experimental 块承载四块松散相关的功能：持久化缓存文件、与 Clash 兼容的 RESTful API、V2Ray gRPC 统计 API，以及内嵌 pprof / 运行时调试端点。

字段	类型	默认值	允许值	描述
cache_file	*CacheFileOptions	(unset)	CacheFileOptions	持久化状态缓存。
clash_api	*ClashAPIOptions	(unset)	ClashAPIOptions	与 Clash 面板兼容的外部控制器。
v2ray_api	*V2RayAPIOptions	(unset)	V2RayAPIOptions	与 V2Ray 客户端兼容的 gRPC 统计服务。
debug	*DebugOptions	(unset)	DebugOptions	内嵌 pprof 端点与 GC 调优。

源码： option/experimental.go:5-10 · 锚定版本 v1.14.2 (af6e64c)

cache_file

持久化磁盘缓存，用于 fakeip 租约、选中代理记忆、RDRC 条目、DNS 缓存（store_dns）及其他运行时状态。

字段	类型	默认值	允许值	描述
enabled	bool	false	true | false	启用缓存文件。
path	string	cache.db	<file path>	缓存数据库的存储位置。
cache_id	string	(unset)	<string>	同一缓存文件内的命名空间前缀。多个 sing-box 实例共享一个缓存文件时有用。
store_fakeip	bool	false	true | false	持久化 fakeip 租约表。
store_rdrc	bool	false	true | false	已弃用，由 store_dns 取代。持久化旧式 DNS 地址过滤字段所用的「被拒绝 DNS 应答」缓存。
rdrc_timeout	badoption.Duration	7d	<duration>	rdrc 条目在缓存中保留的有效期。
store_dns	bool	false	true | false	把 DNS 缓存持久化到缓存文件，重启后仍然保留；遵循 dns.disable_expire 与 dns.optimistic。

源码： option/experimental.go:12-20 · 锚定版本 v1.14.2 (af6e64c)

clash_api

Clash RESTful API 的内置实现，可与 metacubexd、Yacd、Clash Dashboard 等 Clash API 消费者直接对接。

字段	类型	默认值	允许值	描述
external_controller	string	(unset)	<host:port>	RESTful API 监听地址。
external_ui	string	(unset)	<dir path>	用作面板的本地目录。
external_ui_download_url	string	https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip	<URL>	external_ui 为空时自动下载的 tarball URL。
external_ui_download_detour	string	(direct)	<outbound tag>	下载使用的出站。
secret	string	(unset)	<bearer token>	所有 API 调用所需的 Bearer 令牌，强烈建议设置。
default_mode	string	rule	rule | global | direct | <custom>	通过 API 报告的初始隧道模式。也接受自定义值，但非标准面板会忽略它们。
access_control_allow_origin	badoption.Listable[string]	[]	<origin>	API 的 CORS 允许列表。
access_control_allow_private_network	bool	false	true | false	允许来自私有网络的 preflight 请求。

源码： option/experimental.go:22-42 · 锚定版本 v1.14.2 (af6e64c)

另有五个字段（cache_file、cache_id、store_mode、store_selected、store_fakeip）属于顶层 cache_file 块 —— 在 clash_api 上设置其中任何一个都会导致启动失败。

v2ray_api

V2Ray 兼容的 gRPC 统计 API。若你已有 v2ray api stats query ... 这类工具且希望继续沿用，可以保留它。

字段	类型	默认值	允许值	描述
listen	string	(required)	<host:port>	StatsService 的 gRPC 监听地址。
stats	*V2RayStatsServiceOptions	(unset)	V2RayStatsServiceOptions	需要统计的对象。

源码： option/experimental.go:44-47 · 锚定版本 v1.14.2 (af6e64c)

v2ray_api.stats

字段	类型	默认值	允许值	描述
enabled	bool	false	true | false	启用统计服务。
inbounds	[]string	[]	<inbound tag>	需要统计流量的入站 tag。
outbounds	[]string	[]	<outbound tag>	需要统计流量的出站 tag。
users	[]string	[]	<user name>	按用户的计数器。

源码： option/experimental.go:49-54 · 锚定版本 v1.14.2 (af6e64c)

debug

Go 运行时调优块。多数字段直接对应 runtime / runtime/debug 包的旋钮。listen 字段暴露标准 net/http/pprof handlers。

字段	类型	默认值	允许值	描述
listen	string	(unset)	<host:port>	pprof 端点的监听地址（如 127.0.0.1:6060）。
gc_percent	*int	(Go default)	<int> | -1	GOGC 覆盖。-1 禁用 GC。
max_stack	*int	(Go default)	<bytes>	单 goroutine 栈上限。
max_threads	*int	(Go default)	<int>	GOMAXPROCS 风格的线程上限。
panic_on_fault	*bool	false	true | false	将不可恢复的运行时 fault 转为带栈跟踪的 panic。
trace_back	string	(Go default)	none | single | all | system | crash	GOTRACEBACK 设置。
memory_limit	*byteformats.MemoryBytes	(unset)	<bytes/MiB/GiB>	软内存上限；接受纯数字（字节）或带后缀的 256MiB 等。
oom_killer	*bool	false	true | false	持续超出 memory_limit 时让进程崩溃退出。

源码： option/debug.go:5-14 · 锚定版本 v1.14.2 (af6e64c)

示例

{
  "experimental": {
    "cache_file": {
      "enabled": true,
      "path": "cache.db",
      "store_fakeip": true
    },
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "secret": "<random>",
      "external_ui": "/etc/sing-box/ui"
    },
    "debug": {
      "listen": "127.0.0.1:6060",
      "memory_limit": "256MiB"
    }
  }
}

说明

• 在 clash_api 上设置缓存字段（cache_file、cache_id、store_mode、store_selected、store_fakeip）中的任何一个，都会使 Clash API 在启动时报错并提示改用 experimental.cache_file —— 请使用该块。
• store_rdrc 已弃用：请改为启用 store_dns，它持久化的是完整的 DNS 缓存，而不只是被拒绝的应答。
• debug.memory_limit 接受纯数字（字节）或 "256MiB" / "2GiB" 之类带后缀的字面量，由 byteformats.MemoryBytes 解析。

源码： option/experimental.go:5-54 · v1.14.2 (af6e64c)