Shadowrocket 模块深度配置指南：从入门到精通的完整实践手册
模块机制概述：理解 Shadowrocket 的扩展架构
Shadowrocket 的模块（Module）系统是其区别于基础代理工具的核心竞争力，基于类似 Surge 的模块规范构建，模块本质上是一组预配置的规则集合、脚本逻辑、MITM 证书配置和主机映射的封装单元，允许用户在不修改主配置文件的前提下,动态注入功能扩展。
技术原理：模块通过覆写（Override）机制工作，加载后会在内存中合并到当前配置，优先级遵循"后加载覆盖先加载"原则，模块文件通常采用 .sgmodule 扩展名（部分社区资源使用 .conf），内部采用 INI 格式结构，包含 [Script]、[Rule]、[MITM]、[Host] 等段落标识。
环境准备与前置检查
1 系统兼容性验证
- iOS 版本：需 iOS 12.0+，建议使用 iOS 14+ 以获得完整的 JavaScript 引擎支持
- Shadowrocket 版本：确保更新至 2.2.0+（模块功能完善版本），当前 App Store 版本均支持
- 证书安装：若模块包含 HTTPS 解密（MITM）功能，需提前安装并信任 Shadowrocket 生成的 CA 证书
2 基础配置备份
进入 配置（Config） → 选择当前活动配置 → 编辑（Edit） → 导出（Export），通过 AirDrop 或邮件备份原始配置，模块调试过程中可能出现规则冲突,备份可确保快速回滚。
模块获取与安装方法论
1 远程 URL 安装（推荐）
适用于持续更新的功能模块（如去广告规则、定时签到脚本）：
- 获取模块链接：从 GitHub、Telegram 频道或社区论坛获取
.sgmodule直链（确保链接以 raw 内容形式提供） - Shadowrocket 内导入：
- 方法 A：复制链接 → 打开 Shadowrocket → 自动识别剪贴板内容 → 选择"安装模块"
- 方法 B：配置页面 → 模块（Modules） → 右上角 + 号 → 粘贴 URL → 下载
- 验证完整性：安装后检查模块列表中是否显示绿色勾选标志，红色感叹号表示解析错误
技术细节：Shadowrocket 支持 #!include 指令的嵌套引用，但出于安全考虑，默认禁止跨域引用本地文件，若模块包含子资源,需确保所有依赖均可公开访问。
2 本地文件导入
适用于自定义开发或离线环境：
- iCloud 同步：将
.sgmodule文件保存至iCloud Drive/Shadowrocket/目录，应用内自动识别 - 文件共享：通过 iTunes 文件共享或"文件"应用直接拖拽至 Shadowrocket 沙盒
- 文本导入：长按模块内容 → 复制 → Shadowrocket → 模块 → 从剪贴板添加
3 手动创建模块
针对特定需求的轻量级定制：
#!author=YourName
#!icon=https://example.com/icon.png
[Rule]
DOMAIN,ad.example.com,REJECT
DOMAIN-SUFFIX,ads.com,REJECT
[Script]
http-response ^https?://api\.app\.com/v\d+/ad script-path=removeAd.js,requires-body=true
[MITM]
hostname = api.app.com保存为 .sgmodule 文件后按本地导入流程加载。
模块类型与实战配置
1 规则增强型模块
典型应用：GeoIP 数据库更新、分流规则集、广告拦截清单
配置要点：
- 检查
[Rule]段落的优先级，使用RULE-SET引用外部规则集时，确保 URL 可访问 - 注意
FINAL规则的位置，模块中的规则默认插入到主规则之前，可能改变流量走向
调试技巧：开启 日志（Log） → 记录所有流量（Capture all traffic），观察模块规则是否命中（显示为 Module Rule）。
2 脚本处理型模块
功能范畴：API 响应修改、自动签到、Cookie 刷新、界面优化
关键配置：
- 脚本引擎：Shadowrocket 支持 JavaScript 与部分 Python 脚本（需 iOS 15+ 的 Pythonista 环境）
- 执行时机：
http-request（请求阶段）与http-response（响应阶段）需严格区分 - MITM 声明：若脚本需解密 HTTPS 流量，必须在模块内声明
hostname，并在系统设置中信任证书
示例：京东签到模块配置
[Script]
cron "5 0 * * *" script-path=https://raw.githubusercontent.com/.../jd_sign.js,tag=京东签到3 网络层优化模块
应用场景：DNS 防污染、DoH/DoT 配置、Host 映射管理
注意事项：
[Host]段落支持通配符 和 ，但 Shadowrocket 的 Host 优先级低于 DNS 设置- 若模块包含
doh-server配置，确保所选 DoH 服务在目标网络环境下可访问（部分国内网络屏蔽海外 DNS）
高级管理与故障排查
1 模块冲突解决
当多个模块修改同一域名规则时：
- 优先级调整：在 模块 列表中，通过拖拽调整顺序，下方模块覆盖上方模块
- 选择性启用：使用开关临时禁用可疑模块，二分法定位冲突源
- 规则隔离：为特定应用创建独立配置（Configuration），避免全局模块干扰
2 性能优化策略
- 脚本超时：在
[Script]段落添加timeout=10防止脚本卡死导致请求失败 - 规则去重：定期使用 配置 → 编辑 → 诊断（Diagnose） 检查冗余规则
- 懒加载：对于不常用的模块（如特定游戏加速），使用 按需启用（On-Demand） 功能
3 调试与日志分析
启用详细日志： 设置 → 高级（Advanced） → 日志级别（Log Level） → Verbose
常见问题诊断：
- MITM 失败：检查证书有效期，iOS 16+ 需确保证书安装在"信任"存储区而不仅是"登录"
- 脚本不执行：验证正则表达式匹配 URL，检查
requires-body参数是否与脚本需求一致 - 模块加载失败：使用文本编辑器检查文件编码（必须为 UTF-8），确认无 BOM 头
安全合规与最佳实践
1 来源可信度验证
- 签名验证：优先选择带有
#!author和#!homepage声明的模块，避免使用来路不明的短链接 - 代码审计：对包含
[Script]的模块，审查脚本 URL 指向的内容，警惕收集敏感信息的恶意脚本 - 权限最小化：禁用模块中不必要的
network-changed事件监听和$notification权限
2 隐私保护建议
- 避免使用需要登录凭证的自动化脚本模块，除非确认其使用本地存储（
$persistentStore）而非云端同步 - 定期清理 脚本缓存（设置 → 高级 → 清除脚本缓存），防止旧版本脚本残留
3 法律合规边界
- 模块功能仅限个人网络优化使用，不得用于破解付费服务、绕过地理限制访问非法内容
- 企业用户需遵守《网络安全法》及公司 IT 政策，部分 MITM 模块可能违反企业安全策略
模块开发入门（附录）
对于希望自定义模块的用户,掌握以下模板结构：
#!name=示例模块 #!desc=功能描述 #!author=开发者ID #!icon=图标URL（可选） #!system=ios（平台限制，可选） [General] # 覆盖全局设置，如 dns-server, doh-server [Rule] # 规则语法：类型,内容,策略,标签（可选） [Script] # 脚本语法：类型,匹配模式,脚本路径,参数 [MITM] # hostname = 需要解密的域名 # ca-passphrase = 证书密码（高级） # ca-p12 = 证书内容（Base64） [Host] # 域名 = IP地址
测试流程：本地编辑 → 通过 iCloud 同步 → Shadowrocket 中禁用后重新启用 → 查看日志验证。
Shadowrocket 的模块系统赋予了 iOS 平台前所未有的网络流量操控能力，掌握模块的安装、调试与开发，意味着从"使用工具"进阶到"定制网络环境"，建议从成熟的社区模块（如神机规则、DivineEngine）入手，逐步理解其架构逻辑,最终构建符合个人需求的网络优化方案。
本文基于 Shadowrocket v2.2.45 版本撰写，部分功能可能随应用更新调整。
