EeveeSpotify 项目架构剖析:如何伪装成 Premium?三大核心模块划分与协作机制
EeveeSpotify 项目架构剖析:如何伪装成 Premium?三大核心模块划分与协作机制
EeveeSpotify 是一款面向 iOS 的 Spotify 增强 tweak(插件),通过拦截并实时修改 App 的网络请求,让 Spotify 认为你拥有 Premium 订阅,实现免费无广告收听,同时支持 Musixmatch、Genius 等多个来源的自定义歌词。本文带你剖析它的 Premium(高级版权限伪造)、Lyrics(歌词替换)、Settings(设置界面)三大核心模块是如何划分与协作的,即使你是新手也能看懂整体架构。
一、先看图:EeveeSpotify 最终效果
下图是它伪造的 "Your Premium" 页面——订阅计划被改名为 Eevee,并列出无广告收听、任意顺序播放等权益:
这个漂亮的"假订阅页",正是 Premium 模块用 Protobuf 序列化的结果。下面我们进入源码。
二、总体架构:入口与"版本路由器"
整个 tweak 的代码集中在 Sources/EeveeSpotify/ 目录,顶层结构如下:
Sources/EeveeSpotify/
├── Tweak.x.swift # 入口:模块装配与版本分发
├── SessionProtection.x.swift # 会话保护:防止被强制登出
├── Premium/ # 模块一:Premium 订阅伪造
├── Lyrics/ # 模块二:多来源歌词替换
├── Settings/ # 模块三:App 内设置界面
├── Shared/ # 公共工具与模型
├── Experiments/ # 实验性功能
└── Dependencies/ # XMLCoder 等第三方库
入口文件 Tweak.x.swift 定义了核心结构体 EeveeSpotify,它做三件事:
- 识别 Spotify 版本:读取
CFBundleShortVersionString,映射到 VersionHookTarget(如.lastAvailableiOS14、.v91、.latest)。因为不同版本 Spotify 的内部类名不同,钩子必须"对症下药"; - 按用户配置启用模块:检查
UserDefaults中的 patchType、lyricsSource 等选项,决定激活哪些 Hook 组; - 激活各功能组:基于 Orion 框架的
HookGroup机制,同类钩子被归入同一个 Group(如BasePremiumPatchingGroup、BaseLyricsGroup),统一激活,代码组织非常清晰。
这种"入口路由 + 版本分组 + 配置驱动"的设计,是它能稳定支持多个 Spotify 版本的关键。
上图展示了项目内置的 resolveconfiguration.bnk 资源(见 layout/Library/Application Support/EeveeSpotify.bundle/resolveconfiguration.bnk)——一份可整体替换远程配置的"补丁数据包"。
三、Premium 模块:如何"骗过" Spotify?
源码位置:Sources/EeveeSpotify/Premium/
EeveeSpotify 的核心原理是:拦截 Spotify 加载用户数据的请求,反序列化后实时修改参数。具体分为两条路径(由 EeveePatchType 枚举控制):
- requests 模式:逐项修改远程配置。核心逻辑在 DynamicPremium+ModifyingFunctions.swift,它遍历一份
propertyReplacements替换表,把enable_ads、enable_playback_timeout_service等几十个开关逐一关掉或移除; - 整体替换模式:直接用本地
resolveconfiguration.bnk覆盖整份远程配置。
同时,订阅卡片、权益列表等 UI 数据通过 Protobuf 重新构造,例如 DynamicPremium+PremiumPlanRow.swift 将计划名改为 "EeveeSpotify",徽章数据由 YourPremiumBadge.pb.swift 生成——这就是第二节的 "Eevee" 订阅卡的来源。
辅助文件还包括:
| 文件 | 作用 |
|---|---|
| Lik edSongsEnabler.x.swift | 启用红心收藏 |
| TrackRowsEnabler.x.swift | 让艺术家页面显示曲目列表 |
| ServerSidedReminder.x.swift | 针对服务端限制的提示 |
⚠️ 注意:部分功能(如超高音质、Spotify Connect、AI DJ)是服务端限制,客户端无法绕过,这一点在 README.md 中有明确说明。
四、Lyrics 模块:Repository 模式的多来源歌词
源码位置:Sources/EeveeSpotify/Lyrics/
歌词模块是典型的策略模式 + 仓储(Repository)模式设计:
- 统一协议:LyricsRepository.swift 定义了一个方法
getLyrics(_:options:),所有歌词源都必须实现它; - 四个可插拔实现:分别位于 Repositories/ 目录下的
GeniusLyricsRepository、LrclibLyricsRepository、MusixmatchLyricsRepository、PetitLyricsRepository,每个源的数据模型独立存放在 Models/ 对应子目录(如 Genius/、Lrclib/); - 来源枚举驱动:LyricsSource.swift 定义了 genius / lrclib / musixmatch / petit / notReplaced 五个选项,当前构建默认启用 Musixmatch;
- UI 钩子层:CustomLyrics.x.swift 负责钩住"正在播放"页的歌词滚动控制器,替换显示内容。
主入口 CustomLyrics.x.swift 的加载流程也值得学习:先用缓存 → 再问播放器当前轨道 → 最后才调 API 兜底取元数据,层层递进,兼顾性能与可靠性。此外还有 +ScrollCrashFix、+HideOnError 等按功能切分的扩展文件,单一职责做得很到位。
五、Settings 模块:把设置页"塞进" Spotify
源码位置:Sources/EeveeSpotify/Settings/
这个模块解决"用户在哪里配置插件"的问题,分两层:
1. 入口注入(Hook 层)
EeveeSettingsUniversal.x.swift 钩住 Spotify 的设置菜单类 ProfileSettingsSection,在原有列表末尾追加一行 "EeveeSpotify",点击后跳转插件设置页。它通过 orig.numberOfRows() 判断"最后一行是不是我加的",避免与原生行冲突——这种写法保证了跨版本兼容。
2. 设置界面(SwiftUI 层)
EeveeSettingsView.swift 是 SwiftUI 主界面,分为四个彩色入口:
| 入口 | 页面 | 对应功能 |
|---|---|---|
| 🔧 patching | EeveePatchingSettingsView | 选择 Premium 补丁模式 |
| 💬 lyrics | EeveeLyricsSettingsView | 选择歌词来源、配置 token |
| 🎨 customization | EeveeUISettingsView | 界面外观自定义 |
| ✨ experiments | EeveeExperimentsSettingsView | 实验性功能开关 |
所有选项通过 UserDefaults 的扩展(如 LyricsOptions+UserDefaults.swift)持久化,入口在 Tweak.x.swift 启动时读取——Settings 写配置,Tweak 入口读配置,形成闭环。
六、三大模块如何协作?
整体协作关系可以用一句话概括:入口路由、配置驱动、模块解耦。
用户操作 Settings 模块 (SwiftUI)
│ 写入 UserDefaults
▼
Tweak.x.swift 启动时读取配置
│ 按 hookTarget 版本路由
├──────► Premium 组 (patchType 启用时激活)
├──────► Lyrics 组 (lyricsSource 启用时激活)
└──────► Settings 注入组 (始终激活)
SessionProtection (始终激活):拦截登出/令牌过期,保证"伪装"不掉线
- SessionProtection(SessionProtection.x.swift)是所有版本都会激活的"守门员",它钩住
logout()等方法并拦截 Ably WebSocket 的撤销事件,防止 Spotify 发现账号并非真正 Premium 后强制登出——这是 Premium 模块能长期生效的底线保障; - 每个模块内部按 HookGroup 再细分为 Base / Legacy / Modern / V91 等子组,针对具体版本做增量激活(见 Tweak.x.swift 的
activatePremiumPatchingGroup()); - 公共能力(日志、弹窗、Bundle 读取、URLSession 封装)统一收敛在 Shared/Helpers/,三个模块共享复用。
七、架构亮点小结
- 版本路由机制:用枚举
VersionHookTarget+ 条件激活 HookGroup,优雅化解"多版本 Spotify 兼容"这一最大难题; - Repository 策略模式:歌词源可插拔,新增一个来源只需实现一个协议;
- SwiftUI + Hook 双层设置:原生体验的界面与底层钩子解耦;
- 文件组织清晰:每个功能一个文件、每个来源一个目录,配合扩展文件(
+xxx.x.swift)拆分单一职责,非常适合作为 Theos/Orion tweak 项目的架构参考。
如果你想动手修改,建议从 Tweak.x.swift 入手理解装配流程,再按本文的三大模块路径逐个深入。构建方面可参考根目录的 Makefile 与 README.md 中的编译说明。

