Sublink Worker：我在上游之外补了什么

Sublink Worker 是我基于 7Sageer/sublink-worker 维护的社区 Fork。原项目提供了订阅解析、格式转换和多运行时部署等基础能力；这个分支没有重新包装这些已有功能，而是围绕我在长期使用中遇到的几个具体问题继续演进。

这些问题主要集中在三个地方：短链缺少明确的所有权、复杂规则难以稳定保存和恢复，以及 Surge 特有能力在通用转换模型中容易丢失。

上游仍在独立维护和更新，因此这个 Fork 不是所谓的“增强版替代品”。它更像一条面向特定使用场景的分支：保留上游架构，在需要的地方增加更明确的权限、状态与平台语义。

Sublink Worker - 订阅链接转换工具

Convert and optimize your subscription links easily

订阅链接转换工具

💡

延伸阅读：如果你对“用明确的数据模型、字段映射与序列化边界组织复杂转换逻辑”这一思路感兴趣，可以阅读《利用装饰器进行 OOP 开发的实践》。文章以 TypeScript 装饰器为例，进一步介绍 Class Model、声明式序列化、字段映射和接口调用的实现原理。

让短链拥有明确的修改权限

上游短链解决了 URL 太长的问题，但只要知道固定短码，理论上就可以重新写入它所指向的内容。对于长期配置，这意味着一个正在被客户端定时读取的地址可能被意外覆盖。

从 v2.5 开始，这个 Fork 为短链加入 Token：创建短码时同时返回一个随机 Token；以后覆盖同一个短码，必须提供匹配的 X-Shortlink-Token。旧格式短链在第一次被重新写入时会完成认领，之后也进入相同的鉴权流程。

v2.6 又增加了显式的「通过短码加载」入口。新格式短码只有在 Token 正确时，才能把原始配置重新载入编辑器；缺少 Token 和 Token 不匹配分别返回不同的错误。相比“把短链粘贴进输入框后自动展开”，这个过程更明确，也不会在用户只是粘贴文本时触发读取。

这里的边界需要说清楚：Token 保护的是覆盖短码和重新载入编辑数据的权限。客户端用于更新订阅的短地址仍可直接访问，否则 Surge、Clash 或 Sing-Box 无法自动刷新。因此，短码本身依然应该视为一种访问凭据，而不是公开分享的普通链接。

让 Surge 始终订阅短地址

早期实现虽然能生成 Surge 短链，但返回配置中的 #!MANAGED-CONFIG 仍然指向展开后的长 URL。客户端第一次添加的是短地址，后续定时更新却绕回了长地址；即使重新映射短码，已经订阅的设备也无法得到变化。

v2.7 在短链跳转时把同源短地址传给 Surge 构建器，再写回 #!MANAGED-CONFIG。这样客户端会一直订阅 /s/<code>：更新短码映射后，下一次刷新就能取得新配置，不需要在每台设备上重新粘贴地址。

这项改动看似只是保留一个 URL，实际修复的是短链“创建后还能继续维护”的完整生命周期。

从固定规则扩展为可组合策略

上游已经支持预设规则和自定义规则，但当规则数量增加后，单纯填写一个出站名称很容易产生失效引用，也难以在不同客户端之间保持一致。

这个 Fork 从 v2.9 开始扩展规则系统：

新增 15 个可选规则组，覆盖通讯、媒体、开发、AI 等常用服务，但不改变原有预设；
自定义规则集可以从 MetaCubeX、blackmatrix7、Loyalsoldier、ACL4SSR 或自定义地址生成，并注册为独立策略组；
自定义规则的出站从自由文本改成有效目标下拉框，来源删除或改名后会自动清理失效引用；
未命中规则的流量可以明确选择交给节点选择、DIRECT、REJECT 或自定义策略组；
域名精确匹配成为独立字段，IP CIDR 则可逐条决定是否移除 no-resolve，避免客户端拿域名评估规则时直接漏到 Final。

这些状态会一起写入分享 URL，也能通过短码重新载入。重点不只是“多了几个选项”，而是规则、规则集和出站之间的引用关系可以完整往返。

把 Surge 特有能力保留下来

跨客户端转换最容易犯的错误，是把“目标端不支持”误写成“找一个相似字段代替”。这个 Fork 对 Surge 专属能力选择显式保留或显式跳过。

v2.10 增加了 Snell 解析和输出。Snell 节点可以从 Surge 配置、Clash YAML 或项目自定义的 snell:// 形式导入，并原生输出到 Surge 与 Clash（Mihomo）；Sing-Box 没有对应出站，因此会跳过并给出警告，而不是生成一份看似完整但无法使用的配置。

同一版本还加入了 Surge DEVICE:<name> 出站。用户可以先声明 Ponte 设备，再把自定义规则或规则集直接指向这台设备。Surge 会原样输出 DEVICE: 策略；Clash 与 Sing-Box 没有等价语义，所以相关规则在这两个目标中被跳过，不创建伪造的代理组。

自定义 Surge 基础配置中的 [Host]、[URL Rewrite]、[Header Rewrite]、[MITM]、[Script] 与 [SSID Setting] 也会被解析并按标准顺序写回。它解决的是另一个常见问题：节点和规则转换成功了，但用户原本依赖的本地覆写、脚本或 MITM 配置在生成结果中悄悄消失。

自定义策略组成为一等对象

v2.11 进一步加入自定义策略组。用户可以创建 select、url-test、fallback 或 load-balance，并引用节点选择、自动选择、地区组、规则组、规则集、Surge 设备或其他自定义组。

这些组不只是输出时临时拼接的文本，而是表单状态中的一等对象：可以成为自定义规则、自定义规则集和漏网之鱼的目标，也会随分享链接与短码恢复。被引用对象删除或改名时，界面会清理失效成员；名称与规则组冲突时，显式定义的自定义组优先，避免同名对象被静默替换。

不同平台仍按自身能力输出。Sing-Box 的 fallback 与 load-balance 会降级为 urltest，Surge 的 load-balance 会降级为 url-test，DEVICE: 成员只在 Surge 中保留。这里追求的不是三份配置字符完全一致，而是尽可能保留同一份策略意图。

修复长期运行才会出现的问题

除了可见功能，这个 Fork 也处理了一些只在真实使用中暴露的边界：

Node.js 的 setTimeout 无法可靠承载超过约 24.85 天的定时器，原先 30 天的内存 KV 过期时间会溢出并接近立即删除；现在改为记录绝对过期时间，并在读取时判断；
CONFIG_TTL_SECONDS=0 曾被 || 当成未设置，无法表达“永久保存”；改用空值判断后，0 可以正确传到存储层；
节点去重曾使用前缀匹配，VMESS_OVER_WS 可能因为已有 VMESS_OVER_WS_CDN 而被误判重名；现在只有名称完全相同时才追加编号。

这些修复没有增加新的页面入口，却决定了短链、配置和节点名称能否在长时间运行后仍保持可预期。