一键导入是怎么实现的：URL Scheme 唤起客户端原理

一键导入，就是把“复制粘贴”交给系统去做

订阅一键导入的原理是：用户中心的按钮背后是一条以客户端专属协议名开头的链接，系统据此唤起已安装的客户端，并把订阅地址作为参数传过去，客户端再自行下载配置。 它没有改变订阅本身，客户端最后保存的仍是那条订阅地址，后续更新与手动导入完全相同。

理解这一点有两个用处：一键导入失败时，你知道可以随时退回手动导入；看到陌生的一键导入链接时，你知道它能做到什么、为什么不该随便点。手动导入的通用流程见 订阅导入六步流程。

URL Scheme 是什么

平时见到的网址以 https:// 开头，这里的 https 就是一种协议名（scheme），系统知道应该交给浏览器处理。应用安装后，也可以向操作系统登记自己的协议名，例如某个客户端登记了 clash，以后凡是以 clash:// 开头的链接，系统都会交给它。

各平台的登记方式不同，但效果相似：

平台	登记方式（概念层面）	用户可感知的表现
Windows	安装时写入注册表的协议关联	浏览器弹出“是否打开某某应用”
macOS	应用包内声明可处理的协议名	浏览器询问是否允许打开应用
iOS / iPadOS	应用声明的自定义协议	弹出“在某应用中打开”确认
Android	应用声明能处理的链接类型	可能出现“选择打开方式”列表

一条一键导入链接由哪几部分组成

以 Clash 系客户端常见的写法为例，结构大致是：

clash://install-config?url={经过 URL 编码的订阅地址}&name={显示名称}

可以拆成三段理解：

1. 协议名：决定由哪个客户端接手。不同客户端使用不同的协议名，sing-box、Shadowrocket 等都有各自的写法，具体格式以客户端文档为准。
2. 动作：告诉客户端要做什么，这里是“安装一份配置”。
3. 参数：最重要的是订阅地址，有时还附带名称。订阅地址本身含有 ?、&、= 等字符，必须先做 URL 编码，否则客户端会把订阅地址里的参数误当成一键导入链接自己的参数，导致导入的地址被截断。

最后一点解释了一个现象：用户中心生成的一键导入按钮能用，自己手工拼的链接却导入了一个残缺的地址。

点击之后发生了什么

点击按钮
  └→ 浏览器发现不是 http/https，交给系统
       └→ 系统查找登记了该协议名的应用，并请求用户确认
            └→ 客户端被唤起，解析出订阅地址与名称
                 └→ 客户端请求订阅地址，下载并保存配置
                      └→ 用户在客户端里确认或启用这份配置

整个过程中，订阅地址只经过浏览器、系统和客户端三者，并不会额外发给第三方。真正向机场发起请求的仍是客户端，因此格式判断、流量信息显示等行为与手动导入一致。

点了没反应：五类常见原因

现象	可能原因	处理方式
完全没有任何提示	对应客户端未安装，或安装后从未打开过，协议尚未登记	先手动打开一次客户端再试
在 App 内置网页里点击无效	内置浏览器限制跳转到外部应用	用系统浏览器打开用户中心
打开了另一个客户端	多个客户端登记了同一协议名	在系统中调整默认打开方式，或改用手动导入
客户端打开了但提示失败	按钮对应的格式与客户端不匹配，或网络无法访问订阅地址	换对应按钮，或按更新失败思路排查
导入的配置节点为空	套餐状态异常或地址被截断	查看用户中心套餐状态，改用复制链接

手机上遇到这类问题更常见，因为系统对应用间跳转的确认更严格；平台差异可以参考 移动端客户端：iOS 与 Android。

自研客户端的“登录即用”是另一种机制

提供自研客户端的机场，常见做法是让用户在客户端里直接登录账号，客户端再通过机场的接口取得订阅并自动保存。这看起来也是“一键”，但与 URL Scheme 不同：它依赖账号登录，而不是把订阅地址交给系统转发；换设备时需要重新登录，退出登录通常会一并清除本机保存的配置。

两种机制可以并存。同一账号在自研客户端里登录使用，同时又通过一键导入把订阅放进第三方客户端，是不少人的做法。此时要记住，第三方客户端里保存的那份订阅不会随自研客户端退出而消失，清理设备时需要分别处理。自研客户端与第三方客户端的取舍，见 自研客户端与第三方客户端怎么选。

一键导入链接本身也是凭证

一键导入链接里完整包含了订阅地址，只是外面多套了一层。由此带来两个容易忽视的风险：

• 复制按钮链接等于复制订阅地址。 有人为了“方便家人一键导入”，把按钮链接转发出去，效果与直接分享订阅链接没有区别，相关风险见 订阅链接为什么不能分享。
• 陌生链接可以让你导入别人的配置。 一键导入并不检查订阅来自哪里。对方可以构造一条链接，让你的客户端导入一份由他控制的配置：节点指向他的服务器，规则决定你的哪些流量经过那里。点击前看清来源，只在官方用户中心里使用。

另外，客户端唤起时通常会显示即将导入的地址或名称，确认弹窗不要一路点过，看一眼域名是否与你的机场一致。

一键导入失败时的退路

一键导入只是便利功能，不可用时直接回到手动方式：在用户中心复制订阅地址，打开客户端新建订阅、粘贴、更新。两种方式得到的结果相同，后续的验证步骤也一样，可以对照 导入后的五项检查。更多关于订阅格式与更新的内容，见 订阅链接导入与更新专题。