MoviePilot-TV
基于 Swift 和 SwiftUI 开发的 MoviePilot Apple TV 原生客户端。为大屏幕和 Siri Remote 遥控器交互而设计。
界面预览
核心特性
专为大屏幕和家庭观影设计，提供从浏览、搜索到订阅的完整闭环体验。
- 为家庭设计: 聚焦核心观影功能，摒弃复杂的管理员后台设置，交互简洁，适合所有家庭成员。
- 原生沉浸体验: 基于 Swift & SwiftUI 原生开发，遵循 tvOS 设计规范，提供流畅的动效和沉浸式详情页。
- Siri Remote 完整支持: 所有功能均可通过 Siri Remote 直观操作，支持长按海报进行订阅、搜索等快捷操作。
- 聚合搜索: 一键搜索电影、电视剧、合集及演职人员。
- 高效订阅: 优化订阅流程，在订阅时直接完成配置，一步到位。
- 无缝浏览: 通过详情页预加载和持久化登录，消除等待，实现无缝切换和快速访问。
⚠️ 兼容性与已知问题
- tvOS 版本: 支持 tvOS 18.0+。本项目主要在 tvOS 26.0+ 环境下开发，建议使用最新的 tvOS 系统获得最佳体验。
- MoviePilot 版本: 当前测试兼容的后端版本为
v3.0.4，媒体业务按 MoviePilot Webv3.0.4对齐。低于该版本不在兼容范围；App 启动时会提示版本过低风险。 - 兼容原则: TV 端以 MoviePilot Web 前端和 MoviePilot 后端当前行为为准；如果 Web 本来也不显示，或后端/第三方数据源同样异常，本项目通常不会在 TV 端额外兜底修复。
- 更新节奏: 本应用更新频率可能低于 MoviePilot 原版，不保证长期兼容旧版 API 或旧版后端已知问题。
- 账号登录: 不支持已开启双因素认证 (MFA/2FA) 的账号，请在关闭双因素认证后再登录。
- 密码安全: 请勿将 MoviePilot 密码与其他服务的密码设为相同值。Apple 钥匙串不可用时，本 App 会自动降级为明文持久化密码；即使 Apple TV 环境相对封闭，仍存在密码泄露风险。
安装指南
方式一：下载 IPA 并自签侧载
前往项目的 Releases，下载最新版本中的：
MoviePilot-TV-unsigned.ipa该文件为未签名 IPA，不能直接安装，需要使用自己的 Apple 账号或证书重新签名后侧载到 Apple TV。
可使用支持 tvOS 应用签名和侧载的工具进行安装，例如：
- ATVloadly
- 其他支持 tvOS IPA 重签名及侧载的工具
方式二：社区 TestFlight 苹果测试渠道
社区用户 EricCartman9969 提供了个人 TestFlight，可通过以下链接加入：
https://testflight.apple.com/join/UK3qEnVU
[!WARNING]
该 TestFlight 由社区用户自行维护，并非本项目官方发布渠道。
> 不保证长期更新、持续可用或与最新源码版本保持一致；测试名额、构建有效期及后续维护均由提供者决定。
方式三：通过 Xcode 源码构建
准备工作
- macOS 26.0+
- Xcode 26.0+
构建步骤
- 克隆项目代码：
git clone --filter=blob:none https://github.com/CHANTXU64/MoviePilot-TV.git
# 切到最新 tag (例如 v0.3.8)
git checkout tags/v0.3.8
- 使用 Xcode 打开
MoviePilot-TV.xcodeproj。 - 选择你的真实 Apple TV 设备（需在同一局域网并已配对）。
- 在 Signing & Capabilities 中选择你的开发者账号，修改
Bundle Identifier为一个唯一的名称（例如com.yourname.MoviePilot-TV）。 - 点击 Run (或
Cmd + R) 编译并安装。 - 自动续签 (可选): 免费账号签名的应用有效期通常为 7 天，可使用 Sideloadly 或项目内的
scripts/apple-tv-renew.sh续签：
BUNDLE_ID="com.yourname.MoviePilotTV" bash scripts/apple-tv-renew.sh
BUNDLE_ID="com.yourname.MoviePilotTV" bash scripts/apple-tv-renew.sh --force注意： 脚本默认只检查本机 DerivedData 中构建产物的 embedded.mobileprovision，不会确认 Apple TV 设备端是否仍安装成功；如果本机构建产物里的签名配置仍未过期，脚本会直接跳过。--force 会忽略这个本地未过期检查，直接重新构建并安装到已配对的 Apple TV，适合放进 crontab 定时保活或怀疑设备端安装状态异常时使用。
--force 只强制执行构建和安装流程，不代表 Xcode/Apple 一定会在旧的 Xcode-managed provisioning profile 过期前签发新的 profile；如果 Apple 仍复用未过期的 profile，应用的实际到期时间不会被提前延长。
开发与测试
后端兼容性测试
如需使用自己的 MoviePilot 后端验证 TV 端接口、图片和功能兼容性，请先阅读 后端兼容性测试文档。真实后端测试可能包含副作用套件，运行前请确认测试范围。
UI 预览测试分支
UI 预览测试请切到 ai/ui-preview-mode 分支，该分支不计划合并到 main。Debug 构建运行时添加启动参数 -uiPreviewMode。
反馈与贡献
- 提交 Bug：请务必提供 MoviePilot 版本号、相关截图和复现步骤。
- 功能建议：本项目专注提供基础的客厅浏览和订阅体验，过于复杂的后端配置管理等需求暂不考虑。
- 贡献代码：代码采用纯 Swift 编写。提交 PR 前请确保在真实 Apple TV 上测试过。
协议声明
本项目原创代码基于 CC0 1.0 Universal 协议发布（公有领域）。可自由复制、修改、发布和商业使用。
鸣谢
界面及交互设计参考了 MoviePilot-Frontend 与 Apple TV 官方应用，对相关开发者表示感谢。原项目的相关参考代码和逻辑遵循原作者的 MIT License。