EeveeSpotify 项目架构剖析:如何伪装成 Premium?三大核心模块划分与协作机制

原创2026-10-31 22:53:381,973 阅读

EeveeSpotify 项目架构剖析:如何伪装成 Premium?三大核心模块划分与协作机制

EeveeSpotify 是一款面向 iOS 的 Spotify 增强 tweak(插件),通过拦截并实时修改 App 的网络请求,让 Spotify 认为你拥有 Premium 订阅,实现免费无广告收听,同时支持 Musixmatch、Genius 等多个来源的自定义歌词。本文带你剖析它的 Premium(高级版权限伪造)、Lyrics(歌词替换)、Settings(设置界面)三大核心模块是如何划分与协作的,即使你是新手也能看懂整体架构。

一、先看图:EeveeSpotify 最终效果

下图是它伪造的 "Your Premium" 页面——订阅计划被改名为 Eevee,并列出无广告收听、任意顺序播放等权益:

EeveeSpotify 伪造的 Premium 订阅页面展示

这个漂亮的"假订阅页",正是 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,它做三件事:

  1. 识别 Spotify 版本:读取 CFBundleShortVersionString,映射到 VersionHookTarget(如 .lastAvailableiOS14、.v91、.latest)。因为不同版本 Spotify 的内部类名不同,钩子必须"对症下药";
  2. 按用户配置启用模块:检查 UserDefaults 中的 patchType、lyricsSource 等选项,决定激活哪些 Hook 组;
  3. 激活各功能组:基于 Orion 框架的 HookGroup 机制,同类钩子被归入同一个 Group(如 BasePremiumPatchingGroup、BaseLyricsGroup),统一激活,代码组织非常清晰。

这种"入口路由 + 版本分组 + 配置驱动"的设计,是它能稳定支持多个 Spotify 版本的关键。

EeveeSpotify 修改的 premium.bnk 远程配置二进制文件十六进制视图

上图展示了项目内置的 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)模式设计:

  1. 统一协议:LyricsRepository.swift 定义了一个方法 getLyrics(_:options:),所有歌词源都必须实现它;
  2. 四个可插拔实现:分别位于 Repositories/ 目录下的 GeniusLyricsRepository、LrclibLyricsRepository、MusixmatchLyricsRepository、PetitLyricsRepository,每个源的数据模型独立存放在 Models/ 对应子目录(如 Genius/、Lrclib/);
  3. 来源枚举驱动:LyricsSource.swift 定义了 genius / lrclib / musixmatch / petit / notReplaced 五个选项,当前构建默认启用 Musixmatch;
  4. 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/,三个模块共享复用。

七、架构亮点小结

  1. 版本路由机制:用枚举 VersionHookTarget + 条件激活 HookGroup,优雅化解"多版本 Spotify 兼容"这一最大难题;
  2. Repository 策略模式:歌词源可插拔,新增一个来源只需实现一个协议;
  3. SwiftUI + Hook 双层设置:原生体验的界面与底层钩子解耦;
  4. 文件组织清晰:每个功能一个文件、每个来源一个目录,配合扩展文件(+xxx.x.swift)拆分单一职责,非常适合作为 Theos/Orion tweak 项目的架构参考。

如果你想动手修改,建议从 Tweak.x.swift 入手理解装配流程,再按本文的三大模块路径逐个深入。构建方面可参考根目录的 Makefile 与 README.md 中的编译说明。

登录后查看全文
EeveeSpotifyRevivedPublic