从零构建到本地编译:WaifuX 动态壁纸与番剧应用开发上手完整指南
从零构建到本地编译:WaifuX 动态壁纸与番剧应用开发上手完整指南
WaifuX 是一款开源的 macOS ACG 一站式应用,聚合了静态壁纸、动态壁纸与番剧视频播放三大核心功能。本文将从零带你完成开发环境搭建、源码克隆、Xcode 工程生成与本地编译运行,帮助新手开发者快速上手 WaifuX 项目的开发工作。
📥 第一步:克隆 WaifuX 源码仓库
在开始之前,请确认你的 Mac 满足以下基本条件:
- macOS 14.0+(Sonoma 及以上版本)
- 已安装 Xcode 16 或更高版本(Apple 芯片与 Intel 芯片均可)
确认环境后,打开终端,执行以下命令克隆仓库:
git clone https://gitcode.com/gh_mirrors/wa/WaifuX
cd WaifuX
克隆完成后,你会得到一份完整的 WaifuX 源码,包括主程序、动态壁纸扩展、屏保组件以及 Steam 服务等多个模块。
🧭 第二步:快速认识项目目录结构
WaifuX 采用职责清晰的目录划分,刚接触源码时先建立整体认知非常重要。下面是几个你最常打交道的目录:
| 目录 / 文件 | 作用 | 入门建议 |
|---|---|---|
| App/ | 应用入口,包含 WaifuXApp.swift 与 Info.plist | 从这里开始看应用启动流程 |
| Views/ | SwiftUI 界面层,如 ContentView.swift | 找 UI 相关代码先看这里 |
| ViewModels/ | 视图模型层,负责界面与数据的桥梁 | 理解状态管理逻辑 |
| Services/ | 核心业务逻辑:壁纸下载、动态壁纸、云同步等 | 功能最多的目录 |
| Models/ | 数据模型定义 | 配合 Rules 一起看 |
| WaifuXWallpaperExtension/ | 动态壁纸桌面扩展(.appex) | 动态壁纸渲染的关键 |
| WaifuXScreenSaver/ | 屏保组件(.saver) | 了解多目标构建 |
| Tests/ 与 WallHavenTests/ | 回归测试与单元测试 | 改动功能后跑一遍测试 |
| Scripts/ | 打包、版本号同步等构建脚本 | 发布构建时用到 |
项目使用 XcodeGen 管理工程配置:所有 target、依赖、签名等设置都集中在 project.yml 这一个文件中,Xcode 工程文件由它自动生成。这意味着你不需要手动打开 Xcode 拖文件,改配置只改 YAML 即可,非常清爽。
🛠️ 第三步:生成 Xcode 工程并首次运行
这是新手最容易卡住的一步,跟着下面三步走即可:
1. 安装 XcodeGen
仓库不直接包含 .xcodeproj 文件,需要先安装 XcodeGen 生成工程:
brew install xcodegen
2. 生成工程文件
cd WaifuX
xcodegen generate
生成后会得到 WaifuX.xcodeproj,其中包含三个构建目标:主程序 WaifuX、壁纸扩展 WaifuXWallpaperExtension、屏保 WaifuXScreenSaver(见 project.yml 中的 targets 配置)。
3. 打开并运行
用 Xcode 打开 WaifuX.xcodeproj,按 Cmd + R 即可编译运行。仓库已把共享 Scheme 纳入配置,换机或重装后也能直接运行。
💡 小贴士:首次打开可能遇到签名警告,把
DEVELOPMENT_TEAM改为你自己的 Apple ID 团队即可本地跑通。
首次启动后,你可以在设置页中了解各项功能开关与个性化配置:
🧩 第四步:理解数据源规则引擎(Rule 系统)
WaifuX 的番剧多源解析能力来自一套 数据源规则引擎——用 JSON 描述网站结构,配合 XPath 选择器抓取内容,无需为每个站点写代码。
规则文件放在 AnimeRules/ 目录,示例可以参考 Rules/gimy-example.json,核心字段包括:
baseURL:数据源地址xpath.search:搜索页的列表、标题、封面选择器xpath.detail:详情页的标题、简介、选集选择器headers:请求头配置
规则加载逻辑在 Rules/RuleLoader.swift 与 Rules/DataSourceRule.swift 中实现。如果你想为新番剧站点贡献解析规则,从看懂这份示例 JSON 开始,是最快的入门路径。
🧪 第五步:本地运行测试
项目内置了回归测试与单元测试,改动代码后建议跑一遍,避免破坏已有功能:
- WallHavenTests/CropLayoutEngineTests.swift:壁纸裁剪布局引擎测试
- Tests/LockScreenHardeningRegression.swift 等:锁屏、多显示器等场景回归测试
在 Xcode 中选中 WaifuX Scheme,按 Cmd + U 即可运行全部测试。绿色的对勾就是本地编译环境完全健康的标志。
📦 第六步:打包生成可分发的安装包
当本地运行稳定后,可以体验一次完整的发布构建流程。项目提供了 scripts/package.sh 一键打包脚本:
./scripts/package.sh
脚本会自动完成工程归档(Archive)、dylib 路径修复、内部二进制签名,最终产出 .dmg 安装包。支持通过环境变量指定架构:
WAIFUX_ARCH=x86_64 ./scripts/package.sh
另外,版本号统一管理在 VERSION 文件中,修改后执行以下命令同步到工程配置(见 scripts/sync-version.sh):
bash scripts/sync-version.sh && xcodegen generate
🤝 第七步:参与 WaifuX 开源贡献
熟悉本地开发流程后,你就可以正式参与贡献了。项目贡献规范写在 CONTRIBUTING.md 中,简要流程如下:
- Fork 仓库并从
main分支创建功能分支 - 按现有代码风格提交改动,附上必要测试
- 提交 Pull Request,等待维护者审核
贡献方向推荐(由浅入深):
- 🏷️ 番剧解析规则:为 AnimeRules/ 新增 JSON 规则,门槛最低
- 🐛 Bug 修复:附重现步骤与系统版本,优先修复体验类问题
- ✨ 功能增强:在 Services/ 与 ViewModels/ 中扩展功能
此外,SteamService/ 目录还包含一个独立的 .NET Steam 认证服务(用于 Workshop 内容下载),对 C# 方向的贡献者也友好。
✅ 常见问题速查
| 问题 | 解决方案 |
|---|---|
| 打开工程没有可用 Scheme | 重新执行 xcodegen generate |
| 编译报签名错误 | 修改 Signing Team 为自己的开发者账号 |
| 首次打开 App 被系统拦截 | 系统设置 → 隐私与安全性 中允许运行 |
| 内容加载不出来 | 主数据源在海外,检查网络环境 |
| 想改本地版本号 | 编辑 VERSION 后运行 bash scripts/sync-version.sh && xcodegen generate |
🎯 总结
回顾一下这条从零到本地编译的完整路径:
- 克隆:
git clone获取 WaifuX 源码 - 生成:
brew install xcodegen+xcodegen generate产出工程 - 运行:Xcode 打开后 Cmd + R 首次启动
- 理解:熟悉 project.yml、规则引擎与目录结构
- 测试:Cmd + U 跑回归测试
- 打包:
./scripts/package.sh生成安装包
整个过程不需要任何付费工具,一台 Mac 加 Xcode 就能完整跑通。祝你在 WaifuX 开源项目中玩得开心,写出自己的第一个 Pull Request!




