模块

Chute 支持外部模块文件（.sgmodule），用于通过可复用、可分享的规则、脚本、MitM 主机和 DNS 映射来扩展配置。模块遵循 Surge 模块格式。

模块在 [Module] 段中定义：

[Module]
https://example.com/my-module.sgmodule
/Users/me/.chute/custom-module.sgmodule
~/.chute/another-module.sgmodule

http:// 与 https:// 模块会被远程获取；本地文件写成裸路径——/path/to/local-module.sgmodule 或 ~/.chute/local-module.sgmodule——保存配置时也会写回这种形式。写成 file:/// URL 也可以。读不出来的本地模块文件会被跳过，并在日志里留下一条警告。

模块文件结构

.sgmodule 文件遵循与主配置文件相同的语法。支持的段：

出于兼容性考虑，模块中的 [DNS] 段会被接受为 [Host] 的别名。

模块元数据

模块可以包含元数据指令（以 #! 开头的行）：

#!name = My Custom Module
#!desc = Blocks ads and trackers for example.com
#!system = ios,macos

#!system 是显示在模块编辑器中的信息性元数据；目前它不会限制加载——模块会在所有平台上生效。

#!arguments 可以出现多次；后声明的会覆盖先声明的。模块正文中的 {{{variable}}} 占位符会被替换为该变量在 #!arguments 里声明的默认值；没有声明默认值时替换为空字符串。目前没有任何应用提供覆盖模块参数的入口，所以生效的总是声明的默认值。

以 #!IOS-ONLY、#!MACOS-ONLY 或 #!TVOS-ONLY 为前缀的行只在对应平台生效，在其他平台上会被丢弃——无论它出现在模块中还是配置文件本身的哪个位置：

[Rule]
#!IOS-ONLY DOMAIN-SUFFIX,mobile-ads.example,REJECT
#!MACOS-ONLY PROCESS-NAME,Updater,REJECT

应用保存配置时前缀按原样保留：在本平台被排除的行既不会从文件里消失，也不会变成注释，所以同一份配置在其他平台上照常可用。

模块示例

#!name = Ad Block Module
#!desc = Block common ad domains
#!system = ios,macos

[Rule]
DOMAIN-SUFFIX,doubleclick.net,REJECT
DOMAIN-SUFFIX,googlesyndication.com,REJECT
DOMAIN-SUFFIX,googleadservices.com,REJECT

[Host]
localhost = 127.0.0.1

[MITM]
hostname = *.google-analytics.com

[URL Rewrite]
^https://example\.com/old-api https://example.com/new-api 302

模块 hostname 值中的 %APPEND% / %INSERT% 指令会被剥离，其主机名将被合并到 MitM 列表中；主机名前的 - 排除前缀会被保留。

模块的 [General] 段可以用 %APPEND%（追加到末尾）或 %INSERT%（插入到开头）扩展运行中配置的五个列表选项：skip-proxy、tun-excluded-routes、tun-included-routes、dns-server 和 always-real-ip。五个都会执行合并；两个路由列表分别由哪些平台的隧道读取，见包含路由与排除路由。这些值在模块应用时合并，在模块被移除或禁用时撤回。没有指令的值同样按追加处理并给出提示，因为不支持整体替换列表；其他 [General] 键会被忽略并给出提示。

[General]
skip-proxy = %APPEND% *.corp.example, 10.20.0.0/16

模块生命周期

• 模块在主配置解析完成后加载。
• 来自模块的规则、脚本、MitM 主机和 DNS 主机将被添加到运行时管理器中。
• 模块的 [Rule] 行排在 Tailscale 自动规则之后、配置自身的规则之前，按模块加载顺序排列。这与 Surge 一致，因此广告拦截模块的 REJECT 不会被配置中更早的规则遮住。
• 配置重新加载后，来自模块的 [Map Local]、[Body Rewrite] 以及 [General] 合并会重新应用。
• 当模块被移除或禁用时，其所有规则、脚本和主机都将被取消注册。
• 远程模块内容在隧道启动时获取，仅当配置重新加载导致 [Module] URL 列表发生变化时才会重新获取。