Config Scripts zh

配置脚本

🌐 English · Русский · 中文

配置脚本是一小段 JavaScript，会在内核加载配置之前重写该配置文件。你可以借此修改配置中的任何内容 —— DNS、规则、代理组 —— 而无需编辑 YAML，并且修改会在每次订阅更新后保留。

打开方式：配置文件 → 某个配置的 ⋮ → 配置脚本。

约定

脚本需定义一个函数：

function main(config) {
  // 随意修改
  return config
}

config 是整份配置，以普通 JavaScript 对象的形式提供，与内核将要收到的内容一致。你返回什么，就用什么替换它。

必须 return config。 修改了对象却忘记返回，等于什么都没保存。

这与其他 Clash 客户端使用的签名相同，因此在别处编写的脚本通常可以直接使用。

快速上手

点击插入模板，会填入一段可直接保存的空操作示例：

function main(config) {
  // config.dns.enable = true
  // config.rules.unshift("DOMAIN-SUFFIX,example.com,DIRECT")
  return config
}

然后点击检查。这不是语法高亮 —— 脚本会针对你自己的配置真实运行，因此能发现只在你的订阅上才会出现的问题。

保存会存储脚本并立即重建配置。如果脚本无法运行，则不会保存任何内容 —— 应用不会让配置文件带着一个坏掉的脚本。

运行此脚本开关可在不删除文本的情况下停用它。

示例

强制开启 DNS

function main(config) {
  config.dns = config.dns || {}
  config.dns.enable = true
  return config
}

让某个域名直连，并置于所有规则之前

function main(config) {
  config.rules = config.rules || []
  config.rules.unshift("DOMAIN-SUFFIX,bank.example,DIRECT")
  return config
}

移除从不使用的节点

function main(config) {
  config.proxies = (config.proxies || []).filter(p => !/test|expired/i.test(p.name))
  return config
}

调高所有 url-test 组的自动测速间隔

function main(config) {
  for (const group of config["proxy-groups"] || []) {
    if (group.type === "url-test") group.interval = 600
  }
  return config
}

只作用于某一个配置 —— 配置名称作为第二个参数传入：

function main(config, profileName) {
  if (profileName === "Work") config.mode = "global"
  return config
}

脚本能做什么、不能做什么

脚本只能看到配置，别无其他。没有文件访问、没有网络、没有 require、没有定时器 —— fetch、process 之类根本未定义。它无法下载规则列表，也无法向外发送数据。

它同样无法削弱应用自身的防护：ClashFest 的安全处理在你的脚本之后执行，因此脚本无法重新打开应用关闭的本地监听端口，也无法绕过 URL 清理。

运行超过 3 秒的脚本会被终止。配置转换本质上只是对象搬运，更慢的情况几乎都是死循环。

出问题时

如果脚本日后失效 —— 例如订阅更新删除了它依赖的某个键 —— 应用不会跟着一起坏掉。它会静默地在不使用该脚本的情况下重建配置并继续运行，因此凌晨三点的定时更新绝不会让你失去可用的隧道。打开编辑器点击检查即可看到原因。

错误带有稳定的代码：

代码	含义
E-60	语法错误 —— 无法解析脚本
E-61	没有 main —— 脚本必须定义 function main(config)
E-62	脚本运行时抛出错误
E-63	main() 未返回内容，或返回的不是配置对象
E-64	脚本运行过久已被终止（几乎总是死循环）
E-65	脚本生成的配置大得不合常理

完整代码列表见疑难解答。

说明

脚本与该配置文件的其他修改一并保存，因此能在订阅更新后保留，并且每次重建配置时都会重新运行 —— 更新时、启动 VPN 时以及保存时。

脚本运行后配置会被重新序列化，因此 config.yaml 中的键顺序可能改变、注释可能丢失。这是预期行为：内核读取的是值而非格式。你的原始订阅会原样保存在旁边。

面向运营方

如果你运营面板，且不希望用户重写你下发的配置，请发送：

X-Brand-Lock-Config-Script: true

编辑器将变为只读，配置文件上已保存的脚本也会停止运行。该限制在构建配置时生效，而不仅仅作用于界面，因此在你启用该标志之前保存的脚本同样会停止。

与其他策略类标头一样，它无需 X-Branding-Enabled 即可生效，并且在品牌化被关闭后依然保留。参见标头参考。