GKD订阅规则编写终极指南：快速上手与实战技巧

GKD订阅项目是一个由Adpro-Team维护的Android广告拦截规则库，通过精准的界面元素识别技术实现自动化广告关闭。本指南将带你从零开始，掌握GKD订阅规则编写的核心技能。

快速入门：环境配置与工具准备

开发环境搭建

必备工具清单：

• Node.js环境：建议安装18.x及以上版本
• 包管理工具：pnpm优先，npm次之
• 代码编辑器：Visual Studio Code + TypeScript插件

环境验证步骤：

1. 克隆项目仓库：git clone https://gitcode.com/gh_mirrors/gkd/GKD_subscription
2. 安装项目依赖：pnpm install
3. 运行检查脚本：pnpm run check

设备端准备

权限配置要点：

• 无障碍服务：开启GKD的无障碍权限
• 悬浮窗权限：允许GKD显示悬浮窗
• 截屏权限：Android 11以下设备需单独配置

核心技能：快照捕获与元素分析

三种快照获取方式

方式	适用场景	操作复杂度
悬浮窗按钮	快速捕获	简单
控制中心	常规使用	中等
网页审查工具	深度分析	复杂但推荐

网页审查工具使用技巧

网页审查工具是规则编写的利器，提供以下优势：

• 实时预览：即时查看选择器匹配结果
• 节点分析：深入了解界面元素结构
• 批量测试：验证多个规则的有效性

使用流程：

1. 确保设备与电脑在同一局域网
2. 在GKD设置中启用HTTP服务
3. 浏览器访问审查界面进行调试

实战演练：规则编写全流程

广告元素识别策略

常见广告特征：

• 关闭按钮：通常包含"关闭"、"跳过"等文本
• 特定ID：如"ad_close"、"native_close"等模式
• 固定位置：某些广告在特定界面区域出现

选择器编写技巧

基础语法模式：

• 精确匹配：[id="com.example.ad/close"]
• 后缀匹配：[id$="/close"]（匹配以"/close"结尾的ID）
• 文本匹配：[text="关闭广告"]

高级匹配技巧：

• 组合条件：[id$="/close"][text="关闭"]
• 层级关系：ViewGroup > [id$="/close"]
• 排除规则：:not([text="不再显示"])

完整规则示例

以下是一个典型的WPS广告拦截规则：

{
  id: 'cn.wps.moffice_eng',
  name: 'WPS',
  groups: [
    {
      key: 1,
      name: '分段广告-首页-文档列表广告',
      activityIds: [
        'cn.wps.moffice.main.StartPublicActivity',
        'cn.wps.moffice.main.local.HomeRootActivity'
      ],
      rules: [
        {
          matches: '[text="关闭当前广告"]',
          snapshotUrls: 'https://i.gkd.li/i/12505365'
        },
        {
          matches: '[id$="/nativeclose"]',
          snapshotUrls: [
            'https://i.gkd.li/i/12505350',
            'https://i.gkd.li/i/12505286'
          ]
        }
      ]
    }
  ]
}

质量保证：规则验证与提交

本地测试流程

关键检查点：

1. 语法正确性：TypeScript编译无错误
2. 选择器有效性：在审查工具中验证匹配
3. 快照关联性：确保截图与规则描述一致

提交规范

文件结构要求：

• 每个应用独立文件：src/apps/应用ID.ts
• 命名规范：使用应用包名作为文件名
• 元信息完整：必须包含id和name字段

质量检查清单：

• [ ] 规则分类符合标准
• [ ] 选择器简洁高效
• [ - ] 快照URL可正常访问
• [ ] 无重复或冲突规则

进阶技巧：高级规则编写

多活动场景处理

当应用在不同界面显示相同广告时，需要指定多个activityIds：

activityIds: [
  'com.example.MainActivity',
  'com.example.DetailActivity'
]

延迟点击配置

对于需要等待加载的元素，可配置延迟时间：

actionDelay: 1000 // 延迟1秒后点击

常见问题与解决方案

选择器过匹配

症状：规则匹配到非广告元素 解决方案：增加更具体的约束条件，或使用排除规则

规则失效

症状：更新应用后规则不再生效 解决方案：重新捕获快照，分析界面变化

性能优化

优化策略：

• 避免过于复杂的正则表达式
• 优先使用ID选择器
• 减少不必要的层级嵌套

总结与最佳实践

通过本指南的学习，你已经掌握了GKD订阅规则编写的核心技能。记住以下关键要点：

规则编写黄金法则：

1. 精确性优先：确保规则只匹配目标广告
2. 简洁性至上：避免过度复杂的匹配逻辑
3. 可维护性考虑：为后续更新预留灵活性

持续学习建议：

• 定期查看官方文档：CONTRIBUTING.md
• 学习优秀规则案例：src/apps/
• 参与社区讨论，分享经验心得

现在就开始你的GKD订阅规则编写之旅吧！每一个高质量的规则贡献，都将为更多用户带来纯净的应用体验。