用途:在 iOS 应用中使用 MusicKit 接入 Apple Music 目录、播放歌曲、查询个人云端资料库,并向非订阅用户展示订阅引导。资料标注目标环境为 Swift 6.3 / iOS 26+。
主要能力:请求用户音乐授权;通过 MusicSubscription.current 校验订阅能力(canPlayCatalogContent、canBecomeSubscriber、hasCloudLibraryEnabled);用 MusicCatalogSearchRequest 搜索歌曲、专辑和艺人并限制返回数量;用 MusicCatalogChartsRequest 获取排行榜;用播放器播放曲目;用原生订阅表单做订阅引导。
必要用法:先在 Info.plist 添加 NSAppleMusicUsageDescription;调用 MusicAuthorization.request() 获取授权;播放目录完整曲目前确认订阅的 canPlayCatalogContent 为真;应用内播放使用 ApplicationMusicPlayer.shared,系统级播放使用 SystemMusicPlayer;通过 .musicSubscriptionOffer(isPresented:) 展示订阅表单;对 player.play() 做错误处理。
适用场景:需要在应用内搜索并播放 Apple Music 内容、接入用户个人音乐库、展示排行榜,或引导用户订阅 Apple Music 的 iOS 应用。
限制与注意事项:未添加 NSAppleMusicUsageDescription 会在请求授权时崩溃;未校验订阅可能只播放试听或失败;SystemMusicPlayer 会替换用户 Music 应用的播放队列,应用内播放应选 ApplicationMusicPlayer;播放可能因家长限制、离线或 DRM 失败;不要硬编码商店地区 ID,MusicKit 会依据账户设置推断。更完整的自定义播放列表、Now Playing 元数据和音频引擎整合模式见 references/musickit-patterns.md。