MusicKit 是一份面向 iOS 开发的技能文档，介绍如何使用 Apple 的 MusicKit 与 MediaPlayer 框架，在应用中集成 Apple Music 播放、目录搜索和正在播放（Now Playing）元数据。目标平台为 Swift 6.3 / iOS 26+。
用途 该文档用于指导开发者在 iOS 应用中添加 Apple Music 相关功能，包括搜索 Apple Music 目录、管理播放、检查订阅状态，以及通过 MPNowPlayingInfoCenter 和 MPRemoteCommandCenter 发布正在播放元数据。
主要能力
- 授权：通过 MusicAuthorization.request() 请求访问用户音乐数据的权限，每次安装仅提示一次；也可用 MusicAuthorization.currentStatus 检查当前状态而不触发提示。
- 目录搜索：使用 MusicCatalogSearchRequest 搜索 Apple Music 目录，可设置 limit，返回 MusicItemCollection<Song>，并可读取歌曲标题、艺术家和封面图 URL。完整目录访问需要用户拥有 Apple Music 订阅。
- 订阅检查：通过 MusicSubscription.current 判断 canPlayCatalogContent，并可用 MusicSubscription.subscriptionUpdates 观察订阅变化；未订阅时可展示 Apple Music 订阅 offer 表单（musicSubscriptionOffer）。
- 播放：使用 ApplicationMusicPlayer.shared 播放 Apple Music 内容，独立于系统 Music 应用，不影响系统播放器状态；支持播放、暂停、跳到下一项，并可通过 player.state 观察播放状态。
- 队列管理：通过 ApplicationMusicPlayer.Queue 初始化队列、向队尾追加歌曲、在当前项之后插入歌曲。
- Now Playing 信息：更新 MPNowPlayingInfoCenter，使锁屏、控制中心和 CarPlay 显示当前曲目元数据；对自定义音频（非 MusicKit 来源）尤其必要，ApplicationMusicPlayer 对 Apple Music 内容会自动处理。可设置标题、艺术家、时长、已播放时间、播放速率、媒体类型和封面图。
- 远程命令中心：通过 MPRemoteCommandCenter 注册播放、暂停、下一首、上一首等处理程序，响应锁屏控件、AirPods 手势和 CarPlay 按钮；可禁用不支持的命令，并支持拖动进度（changePlaybackPositionCommand）。
使用方式 文档以代码示例形式给出各功能的实现方式，包括项目配置步骤（在 Xcode 中启用 MusicKit 能力以添加 com.apple.developer.musickit 权限、在 Info.plist 添加 NSAppleMusicUsageDescription、如需后台播放则添加音频后台模式）、导入 MusicKit 与 MediaPlayer、以及各 API 的调用示例。
适用场景 适用于需要在 iOS 应用中集成 Apple Music 搜索、播放、订阅引导、锁屏与 CarPlay 控制、以及自定义音频正在播放信息展示的开发场景。
限制与注意事项 文档列出常见错误：未配置 MusicKit 权限或用途说明会导致授权崩溃或被 App Review 拒绝；播放目录内容前未检查订阅会静默失败或抛错；应使用 ApplicationMusicPlayer 而非 SystemMusicPlayer（后者会修改用户 Music 应用的全局队列）；曲目变化时需更新 Now Playing 信息；注册远程命令后应返回 .success，不支持的命令应禁用而非返回 .commandFailed。文档还提供审查清单，涵盖权限、用途说明、授权、订阅检查、播放器选择、后台音频、Now Playing 更新、远程命令处理、封面图、已播放时间更新和订阅 offer 展示等检查项。
参考资料 文档提及扩展模式（SwiftUI 集成、流派浏览、播放列表管理）位于 references/musickit-patterns.md，并列出 MusicKit 框架、MusicAuthorization、ApplicationMusicPlayer、MusicCatalogSearchRequest、MusicSubscription、MPRemoteCommandCenter、MPNowPlayingInfoCenter、NSAppleMusicUsageDescription 等参考项。