快连kuailian macOS端导入自定义规则失败如何排查？
功能定位：自定义规则到底在做什么
在快连 kuailian macOS 端，自定义规则是 Split-Tunneling 2.0 的延伸模块，负责把“域名、IP 段、进程名、GeoIP”四类条件即时编译成 ipfw/pf 可识别语法，再注入系统包过滤层。规则一旦加载失败，客户端会回退到全局直连，表现为“节点正常却访问不到目标网站”。理解这一链路，就能在“导入失败”提示出现时有针对性地拆成三段：文件格式→客户端路径→系统权限。
最新版本前提与入口差异
截至当前的最新版本（v7.3.2，2026-03-28），macOS 端提供两处入口：
① 主界面右上角“⋮”→设置→分流设置→自定义规则→“＋”号；
② 顶部菜单栏快连图标→偏好设置→高级→分流→导入规则。
两条路径最终落在同一解析器，但入口①会额外做一次“UTF-8 with BOM”自动转换，入口②则完全原样读取。经验性观察：入口②对纯 ASCII 文件更稳，入口①对含中文注释的 YAML 更友好。
标准格式与易错细节
YAML 最小可运行模板
规则文件必须满足：根节点为 rules，数组元素顺序即匹配优先级；每条必须同时出现 outbound（proxy/direct/reject）；cidr 只接受 4 段掩码写法，/xx 范围 8–32；文件总大小 ≤ 512 KB（经验性观察：超过 6000 行后解析耗时呈指数上升）。常见报错码“Import-102”即因 cidr 写成 192.168.0/16 缺位导致。
JSON 兼容模式
若团队已有 Surge/Clash 存量 JSON，可把根键改为 kuailian_rules 再导入，客户端会提示“检测到第三方格式，已自动转换”，但 process_name 字段会被丢弃，需手动补回。
失败现象与三阶排查表
| 提示文案 | 可能根因 | 验证动作 | 处置 |
|---|---|---|---|
| Import-101 格式非法 | YAML 缩进混用 Tab | cat -A file.yml | grep '^I' | 统一空格，删除 BOM 若从 Windows 拷贝 |
| Import-103 路径超时 | 文件放 iCloud 下载目录 | ls -l@ 查看 com.apple.quarantine | mv 到 ~/Downloads 并 xattr -c |
| Import-201 权限拒绝 | 未给“系统扩展”授权 | 系统设置-隐私-网络扩展 | 重启后再次允许 Kuailink Networks |
沙盒与 quarantine 的隐性拦截
macOS 自 13 Ventura 起对“下载自浏览器”文件默认加 com.apple.quarantine 属性。快连的导入器调用 NSOpenPanel，若检测到该属性会触发沙盒二次确认，而在入口①的自动转换阶段，若文件仍被 iCloud 占位（.icloud 扩展名），解析线程会等待数十秒后抛出 Import-103。解决顺序：先本地落地→清除隔离属性→再导入，可 100% 绕过。
与系统 pf 冲突时的回退逻辑
经验性观察：若用户同时安装 Little Snitch 或 Lulu，第三方防火墙会抢先加载 pf 锚点，导致快连写入规则时返回“Device busy”。客户端在三次重试后自动回退到“进程级分流”，仅对 process_name 生效，域名与 cidr 规则被静默丢弃。此时日志位于 ~/Library/Logs/Kuailian/routing.log，关键字“pf busy, fallback to process”。处置：临时停用第三方防火墙的 pf 模块，再点“重新加载”。
版本差异与迁移建议
v7.2 及更早版本使用 JSON 专属 schema，升级 v7.3.2 后首次启动会提示“发现旧规则，是否迁移”。若点“稍后”，旧文件被重命名为 rules.json.bak，不会自动生效；若点“迁移”，客户端会把 reject 动作映射为 outbound: reject，但把 IP-CIDR 6 写成 cidr6，需手动把关键字改回 cidr 以保持一致。建议升级前先把旧规则导出一份 Git 备份，方便 diff。
验证与观测方法
- 导入成功后，在 设置-分流设置-自定义规则 末尾会出现“已加载 127 条，耗时 0.18 s”字样；
- 打开终端执行
sudo pfctl -sr | grep kuailian，若返回锚点 kuailian_routing 即表示注入成功； - 用 Safari 访问 https://ip.skk.moe，对比关闭/开启代理时的出口 IP，可快速验证域名规则是否命中。
何时不该用自定义规则
- 公司网络已下发全局 PAC，且禁止本地 pf 修改，此时导入会被 MDM 立即回滚；
- 设备为 M 系列芯片 + macOS 15 封闭模式（Lockdown Mode），系统扩展加载被禁用；
- 节点本身为“游戏专线”标签，已内置固定路由表，叠加自定义规则反而多一次 NAT，延迟可见提升。
最佳实践 10 条速查表
- 规则文件 < 5000 行，先本地 YAML Lint 通过再导入；
- 统一用空格缩进，禁用 Tab；
- 把常用域名放前，长尾后缀放后，减少匹配回溯；
- GeoIP 库每周三凌晨云端更新，若发现 cn 分流异常，先检查日期戳；
- 进程名务必给绝对路径，升级应用后第一时间 diff 路径是否变动；
- 重要规则用 # 注释写日期与作者，方便多人协作；
- 导入后点“导出备份”生成带签名的 .krules 包，可一键回滚；
- 不要把广告拦截列表直接粘进来，用专门的 reject 模块更省 CPU；
- 出现 Import-201 时优先重启系统，再考虑关闭 csrutil；
- 每季度用
brew install yq做格式化，保持团队风格一致。
FAQ：macOS 导入自定义规则失败
Import-102 提示 cidr 格式错误，但目测没错？
把文件用 cat -n 显示行号，常见是中文全角“／”或掩码后多空格，复制到纯文本再导入即可。
系统扩展已允许，仍报 Import-201？
检查是否开了 Lockdown Mode；若公司 MDM 下发配置描述文件禁止网络扩展，只能联系管理员放行。
规则导入成功但完全不生效？
大概率是第三方防火墙抢先加载 pf，临时停用其网络模块，再在快连里点“重新加载”即可。
能否一次导入多条 GeoIP？
可以，但建议把最常用的国家放前面，条目超过 200 行后解析耗时明显，晚高峰可能拖慢首次握手。
导入后如何快速回退？
在 设置-分流设置-自定义规则 右上角点“导出备份”会生成带时间戳的 .krules，想回退时直接双击即可。
收尾：下一步行动
自定义规则导入失败并非软件缺陷，而是格式、沙盒、权限三重关卡的自然结果。按本文三阶排查表操作，十分钟内即可定位。若仍卡住，把 ~/Library/Logs/Kuailian/routing.log 最近 50 行贴到官方工单，可缩短一半响应时间。下次更新前，先用 yq 做格式体检，再养成“导入即备份”习惯，就能把试错成本压到最低。