月明星稀

Swift：iOS 控制中心媒体播放状态与软件内不同步的解决办法和排查思路

Sun, 10 May 2026 13:07:00 GMT

iOS 控制中心媒体播放状态与软件内不同步的解决办法&排查思路：AVAudioEngine 暂停只关 playerNode 的坑#

最近在使用Swift原生开发重构一个 iOS 本地全格式音乐播放器，碰到了一个迷惑人的问题：

在 App 内点暂停，音频确实停了；
控制中心 / 通知中心 / 锁屏 / 灵动岛里的进度条也停了；
但播放/暂停按钮的图标还一直显示 playing，点它系统才想起来该切成暂停。

最迷惑的是：日志那一侧完全正确。MPNowPlayingInfoCenter.playbackState = .paused 写了，MPNowPlayingInfoPropertyPlaybackRate = 0 也写了，重复写了好几遍，系统就是不更新按钮。

这篇记录一下三轮修复、最终定位到的真正根因，以及为什么前两轮看起来很对的修改没有解决问题。

先说最终结论#

如果你用 AVAudioEngine + AVAudioPlayerNode（不是 AVPlayer）做播放，又遇到「Control Center 进度停了但按钮不变」这种错位，大概率不是你 MPNowPlayingInfoCenter 那一套写错了——是 你暂停的时候只 playerNode.pause()，AVAudioEngine 本身还在 running。

iOS 系统 Now Playing 界面的播放/暂停按钮图标，不只是看你写给 playbackState 的值，还看你的 app 当前是不是还在向音频图实际输出音频。playerNode.pause() 会让声音停下，但整个 engine 从系统看依然是”活跃的音频生产者”。于是：

rate = 0 会被系统认（所以进度条停）；
playbackState = .paused 不会立刻反映到按钮图标上（因为它跟当前音频输出活跃度冲突）。

真正的修复只有一行：暂停时同时 engine.pause()，恢复时 engine.start()。

但我走了好几步才到这里，中间还尝试了一些”听起来很对”但并没有解决问题的改动。完整记一下。

1. 现象和复现条件#

平台：iOS（真机26、iOS 17/18 均复现）
UIBackgroundModes: audio 已配，UIApplication.shared.beginReceivingRemoteControlEvents() 也调了
MPRemoteCommandCenter 里 play / pause / togglePlayPause / nextTrack / previousTrack / changePlaybackPosition 都有 target
MPNowPlayingInfoCenter 正常写：title / artist / duration / elapsed / rate / playbackState

复现：播一首歌，在 App 内点暂停，然后锁屏或下拉控制中心。

结果：进度条在暂停那一秒就停住了，但播放按钮图标依然是”playing 时显示的暂停图标”（也就是那个让你点了能暂停的图标），不会切成”paused 时显示的播放图标”。再点一次按钮，系统会正确分发 play 命令，说明系统是认你这个 Now Playing owner 的，只是 UI 没同步。

2. 第一轮：怀疑 nowPlayingInfo / playbackState 的写入顺序#

第一反应是一个广为流传的老规律：先写 nowPlayingInfo，再写 playbackState，反过来写系统有时会把 playbackState 的修改吃掉。

原来的代码确实是反的：

1
// 旧
2
nowPlayingCenter.playbackState = state.isPlaying ? .playing : .paused
3
nowPlayingCenter.nowPlayingInfo = info

改成：

1
// 新
2
nowPlayingCenter.nowPlayingInfo = info
3
nowPlayingCenter.playbackState = state.isPlaying ? .playing : .paused

这个修改是对的，但并没有解决我的问题。装上去症状完全一致。

3. 第二轮：怀疑 playCommand / pauseCommand 的可用性开关#

继续查资料，看到另一个说法：如果你根据播放状态去动态切 playCommand.isEnabled / pauseCommand.isEnabled，iOS 在这一瞬间会和 Control Center UI 的刷新抢时序，按钮图标可能卡在旧状态。

我原本的代码正是这么写的：

1
// 旧
2
private func updateCommandAvailability(hasItem: Bool, isPlaying: Bool) {
3
    commandCenter.playCommand.isEnabled = hasItem && !isPlaying
4
    commandCenter.pauseCommand.isEnabled = hasItem && isPlaying
5
    commandCenter.togglePlayPauseCommand.isEnabled = hasItem
6
    commandCenter.changePlaybackPositionCommand.isEnabled = hasItem
7
}

改成只要有曲目就全都 enable，图标完全交给 playbackState + rate 去决定：

1
// 新
2
private func updateCommandAvailability(hasItem: Bool) {
3
    commandCenter.playCommand.isEnabled = hasItem
4
    commandCenter.pauseCommand.isEnabled = hasItem
5
    commandCenter.togglePlayPauseCommand.isEnabled = hasItem
6
    commandCenter.changePlaybackPositionCommand.isEnabled = hasItem
7
}

这也是 Apple 示例代码的推荐方式——两个命令都注册了 handler，iOS 会根据 playbackState 自己去挑合适的图标，不需要你把 enabled 来回切。

这个修改也是对的，但装上去还是一样。进度条停、按钮不变。

至此我两次修改都”理论上对”但问题没变化。这种时候必须停下来，先证明链路到底哪一步出了问题，而不是继续往相邻的地方打补丁。

4. 第三轮：先证明，再改#

加全链路日志，把”用户操作 → coordinator 状态 → 写给系统的值”每一步都打出来：

1
// PlaybackCoordinator
2
public func togglePlayback() {
3
    PlaybackLogger.coordinator.log("togglePlayback: called, isPlaying=\(self.state.isPlaying)")
4
    // ...
5
}
6

7
public func pauseCurrent() {
8
    PlaybackLogger.coordinator.log("pauseCurrent: called, hasItem=\(self.state.currentItem != nil) isPlaying=\(self.state.isPlaying)")
9
    // ...
10
}
11

12
private func setPaused(_ paused: Bool) async {
13
    PlaybackLogger.coordinator.log("setPaused: request paused=\(paused) currentIsPlaying=\(self.state.isPlaying)")
14
    await activeEngine.setPaused(paused)
15
    state.isPlaying = !paused
16
    PlaybackLogger.coordinator.log("setPaused: engine done, state.isPlaying=\(self.state.isPlaying)")
17
    // ...
18
    syncRemoteMetadata()
19
}
20

21
private func syncRemoteMetadata() {
22
    PlaybackLogger.coordinator.log("syncRemoteMetadata: isPlaying=\(self.state.isPlaying) elapsed=\(self.state.currentTime) duration=\(self.state.totalDuration)")
23
    remoteBridge.update(state: state)
24
}

展开收起

1
// SystemRemoteTransportBridge
2
func update(state: NowPlayingState) {
3
    // ... 写 info、写 playbackState ...
4
    PlaybackLogger.remote.log("bridge.update: title=\(item.title, privacy: .public) isPlaying=\(state.isPlaying) rate=\(state.isPlaying ? 1.0 : 0.0) elapsed=\(state.currentTime) duration=\(state.totalDuration) playbackState=\(state.isPlaying ? "playing" : "paused", privacy: .public)")
5
}

然后在真机上暂停一次，截了一段日志（精简）：

1
togglePlayback: called, isPlaying=true
2
setPaused: request paused=true currentIsPlaying=true
3
setPaused: engine done, state.isPlaying=false
4
syncRemoteMetadata: isPlaying=false elapsed=5.65 duration=312.99
5
bridge.update: title=不将就 isPlaying=false rate=0.0 elapsed=5.65 duration=312.99 playbackState=paused

之后没有任何 stray 的 isPlaying=true 再把状态写回去。也就是说：

我们写给系统的值是 100% 正确的；
系统也确实”部分收到了”——因为进度条对得上、rate=0 也生效了（进度不再往前走）；
但按钮图标就是卡在 playing。

到这里排除了”写入顺序”、“命令可用性”、“被别的链路覆盖”这几种可能。既然写是对的，那只能是系统对这个 App 有额外的判定条件，在那个条件上我们写的值被忽略了。

5. 定位到关键点：AVAudioEngine 还在 running#

回到播放内核那边看 setPaused：

1
// 旧（*PlaybackEngine / NativeAudioEngine 二者都一样）
2
public func setPaused(_ paused: Bool) async {
3
    if paused {
4
        playerNode.pause()
5
    } else {
6
        try? Self.activatePlaybackSessionIfAvailable()
7
        if !engine.isRunning {
8
            try? engine.start()
9
        }
10
        playerNode.play()
11
    }
12
}

注意：暂停只调了 playerNode.pause()，engine 从没 pause() 过。AVAudioEngine 是整个音频图的宿主，player node 只是挂在它上面的一个节点。player node 暂停了意味着”我这个节点不再往 mainMixerNode 送 buffer”，但 engine 依然在跑 IO、依然从系统的角度看是一个活跃的 realtime audio producer。

iOS 的 Now Playing UI 在决定”到底该显示 play 还是 pause 图标”的时候，会结合两个信号：

MPNowPlayingInfoCenter.playbackState / nowPlayingInfo[playbackRate]（我们写的）
当前音频会话 owner 的实际音频活动（AVAudioEngine 是不是在往系统送 buffer）

这两个信号冲突时，系统会偏向第二个——因为它不信任 app 可能乱写的 metadata，它信任自己底层 I/O 图看到的现实。于是就出现了「metadata 说 paused（进度条停），但你 engine 还在 run（按钮还 playing）」这种撕裂。

AVPlayer 路径不会有这个问题，因为 AVPlayer.pause() 会同时把播放和底层队列都停下来。只有 AVAudioEngine + AVAudioPlayerNode 这种自己管音频图的路径需要显式地 pause engine。

6. 修复：暂停时同步 pause 整个 engine#

改动非常小：

1
// 新
2
public func setPaused(_ paused: Bool) async {
3
    if paused {
4
        playerNode.pause()
5
        engine.pause()                // ← 关键这一行
6
    } else {
7
        try? Self.activatePlaybackSessionIfAvailable()
8
        if !engine.isRunning {
9
            try? engine.start()       // 恢复时重启 engine
10
        }
11
        playerNode.play()
12
    }
13
}

NativeAudioEngine 和 *PlaybackEngine 同样改一次。恢复路径本来就有 engine.start() 的 fallback，所以不用再改。

这一行加上去，控制中心/通知中心/锁屏/灵动岛的按钮图标立刻跟着暂停状态同步了。

7. 三轮修改的价值分布#

最终生效的是第三轮（engine.pause()）。但前两轮修改我没有回滚，因为它们本身就是更正确的写法：

nowPlayingInfo 先写、playbackState 后写：Apple 官方 sample 和论坛里的多年共识。反着写虽然大多数时候也能跑，但会在某些边界条件下掉状态。这个改动没副作用，留着。
playCommand / pauseCommand 始终 enable：Apple 推荐做法。动态切 enabled 是一种反模式，容易和系统 UI 的刷新抢时序。这个改动也没副作用，留着。
engine.pause() 在 pause 时同步停图：本 Bug 的真正修复点。

加起来就是一套比较干净、可预期的 Now Playing 同步实现。

8. 经验总结#

这次排查里让我印象深的几点：

1）日志先行，别在相邻的地方打补丁

前两轮改的东西都”理论上对”，但因为没有先证明链路哪里出了问题，我其实一直在改”不是根因”的地方。第三次上来老老实实把每一步 togglePlayback → setPaused → state.isPlaying → syncRemoteMetadata → bridge.update 打出来，日志完全干净了，才能非常确定地排除”我们写得不对”这条路，把方向转到系统侧。

2）iOS 的 Now Playing 界面不是一个纯 metadata 驱动的 UI

很容易把 MPNowPlayingInfoCenter 当成一个 key-value 字典：“我设什么系统就显什么”。真实情况是系统还会交叉验证你的实际音频行为——尤其是 AVAudioEngine 路径下。metadata 和 engine 状态必须配套。

3）AVAudioEngine 的 pause 有两层

playerNode.pause() 只是节点级别的。engine.pause() 才是图级别的。如果你的 App 会把 Now Playing 让给系统（锁屏、控制中心、灵动岛、CarPlay、AirPods 耳机控制…），这两层都要一起切。

4）症状要细读

「进度停了但按钮不变」这种错位，和「按钮变了但进度还在走」是完全不同的两类问题。前者是 metadata 生效了但 UI 主信号没生效，后者是 metadata 没生效但 UI 被其他途径刷了。分清楚之后，排查方向会完全不同。

附：最终 diff（节选）#

*/*PlaybackEngine.swift：

1
public func setPaused(_ paused: Bool) async {
2
    isPaused = paused
3
    if paused {
4
        playerNode.pause()
5
        engine.pause()
6
    } else {
7
        try? Self.activatePlaybackSessionIfAvailable()
8
        if !engine.isRunning {
9
            try? engine.start()
10
        }
11
        playerNode.play()
12
    }
13
}

*/NativeAudioEngine.swift：

1
public func setPaused(_ paused: Bool) async {
2
    if paused {
3
        playerNode.pause()
4
        engine.pause()
5
    } else {
6
        try? Self.activatePlaybackSessionIfAvailable()
7
        if !engine.isRunning {
8
            try? engine.start()
9
        }
10
        playerNode.play()
11
    }
12
}

*/SystemRemoteTransportBridge.swift：

1
nowPlayingCenter.playbackState = state.isPlaying ? .playing : .paused
2
nowPlayingCenter.nowPlayingInfo = info
3
nowPlayingCenter.playbackState = state.isPlaying ? .playing : .paused
4
updateCommandAvailability(hasItem: true, isPlaying: state.isPlaying)
5
updateCommandAvailability(hasItem: true)

1
private func updateCommandAvailability(hasItem: Bool, isPlaying: Bool) {
2
    commandCenter.playCommand.isEnabled = hasItem && !isPlaying
3
    commandCenter.pauseCommand.isEnabled = hasItem && isPlaying
4
private func updateCommandAvailability(hasItem: Bool) {
5
    commandCenter.playCommand.isEnabled = hasItem
6
    commandCenter.pauseCommand.isEnabled = hasItem
7
    commandCenter.togglePlayPauseCommand.isEnabled = hasItem
8
    commandCenter.changePlaybackPositionCommand.isEnabled = hasItem
9
}

最终验证：

App 内暂停 → 控制中心/通知中心/锁屏/灵动岛按钮图标立刻切到”paused”图标，进度条停止；
App 内继续 → 图标立刻切回”playing”图标，进度继续；
控制中心 / 灵动岛 / AirPods 上点暂停 → 同步；
切歌、seek、切内核都不破坏这个行为。

Flutter/iOS 后台自动切歌与通知栏手动“下一首”稳定实现方法

Thu, 23 Apr 2026 14:22:00 GMT

Flutter/iOS 后台自动切歌与通知栏“下一首”稳定实现方法#

前段时间在重构播放器内核时，我顺手把一类最烦的 iOS 播放问题彻底收了一遍：后台自动切歌不稳定、锁屏/通知栏点“下一首”偶发失灵，或者声音切了但元数据还停留在上一首。

这个问题最恶心的地方不在于“完全坏掉”，而在于它经常是 80% 正常，20% 抽风：

前台切歌基本正常；
进后台以后，播完自动下一首偶发不切；
通知栏点下一首，有时能切，有时像没点到；
更诡异的是，有时声音已经切过去了，但歌名、封面、按钮绑定的歌曲还是旧的。

涉及核心文件：

lib/core/services/audio_manager.dart
ios/Runner/AppDelegate.swift
lib/core/services/ios_carplay_service.dart

先说最终结论#

这次修完之后，我对这个问题的总结非常明确：

iOS 后台自动切歌和通知栏“下一首”是否稳定，关键不在于你有没有写 skipToNext()，而在于你有没有把“切歌”当成一个完整的状态机来管理。

真正稳定的实现，至少要满足这几条：

所有切歌入口统一收口：播放器按钮、通知栏、锁屏、CarPlay、自动切歌，最后都走同一条主链路。
在线切歌必须串行化：任意时刻只能有一个活跃切歌任务。
旧异步任务不能回写新状态：要有 token 防串写。
切歌中再次点击不能简单吞掉：要记录“最后一次用户意图”，当前切歌结束后自动 drain。
在线播放列表启动流程也要有独立 token：否则它会和手动切歌抢状态。
iOS 后台缓存切歌不要傻等 play() Future：它可能很晚才 resolve，但音频其实已经播了。
通知栏的 queueIndex 和 mediaItem 不能完全相信播放器内部 index：必须优先使用你自己维护的当前索引。

下面按排查过程慢慢讲。

需注意，本文仅供技术性学习参考，不代表你的软件完全适用，具体问题具体分析，如果遇到问题，欢迎评论区留言交流。 -by Leguan

1. 问题现象：看起来像“偶发失灵”，本质是多条状态链路抢写#

我最早观察到的现象有四类。

1.1 自动切歌偶发不触发#

歌曲在前台播放完时大多能自动切下一首，但一旦切到后台，尤其是在线歌曲，就会出现：

明明还有下一首；
进度已经到结尾；
但就是停在那里不走。

1.2 通知栏/锁屏点下一首偶发没反应#

这个现象在“当前歌曲刚切完、或者正处于切歌中”时更明显：

点一次 next，没反应；
再点一次，又突然跳到后一首；
有时还会出现“第二次操作覆盖第一次”的错觉。

1.3 声音切过去了，但元数据还是旧的#

这是最迷惑人的一种。

用户主观体验是：

耳朵听到已经是下一首；
但锁屏显示还是上一首；
播放页里某些区域也还没更新；
有时暂停一下，信息又“自己好了”。

这类问题最容易让人误以为是 UI 层刷新 bug。

1.4 日志多数正确，但体验依然错#

更坑的是，很多日志看起来都很健康：

targetIndex 是对的；
setAudioSource 是成功的；
play() 也发起了；
SWITCH success 也打出来了。

但用户体验仍然不稳定。

这通常意味着：你看到的不是“某一步完全失败”，而是多个异步流程竞争状态，最后谁晚回来谁覆盖谁。

2. 第一轮误判：以为只是“切歌函数写得不够严谨”#

最开始我以为这是个很普通的切歌重入问题。

于是第一轮修法很朴素：

加 _isSwitchingOnlineTrack 锁；
切歌中直接忽略新的 next/prev；
给 skipToNext() 加节流。

看起来很合理，但很快发现两个副作用：

用户连续点两下 next，第二下被吞了，体感上就是“按钮不灵”；
下一次计算目标索引时，有时还是基于旧的 _currentIndex，结果方向也会错。

也就是说，只靠一个“正在切歌就 return”的入口锁，最多只是降低混乱，并没有真正解决竞争。

3. 第二轮误判：加了 token，为什么还会被旧状态拉回去？#

随后我把在线切歌链路加上了 switchToken。

这个思路本身是对的：

每次切歌时递增 token；
在 resolve -> setAudioSource -> play -> commit 的各个阶段检查 token；
发现 token 过期就立刻放弃，不允许旧任务再写 _currentIndex / mediaItem / queue。

理论上这已经能挡住大部分“旧 Future 晚回来”的问题。

但实测仍然有一类异常：

手动点 next 之后，音频已经切对了；
几百毫秒后，UI 又被“拉回去”；
日志里会混入 ONLINE_START success 一类晚到消息。

这时候我才意识到：切歌并不是唯一一条会写播放状态的链路。

4. 真正根因：不是一个 race，而是四条链路在竞争#

最后梳理下来，真正互相竞争的其实是四条链路：

手动切歌链路 skipToNext / skipToPrevious -> playAtIndex -> setAudioSource -> play -> commit
自动切歌链路 ProcessingState.completed -> _handlePlaybackCompleted -> skipToNext -> playAtIndex
在线播放列表启动链路 setOnlinePlaylist -> setAudioSource -> play -> commit
系统通知栏状态链路 PlaybackEvent -> PlaybackState(queueIndex/mediaItem/controls) -> iOS Now Playing

只要这四条链路没有被统一收口，就一定会出现下面这些问题：

某条旧链路晚回来回写状态；
当前歌曲索引和系统通知栏索引脱节；
音频已切到下一首，但系统仍显示上一首；
背景场景下 play() Future 很慢，结果元数据提交被拖住。

所以后来我的修法也很明确了：

不再把“自动切歌”“通知栏 next”“播放器按钮 next”当成三个问题，而是统一看成“切歌状态机”的三个入口。

5. 最终方案：把所有入口统一收口到一条主链路#

最终稳定下来的结构很简单：

1
播放器按钮 next / prev
2
锁屏、通知栏 next / prev
3
CarPlay next / prev
4
自动切歌 completed
5
  -> skipToNext() / skipToPrevious()
6
  -> playAtIndex(index)
7
  -> resolve / cache / setAudioSource / play
8
  -> commit currentIndex / mediaItem / queue / playbackState

关键点只有一句话：

自动切歌不要另写一套，通知栏点击也不要另写一套，最后都统一走 playAtIndex(index)。

这样做的好处是：

排查路径简单；
修一次逻辑，所有入口一起受益；
不会出现“前台按钮正常，通知栏异常，自动切歌又是另一套”的维护地狱。

6. 先解决自动切歌：完成事件只负责转发，不直接切 source#

自动切歌这部分，我最后保留得非常克制。

监听 processingStateStream，状态进 completed 后，统一走 _handlePlaybackCompleted()：

1
Future<void> _handlePlaybackCompleted() async {
2
  // Guard against duplicate completion notifications (can happen when
3
  // switching sources quickly) to avoid racing setAudioSource/play calls.
4
  if (_isHandlingCompletion) return;
5
  _isHandlingCompletion = true;
6
  try {
7
    if (_repeatMode == RepeatMode.one) {
8
      await seek(Duration.zero);
9
      await play();
10
    } else {
11
      await skipToNext();
12
    }
13
  } catch (e, st) {
14
    debugPrint('[AudioManager] _handlePlaybackCompleted error: $e');
15
    debugPrint('[AudioManager] _handlePlaybackCompleted stack: $st');
16
  } finally {
17
    _isHandlingCompletion = false;
18
  }
19
}

展开收起

这里的重点不是代码长短，而是职责边界：

_handlePlaybackCompleted() 不直接做 URL 解析；
不直接 set source；
不直接提交新歌曲元数据；
它只负责把“播放完成”这个事件，转成一次标准的 skipToNext()。

这一步非常重要。因为一旦自动切歌另走一套私有逻辑，你后面就一定会出现：

手动 next 修好了；
但自动 next 还是会有旧 bug。

7. 再解决通知栏/锁屏 next：原生只桥接，Flutter 统一处理#

我这边的做法是让原生 iOS 尽量“薄”。

7.1 Swift 侧不写业务逻辑，只桥接命令#

AppDelegate.swift 里基本就是这样：

1
func skipToNext(completion: @escaping (Result<Void, Error>) -> Void) {
2
  invokeVoid("skipToNext", completion: completion)
3
}
4

5
func skipToPrevious(completion: @escaping (Result<Void, Error>) -> Void) {
6
  invokeVoid("skipToPrevious", completion: completion)
7
}

也就是说：

原生层不负责计算该跳到哪一首；
也不负责切 source；
所有核心逻辑仍然收敛到 Flutter 侧。

7.2 Flutter 里的媒体按钮也统一走 skip 方法#

click() 这一层也不做特殊逻辑，直接转发：

1
@override
2
Future<void> click([MediaButton button = MediaButton.media]) async {
3
  _logNotificationDebug('click() requested button=${button.name}');
4
  switch (button) {
5
    case MediaButton.media:
6
      if (_player.playing) {
7
        await pause();
8
      } else {
9
        await play();
10
      }
11
      break;
12
    case MediaButton.next:
13
      await skipToNext();
14
      break;
15
    case MediaButton.previous:
16
      await skipToPrevious();
17
      break;
18
  }
19
  _logNotificationDebug('click() finished button=${button.name}');
20
}

展开收起

这样一来，“播放器里的 next”和“通知栏点 next”就没有分叉了。

8. 真正的核心：在线切歌状态机必须同时解决 3 件事#

在线切歌比本地切歌麻烦很多，因为它天然有异步阶段：

可能命中缓存；
可能要拿预加载 URL；
可能要重新 resolve；
可能还夹着歌词、封面、元数据更新。

所以我最后把在线切歌状态机稳定下来，依赖的是这几个字段：

1
bool _isSwitchingOnlineTrack = false;
2
DateTime? _onlineTrackSwitchStartedAt;
3
int _onlineSwitchToken = 0;
4
int? _pendingOnlineSwitchIndex;
5
int? _queuedOnlineSwitchIndex;

它们分别解决不同问题：

_isSwitchingOnlineTrack：当前是否有切歌任务在跑。
_pendingOnlineSwitchIndex：正在执行的目标 index。
_queuedOnlineSwitchIndex：用户切歌过程中又点了一次，最后想去哪里。
_onlineSwitchToken：旧任务晚回来时，是否还有资格写状态。

8.1 skipToNext：切歌中不忽略，而是入队#

这是最关键的一步之一。

以前很多实现会写成：

1
if (_isSwitching) return;

这会让用户的第二次点击直接消失。

我的做法改成了“按 pending index 计算 + 只保留最后一次用户意图”：

1
@override
2
Future<void> skipToNext() async {
3
  if (_playlist.isEmpty) return;
4
  final now = DateTime.now();
5
  var baseIndex = (_isOnlinePlaylist && _isSwitchingOnlineTrack)
6
      ? (_pendingOnlineSwitchIndex ?? _currentIndex)
7
      : _currentIndex;
8

9
  if (_isOnlinePlaylist && _isSwitchingOnlineTrack) {
10
    final startedAt = _onlineTrackSwitchStartedAt;
11
    final isTimedOut = startedAt != null &&
12
        now.difference(startedAt) > _onlineSwitchLockTimeout;
13
    if (isTimedOut) {
14
      debugPrint('[AudioManager] online switch lock timed out, reset lock');
15
      _isSwitchingOnlineTrack = false;
16
      _onlineTrackSwitchStartedAt = null;
17
      _pendingOnlineSwitchIndex = null;
18
      baseIndex = _currentIndex;
19
    } else {
20
      final queuedIndex = _resolveNextIndex(
21
        baseIndex: baseIndex,
22
        reshuffleOnWrap: true,
23
      );
24
      if (queuedIndex < 0) return;
25
      debugPrint(
26
          '[AudioManager][CMD] skipToNext currentIndex=$_currentIndex baseIndex=$baseIndex pending=$_pendingOnlineSwitchIndex queued=$_queuedOnlineSwitchIndex playerIndex=${_player.currentIndex} pos=${_player.position.inMilliseconds}ms currentTitle=${currentSong?.title}');
27
      _queuedOnlineSwitchIndex = queuedIndex;
28
      debugPrint(
29
          '[AudioManager][CMD] skipToNext queued targetIndex=$queuedIndex queued=$_queuedOnlineSwitchIndex baseIndex=$baseIndex');
30
      return;
31
    }
32
  }
33

34
  final nextIndex = _resolveNextIndex(
35
    baseIndex: baseIndex,
36
    reshuffleOnWrap: true,
37
  );
38
  if (nextIndex < 0) return;
39

40
  if (_lastSkipToNextAt != null &&
41
      now.difference(_lastSkipToNextAt!) < _skipToNextThrottle) {
42
    debugPrint('[AudioManager] skipToNext throttled');
43
    return;
44
  }
45
  _lastSkipToNextAt = now;
46

47
  await playAtIndex(nextIndex);
48
}

展开收起

这一段的意义是：

当前切歌没完成时，新的点击不会立即执行；
但也不会被吞掉；
当前切歌结束后，会自动接管 _queuedOnlineSwitchIndex。

用户体感会从“按钮不灵”变成“虽然忙，但会接着响应我最后一次操作”。

9. playAtIndex：这才是整个系统真正的中心#

所有修复最终都落在 playAtIndex(int index) 上。

这段逻辑里，我最后确认必须处理好三件事：

如果在线播放列表启动流程还没结束，先取消旧启动会话。
如果当前已经在切歌，不再直接执行，而是记录 queued target。
真正执行切歌时，整个过程都要受 switchToken 保护。

核心代码如下：

1
Future<void> playAtIndex(int index) async {
2
  if (index < 0 || index >= _playlist.length) return;
3

4
  // Cancel any ongoing fallback recovery for a previous track.
5
  _fallbackManager.cancelCurrentFallback();
6

7
  // Handle online playlist - need to resolve URL and create new audio source
8
  if (_isOnlinePlaylist && _onlineSongList != null && _urlResolver != null) {
9
    _onlineRecoveryShouldResumePlayback = true;
10
    final boardSong = _onlineSongList![index];
11
    if (_isSettingOnlinePlaylist) {
12
      final canceledToken = _onlinePlaylistSessionToken;
13
      _onlinePlaylistSessionToken++;
14
      _isSettingOnlinePlaylist = false;
15
      debugPrint(
16
          '[AudioManager][SWITCH] cancel pending online start token=$canceledToken by manual switch target=$index');
17
    }
18
    if (_isSwitchingOnlineTrack) {
19
      _queuedOnlineSwitchIndex = index;
20
      _pendingOnlineSwitchIndex = index;
21
      _updatePlaybackState();
22
      debugPrint(
23
          '[AudioManager][SWITCH] switching in progress, queue target index=$index queued=$_queuedOnlineSwitchIndex pending=$_pendingOnlineSwitchIndex current=$_currentIndex');
24
      return;
25
    }
26
    _isSwitchingOnlineTrack = true;
27
    _onlineTrackSwitchStartedAt = DateTime.now();
28
    _pendingOnlineSwitchIndex = index;
29
    _updatePlaybackState();
30
    final switchToken = ++_onlineSwitchToken;
31

32
    try {
33
      // ... resolve / cached source / network source / play
34

35
      if (switchToken != _onlineSwitchToken) {
36
        debugPrint(
37
            '[AudioManager][SWITCH] stale network switch ignored token=$switchToken latest=$_onlineSwitchToken index=$index');
38
        return;
39
      }
40

41
      _currentIndex = index;
42
      _updateNowPlayingMediaItem(mediaItems[index], force: true);
43
      _updatePlaybackState();
44
    } finally {
45
      if (switchToken == _onlineSwitchToken) {
46
        _isSwitchingOnlineTrack = false;
47
        _onlineTrackSwitchStartedAt = null;
48
        _pendingOnlineSwitchIndex = null;
49

50
        final queuedIndex = _queuedOnlineSwitchIndex;
51
        if (queuedIndex != null && queuedIndex != _currentIndex) {
52
          _queuedOnlineSwitchIndex = null;
53
          debugPrint(
54
              '[AudioManager][SWITCH] drain queued switch queued=$queuedIndex current=$_currentIndex token=$switchToken');
55
          unawaited(playAtIndex(queuedIndex));
56
        } else {
57
          _queuedOnlineSwitchIndex = null;
58
        }
59
      }
60
    }
61
  }
62
}

展开收起

这一段基本把问题全部收口了。

它解决的是三个最现实的 bug：

旧 start 会话晚到回写
旧切歌任务晚到回写
切歌中用户再次点击被吞掉

10. iOS 后台最关键的坑：缓存切歌时，不要等 `play()` Future 返回#

这一步是我觉得最“值钱”的结论。

日志里我反复看到这种现象：

iOS cached source set ok 很快出现；
但 await _player.play() 可能几秒，甚至十几秒后才返回；
更离谱的是，有时音频已经播了，play() Future 还没 resolve。

如果你这时的代码顺序是：

1
await _player.setAudioSource(source);
2
await _player.play();
3
_currentIndex = index;
4
mediaItem.add(...);

那就等于把“元数据切换”绑死在 play() Future 的完成时机上。

在 iOS 后台场景下，这个绑定非常危险。

所以我最后改成了：

1
if (Platform.isIOS) {
2
  debugPrint(
3
      '[AudioManager] iOS: Full audio reset for background track switch');
4
  try {
5
    // Stop completely first
6
    await _player.stop();
7
    await Future<void>.delayed(const Duration(milliseconds: 50));
8

9
    // Re-activate audio session
10
    final session = await AudioSession.instance;
11
    await session.setActive(true);
12

13
    final fileUri = Uri.file(cachedAudio);
14
    final audioSource = _buildOnlineProgressiveSource(
15
      fileUri,
16
      song: updatedSong,
17
      duration: Duration(milliseconds: updatedSong.duration),
18
    );
19
    await _setOnlineSingleSourceForSwitch(
20
      audioSource,
21
      playlistIndex: index,
22
      reason: 'switch_ios_cached:index=$index',
23
    );
24
    debugPrint(
25
        '[AudioManager][SWITCH] iOS cached source set ok index=$index');
26

27
    final playFuture = _player.play();
28
    unawaited(playFuture.then((_) {
29
      debugPrint(
30
          '[AudioManager][SWITCH] iOS cached play completed token=$switchToken index=$index');
31
    }).catchError((Object e, StackTrace st) {
32
      debugPrint(
33
          '[AudioManager][SWITCH] iOS cached play failed token=$switchToken index=$index error=$e');
34
    }));
35
    debugPrint(
36
        '[AudioManager][SWITCH] iOS cached play requested token=$switchToken index=$index');
37
    if (switchToken != _onlineSwitchToken) {
38
      debugPrint(
39
          '[AudioManager][SWITCH] stale iOS cached switch ignored token=$switchToken latest=$_onlineSwitchToken index=$index');
40
      return;
41
    }
42
  } catch (e) {
43
    debugPrint(
44
        '[AudioManager][SWITCH] iOS background audio reset failed index=$index error=$e');
45
    rethrow;
46
  }
47
}

展开收起

这里真正关键的不是“加了 stop()”或者“加了 50ms delay”。

真正关键的是这句：

1
final playFuture = _player.play();
2
unawaited(playFuture)

换句话说：

play() 要发起；
但状态提交不要被 play() Future 的完成时机绑架。

这一步改完之后，iOS 后台“声音已经切了，但系统元数据还没切”的问题明显少了很多。

11. 只修切歌还不够：在线播放列表启动流程也要防“晚到回写”#

前面说过，playAtIndex 不是唯一会写播放状态的链路。

如果你的项目也有 setOnlinePlaylist(...) 这种“加载列表并自动播第一首”的入口，那它本身也必须带 token。

我这边是这样处理的：

1
final sessionToken = ++_onlinePlaylistSessionToken;
2

3
await _player.setAudioSource(
4
  _onlineConcatenatingSource!,
5
  initialIndex: 0,
6
);
7
if (sessionToken != _onlinePlaylistSessionToken) {
8
  debugPrint(
9
      '[AudioManager][ONLINE_START] stale after setAudioSource token=$sessionToken latest=$_onlinePlaylistSessionToken ignored');
10
  return;
11
}
12

13
_updateNowPlayingMediaItem(mediaItems[_currentIndex], force: true);
14
_updatePlaybackState();
15
if (autoPlay) {
16
  await play();
17
  if (sessionToken != _onlinePlaylistSessionToken) {
18
    debugPrint(
19
        '[AudioManager][ONLINE_START] stale after play token=$sessionToken latest=$_onlinePlaylistSessionToken ignored');
20
    return;
21
  }
22
}

展开收起

这样做的意义是：

如果用户在在线播放列表启动过程中手动切歌；
旧启动流程即使晚回来，也会因为 token 过期被直接丢弃；
不会再把当前状态“拉回初始化那首歌”。

很多“明明切歌成功，过一会儿又回去了”的问题，本质都在这里。

12. 通知栏为什么会显示错歌？因为系统的 queueIndex 未必可信#

这一步是很多人容易忽略的。

audio_service 最终给 iOS Now Playing 的，不只是“播放/暂停状态”，还包括：

当前的 mediaItem
当前的 queueIndex
对应的 controls

如果 queueIndex 落后，或者 mediaItem 更新滞后，系统通知栏就会出现明显错位。

我最后做了两件事。

12.1 queueIndex 优先使用自己维护的 `_currentIndex`#

1
PlaybackState _transformEvent(PlaybackEvent event) {
2
  return PlaybackState(
3
    controls: [
4
      MediaControl.skipToPrevious,
5
      Platform.isAndroid
6
          ? playPauseControl
7
          : (_player.playing ? MediaControl.pause : MediaControl.play),
8
      MediaControl.skipToNext,
9
    ],
10
    systemActions: const {
11
      MediaAction.play,
12
      MediaAction.pause,
13
      MediaAction.playPause,
14
      MediaAction.seek,
15
      MediaAction.seekForward,
16
      MediaAction.seekBackward,
17
      MediaAction.skipToNext,
18
      MediaAction.skipToPrevious,
19
      MediaAction.setShuffleMode,
20
      MediaAction.setRepeatMode,
21
    },
22
    androidCompactActionIndices: const [0, 1, 2],
23
    processingState: const {
24
      ProcessingState.idle: AudioProcessingState.loading,
25
      ProcessingState.loading: AudioProcessingState.loading,
26
      ProcessingState.buffering: AudioProcessingState.buffering,
27
      ProcessingState.ready: AudioProcessingState.ready,
28
      ProcessingState.completed: AudioProcessingState.completed,
29
    }[_player.processingState]!,
30
    playing: _player.playing,
31
    updatePosition: _player.position,
32
    bufferedPosition: _player.bufferedPosition,
33
    speed: _player.speed,
34
    queueIndex: _currentIndex >= 0 ? _currentIndex : event.currentIndex,
35
  );
36
}

展开收起

这句：

1
queueIndex: _currentIndex >= 0 ? _currentIndex : event.currentIndex

非常关键。

因为在某些在线场景里，播放器内部的 event.currentIndex 并不等于你业务上的当前歌曲索引。

12.2 切歌成功后主动推送新的 mediaItem#

我没有完全依赖播放器事件自己同步，而是在切歌成功后主动调用：

1
_updateNowPlayingMediaItem(mediaItems[index], force: true);

这样做的好处是：

一旦业务层已经确认“当前歌就是这首”；
就立即把它推给系统；
不再被动等待底层事件什么时候更新到位。

这一步对锁屏元数据一致性非常重要。

13. 一个容易忽略的细节：idle 不一定应该映射成系统 idle#

我这里还顺手修了一个很隐蔽的问题。

在某些切歌瞬间，播放器会短暂进入 ProcessingState.idle。如果这时你直接把它映射成系统的 AudioProcessingState.idle，iOS 可能会认为当前 Now Playing 会话已经结束。

所以最终我在系统状态映射里故意做了这个处理：

1
processingState: const {
2
  // NOTE: Map idle→loading (not idle) to prevent iOS from killing the
3
  // Now Playing session during track transitions.
4
  ProcessingState.idle: AudioProcessingState.loading,
5
  ProcessingState.loading: AudioProcessingState.loading,
6
  ProcessingState.buffering: AudioProcessingState.buffering,
7
  ProcessingState.ready: AudioProcessingState.ready,
8
  ProcessingState.completed: AudioProcessingState.completed,
9
}[_player.processingState]!,

这个改动不大，但对 iOS 后台切歌过程的稳定性是有帮助的。

因为从系统视角看，切歌瞬间更接近“正在 loading 下一首”，而不是“播放会话结束了”。

14. 复测时我主要盯哪些日志#

这类问题如果没有日志，基本只能靠猜。

我后来重点盯的是这些信号：

cancel pending online start token=...
switching in progress, queue target index=...
iOS cached source set ok
iOS cached play requested
stale ... ignored
drain queued switch queued=...

如果这些日志顺序是健康的，通常状态链路就是对的。

一个比较理想的切歌日志序列，大概会长这样：

1
[AudioManager][CMD] skipToNext targetIndex=12
2
[AudioManager][SWITCH] cancel pending online start token=7 by manual switch target=12
3
[AudioManager][SWITCH] start token=21 index=12 current=11 title=...
4
[AudioManager][SWITCH] iOS cached source set ok index=12
5
[AudioManager][SWITCH] iOS cached play requested token=21 index=12
6
[AudioManager][SYNC] switched(cached) currentIndex=12 ...

如果用户在切歌中又点了一次 next，还会看到：

1
[AudioManager][CMD] skipToNext queued targetIndex=13
2
[AudioManager][SWITCH] drain queued switch queued=13 current=12 token=21

这个“drain queued switch”非常关键，它代表第二次点击没有丢。

15. 本方法要点#

15.1 自动切歌最终调用 `skipToNext()`#

不要自己另写一套自动切歌逻辑。

15.2 在线切歌增加这四个状态字段#

1
bool _isSwitchingOnlineTrack = false;
2
DateTime? _onlineTrackSwitchStartedAt;
3
int _onlineSwitchToken = 0;
4
int? _pendingOnlineSwitchIndex;
5
int? _queuedOnlineSwitchIndex;

15.3 切歌中不要简单 return，要记录 queued target#

否则按钮会“像坏了一样”。

15.4 如果有在线播放列表初始化流程，也必须带 session token#

否则旧启动流程会回写状态。

15.5 iOS 后台缓存切歌时，不要等 `await player.play()`#

这是解决“声音切了但元数据还没切”的关键之一。

15.6 `queueIndex` 优先用自己维护的业务索引#

不要完全依赖 event.currentIndex。

16. 小结#

回头看，这次问题最有意思的地方是：

你一开始会以为它是：

某个按钮监听没接对；
某次 skipToNext() 没执行；
或者某个 UI 刷新晚了。

但真正的根因其实是：

播放器、通知栏、自动切歌、在线播放启动，这几条链路都能改同一份状态，但之前没有统一的切歌状态机去收口它们。

这次最终稳定下来，靠的不是某个神奇 hack，而是把职责重新拉直了：

入口统一；
切歌串行；
旧任务失效；
用户意图排队；
系统状态由业务索引主导；
iOS 后台的 play() 慢返回不再拖住元数据提交。

如果你在做 Flutter 音乐播放器，卡在 iOS 后台自动切歌或通知栏 next 这类问题上，我最建议先检查的，不是 UI，而是：

你的自动切歌和手动切歌是不是同一条主链路；
你的在线切歌是不是有 token + queued target；
你的通知栏 queueIndex 和 mediaItem 是不是由业务层真实当前歌曲驱动。

把这三件事处理好，很多“看起来很玄学”的 iOS 后台播放 bug，都会一下子变得非常具体，也非常好修。

我的音乐App-SollinPlayer，被Apple审核员判“涉黄”了

Sun, 19 Apr 2026 22:43:00 GMT

记一次离谱的App Store审核：纯音乐App被判定涉黄#

iShot_2026-04-19_22.42.32.png

这事儿已经过去一个月了，今天翻到当时的审核邮件，突然想记下来。大半年耗在一个音乐App上，UI改了八版，bug调得快吐了，提交审核的时候还跟朋友吹，说这简洁度Apple肯定爱，结果反手就收到三封拒绝邮件，当时看完人直接傻了。

当时直接存了审核邮件原文，没删没改，现在贴出来，大家随便看看：

Guideline 1.1.4 - Safety - Objectionable Content The app includes content that is considered pornographic. Apps with sexually explicit content and themes are not appropriate for the App Store.

说白了就是：你这App涉黄，不能上，回去改。现在回头看这句话，还是觉得离谱。

当时我盯着这行字看了三分钟，先去核对了提交的包，又怀疑审核员看串了项目——我这是音乐App啊，纯听歌的，界面素得不能再素，怎么就跟涉黄挂上钩了？

说实话，为了过审，我界面做得比Apple官网还素，半点儿擦边的东西都没有，社交功能不敢加，歌词只敢用官方纯文本，动态特效全砍了，就怕审核挑刺。核心就三个功能：听歌、建歌单、导本地音乐，干净得能反光，至今想不通问题出在哪。

当时更离谱的是，除了涉黄，还有两个拒绝理由：Guideline 2.3.1说我有隐藏功能，Guideline 1.1说我有冒犯性内容。

我当时把代码翻来覆去看了好几遍，连注释都没放过，也没找着什么隐藏功能。难不成我写的播放暂停键，在审核员眼里是啥隐藏涉黄开关？现在想起来，还觉得好笑。

当时还忍不住自我怀疑：是不是App图标有问题？那是我自己画的简单音符，纯色背景，连渐变色都不敢用；还是歌单名字踩雷了？“深夜治愈”“通勤必听”“学习专注”，这要是算冒犯，Apple音乐里的歌单不得全下架？

后来跟几个做iOS开发的朋友吐了个槽，才知道我不是唯一一个冤种。有个朋友做工具App，按钮颜色亮了点，被说可能让用户不适；还有个做读书App，就因为有夜间模式，被怀疑在深色模式里藏违规内容。合着Apple审核，当年全看审核员当天心情好坏？

当时最讽刺的是，我去App Store搜了下，真正擦边、伪装成工具的涉黄App，反而能正常上架，有的还能上排行榜。乔布斯当年说“想要色情内容就买Android”，结果那时候Apple Store里漏网之鱼一堆，我这个纯音乐App，倒成了重点打击对象，现在想起来，还是觉得迷惑。

我当时特意去翻了Apple的审核指南，里面说“拒绝越界内容”，但什么是越界，没任何明确标准，就一句“出现了我就知道”。合着全凭主观判断？他说你涉黄，你就涉黄，哪怕你只是个听歌的；他说你有隐藏功能，你就有，哪怕你连多余按钮都没有。

当时更气的是，审核邮件只说有问题，没说具体哪有问题。我总不能把整个App拆了重写吧？总不能把音符图标改成黑白的，歌单名字全改成“歌单1”“歌单2”吧？最后也没辙。

当时没别的招，只能瞎改一通再提交，赌审核员当天心情好点。说出去都没人信——一个连广告都不敢加的音乐App，居然被Apple扣了涉黄的帽子。

[LiveContainer] IOS无限制安装应用教程

Mon, 16 Mar 2026 15:38:00 GMT

前言#

最近体验了 LiveContainer/LiveContainer，体验很不错，之前的安装教程很繁琐，要装好多东西才能配置好，最近LiveContainer更新了，本想按原来老方式更新，但我在官方教程中发现了这个：nab138/iloader，发现这更是个神级软件，竟然可以一键安装并且不需要导入修复文件！！！

如果你也想在iPhone上无限制安装应用，请跟着我的教程来吧。

第一步：下载沙漏#

首先下载沙漏（比较方便，配置驱动啥的）

沙漏

第二步：开启开发者模式#

安装好驱动后，先打开你手机的开发者模式，该如何打开呢？还是网上搜一下吧，很简单的。

第三步：下载iloader#

开启开发者模式后，那么就可以下载 iloader 进行下一步了。

iloader

第四步：登录id后安装软件#

这界面就都很明了了，登陆一个你appleid小号，然后连接iPhone，点击LiveContainer + SideStore（稳定版），静等安装成功就好了。

iloader

第五步：安装过程#

第一次设置的话可能会安装失败，请不要着急，打开设置，进入可以在设置–通用–描述文件与设备管理里，找到刚刚用于签名的ID点击刚刚安装好的LiveContainer对它点击信任，然后回到iloader重新装一遍就好了。安装完成后，需要从 SideStore 导入证书，打开LiveContainer的右下角–设置，点击–从SideStore导入证书，然后回到App页面，点左上角的SideStore按钮切回到SideStore

第六步：使用说明#

进入到SideStore界面，在设置里登录上你前面的appleid，此时我发现我忘记写了很重要的一部分，那就是你需要一个美区appleid（很好注册的：创建你的 Apple 账户），在apple store 下载LocalDevXXX，至于xxx是什么你一搜就知道了，这个软件后面续签也会用到，下载之后打开，然后回到SideStore界面，点击My Apps，点Refresh All，等待成功即可。至此，安装教程便结束了，你找到心仪的.ipa文件直接用LiveContainer打开就可以安装了

注意事项（自动续签说明）#

这个软件要每七天续签一次，不然就得重新像刚刚那样用电脑重新安装了，下面分享一下用快捷指令来达到无感知自动续签，很方便的，锁屏下也可以自动续签。

把StosVXX换成LocalDevXXX，另外，如果显示这个

可以删掉这个操作，自己搜索 Refresh All Apps 加进去，在自动化里设置每周续签一两次就好了（续签的时候一定要连着WiFi）。教程到此就结束了，很多有趣的功能等待你自己挖掘！

虚拟定位#

今天发现虚拟定位软件StephenDev0/StikDebug .直接在LiveContainer内装就可以改位置，这样又省掉一个自签位置捏

本文转载至：[LiveContainer] IOS无限制安装应用教程 已获得作者授权。

Android/Flyme 通知栏“暂停后继续播放无响应”技术复盘：根因、关键代码与最终稳定方案

Thu, 05 Mar 2026 00:00:00 GMT

Android/Flyme 通知栏“暂停后继续播放无响应”技术复盘：根因、关键代码与最终稳定方案#

这篇偏技术细节，重点放在：问题如何被误导、如何用日志证明、最终是怎么改代码稳住的。

涉及核心文件：lib/core/services/audio_manager.dart

1. 问题现象与复现#

复现环境：

Android：Flyme 12.6.0.0A
App：1.0.5+2010~1.0.5+2014 逐版验证
构建：flutter build apk --release --split-per-abi

问题路径：

通知栏点暂停；
再点继续播放；
部分机型无反应。

附带异常：有些通知样式会出现一个方形按钮（本质是 stop/custom action 显示路径差异）。

2. 第一阶段：先清表层问题#

2.1 去掉 stop 按钮，固定 3 个控制位#

先把通知栏按钮收敛为三键：prev / play-pause / next。

1
controls: [
2
  MediaControl.skipToPrevious,
3
  if (_player.playing) MediaControl.pause else MediaControl.play,
4
  MediaControl.skipToNext,
5
],
6
androidCompactActionIndices: const [0, 1, 2],

同时移除 MediaControl.stop，避免 ROM 显示方形动作位导致误触 stop。

2.2 click() 不再依赖 playbackState.playing#

BaseAudioHandler.click() 默认根据 playbackState 判断切换，某些时刻可能滞后。改成看 _player.playing：

1
@override
2
Future<void> click([MediaButton button = MediaButton.media]) async {
3
  switch (button) {
4
    case MediaButton.media:
5
      if (_player.playing) {
6
        await pause();
7
      } else {
8
        await play();
9
      }
10
      break;
11
    case MediaButton.next:
12
      await skipToNext();
13
      break;
14
    case MediaButton.previous:
15
      await skipToPrevious();
16
      break;
17
  }
18
}

展开收起

2.3 onNotificationDeleted() 不再 stop#

默认实现会 stop()，在 Flyme 上可能导致暂停状态下通知被系统清理后队列丢失。

1
@override
2
Future<void> onNotificationDeleted() async {
3
  if (_player.playing) {
4
    await pause();
5
  } else {
6
    _savePlaybackState();
7
  }
8
}

这一步避免了 idx=-1 / playlist=0 这类“状态被清空”的问题。

3. 第二阶段：建立可观测性（先证明再改）#

为了避免“你测的不是我改的包”，增加双版本锚点：

启动版本：STARTUP_VERSION app=...+build
构建探针：BUILD_PROBE ...

1
static const String buildProbe =
2
    'AUDIO_MANAGER_BUILD_2026_02_27_NOTIFDBG_V7_PREPARE_B14';
3

4
debugPrint('[AudioManager][BUILD_PROBE] $buildProbe');

并加 NOTIF_DBG 全链路日志：

click() requested ...
play() requested ...
play() dispatch ...
play() post-check ...
play() future resolved ...

这样就能看清楚“到底有没有收到系统命令”“命令收到后有没有真正进入播放”。

4. 真正根因：`await _player.play()` 语义误用#

旧代码核心问题是把 await _player.play() 当成“播放立即开始”的同步点。

4.1 旧写法（有风险）#

1
@override
2
Future<void> play() async {
3
  await _ensureAudioSessionConfigured();
4
  await session.setActive(true);
5
  await _player.play(); // 这里会被长时间阻塞
6
  // 后续状态提交逻辑被拖延
7
}

4.2 日志证据#

实际日志里经常出现：

play() requested 在 T0
play() future resolved 在 T0 + 8s / 30s / 39s
且 resolve 发生时可能已经 pause 了

这说明 play() Future 更多是底层生命周期结束点，不适合作为 UI/通知链路的“立即成功”判定点。

5. 核心修复：改成“快速派发 + 异步观察”#

5.1 新增派发器 `_dispatchPlayerPlay`#

1
void _dispatchPlayerPlay(String reason) {
2
  _logNotificationDebug('play() dispatch reason=$reason');
3
  final startedAt = DateTime.now();
4
  unawaited(
5
    _player.play().then((_) {
6
      final elapsedMs = DateTime.now().difference(startedAt).inMilliseconds;
7
      _logNotificationDebug(
8
        'play() future resolved reason=$reason elapsed=${elapsedMs}ms',
9
      );
10
    }).catchError((Object e, StackTrace st) {
11
      debugPrint('[AudioManager] play() failed reason=$reason: $e');
12
    }),
13
  );
14
  unawaited(Future<void>.delayed(const Duration(milliseconds: 180), () {
15
    _logNotificationDebug('play() post-check reason=$reason');
16
  }));
17
}

展开收起

5.2 `play()` 改造#

1
@override
2
Future<void> play() async {
3
  await _ensureAudioSessionConfigured();
4
  final session = await AudioSession.instance;
5
  await session.setActive(true);
6

7
  if (_player.playing) return;
8

9
  final processing = _player.processingState;
10
  if (processing == ProcessingState.completed) {
11
    await _player.seek(Duration.zero);
12
    _dispatchPlayerPlay('completed_seek0');
13
    return;
14
  }
15

16
  if (processing == ProcessingState.idle) {
17
    if (_isOnlinePlaylist) {
18
      await _recoverOnlinePlayback('play_from_idle');
19
      return;
20
    }
21
    if (_concatenatingSource != null && _playlist.isNotEmpty) {
22
      final targetIndex = _currentIndex.clamp(0, _playlist.length - 1);
23
      _currentIndex = targetIndex;
24
      await _player.setAudioSource(_concatenatingSource!, initialIndex: targetIndex);
25
      _dispatchPlayerPlay('idle_local_reset');
26
      return;
27
    }
28
  }
29

30
  _dispatchPlayerPlay('primary');
31
}

展开收起

关键点：play() 现在是“命令立即下发”，不再被底层 Future 完成时间绑架。

6. Flyme 兼容层：把所有入口收敛到同一恢复链路#

在 Android MediaSession 中，ROM 可能走：

click
playFrom*
prepareFrom*
customAction

因此新增统一入口：

1
Future<void> _resumeFromExternalCommand(String command) async {
2
  _logNotificationDebug('$command received');
3
  if (_player.playing) return;
4
  if (!_ensureManagedIndexForExternalResume(command)) return;
5
  await play();
6
}

并将这些方法全部接入：

1
@override
2
Future<void> prepare() async => _resumeFromExternalCommand('prepare()');
3

4
@override
5
Future<void> prepareFromMediaId(String mediaId, [Map<String, dynamic>? extras])
6
  async => _resumeFromExternalCommand('prepareFromMediaId() mediaId=$mediaId extras=$extras');
7

8
@override
9
Future<void> playFromMediaId(String mediaId, [Map<String, dynamic>? extras])
10
  async => _resumeFromExternalCommand('playFromMediaId() mediaId=$mediaId extras=$extras');

索引自愈#

1
bool _ensureManagedIndexForExternalResume(String source) {
2
  if (_playlist.isEmpty) return false;
3
  if (_currentIndex >= 0 && _currentIndex < _playlist.length) return true;
4

5
  int? recoveredIndex;
6
  if (_isOnlinePlaylist) {
7
    final playerIndex = _player.currentIndex;
8
    if (playerIndex != null &&
9
        playerIndex >= 0 &&
10
        playerIndex < _onlinePlayerToPlaylistIndex.length) {
11
      final mappedIndex = _onlinePlayerToPlaylistIndex[playerIndex];
12
      if (mappedIndex >= 0 && mappedIndex < _playlist.length) {
13
        recoveredIndex = mappedIndex;
14
      }
15
    }
16
  }
17

18
  recoveredIndex ??= _player.currentIndex;
19
  recoveredIndex = (recoveredIndex == null || recoveredIndex < 0 || recoveredIndex >= _playlist.length)
20
      ? 0
21
      : recoveredIndex;
22

23
  _currentIndex = recoveredIndex;
24
  _updatePlaybackState();
25
  return true;
26
}

展开收起

7. 最终稳定点：Android 中间键改成单一 `playPause`#

为了规避 Flyme 在 pause -> play 动作切换过程中的 PendingIntent 差异，中间控制改为 playPause，只切图标。

1
final playPauseControl = MediaControl(
2
  androidIcon: _player.playing
3
      ? 'drawable/audio_service_pause'
4
      : 'drawable/audio_service_play_arrow',
5
  label: _player.playing ? 'Pause' : 'Play',
6
  action: MediaAction.playPause,
7
);
8

9
controls: [
10
  MediaControl.skipToPrevious,
11
  Platform.isAndroid
12
      ? playPauseControl
13
      : (_player.playing ? MediaControl.pause : MediaControl.play),
14
  MediaControl.skipToNext,
15
],

展开收起

最终日志从 controls=[...,play,...] 变成 controls=[...,playPause,...]，并在 Flyme 上稳定。

8. 最终验证（B14）#

最终验证版本：

app=1.0.5+2014
probe=AUDIO_MANAGER_BUILD_2026_02_27_NOTIFDBG_V7_PREPARE_B14

关键验证链路（通知栏）：

click(media) -> pause() 成功
再次 click(media) -> play() dispatch -> playing=true 成功
多轮 pause/play 成功
click(next) 切歌成功

这说明问题已经从“偶发不可控”转为“可复现可观测且已稳定修复”。

9. 经验总结（面向工程）#

先观测，后猜测：跨 ROM 问题没有日志就没有真相。
明确 Future 语义：play() 的 Future 不等于“开始播放成功”。
命令链路收敛：click/playFrom/prepare/customAction 必须兜底到统一恢复路径。
通知动作尽量稳定：Android 上 playPause 常比动态切 play/pause 更兼容。
版本探针必须跟每轮修复绑定：避免“测错包”让排障退化为玄学。

播放页默认封面切换闪烁（技术细节版）：从资源猜测到动画结构稳定性的完整修复

Wed, 11 Feb 2026 00:00:00 GMT

播放页默认封面切换闪烁（技术细节版）：从资源猜测到动画结构稳定性的完整修复#

这篇是上一版复盘的技术加强版，重点补上：

具体代码点位
为什么前几轮“看起来合理”的修复无效
最终有效方案背后的渲染机制

1. 问题定义（精确到动画阶段）#

问题不是“默认封面偶发闪”，而是：

仅默认封面（无 artworkPath）会闪；
真实歌曲封面不闪；
闪烁发生在动画临界点：
- 大封面开始缩小时（t 从 0 往上）
- 小封面回大封面结束时（t 回到 0）

这类现象在 Flutter 里通常优先怀疑：

动画树结构在阈值发生插拔（if (t > 0)）；
同一视觉对象走了两条不同渲染链路；
资源首帧不可用（次要）。

2. 关键代码背景#

播放器核心动画在：

lib/features/player/presentation/screens/player_screen.dart
方法：_buildAnimatedLayout(...)
驱动：AnimatedBuilder(animation: _layoutAnimation, ...)

封面渲染组件在：

lib/core/widgets/artwork_widget.dart

默认封面资源：

assets/images/fengmiantu.png

3. 失败方案（为什么失败）#

方案 A：仅做默认图预缓存#

做法：

1
await precacheImage(const AssetImage('assets/images/fengmiantu.png'), context);

结论：无效（或仅轻微改善）。

原因：

预缓存只能解决“资源首帧缺失”；
解决不了动画临界点的节点替换/重建。

方案 B：固定默认图 provider + DecorationImage#

做法：

1
const AssetImage _kDefaultCoverProvider = AssetImage(_kDefaultCoverAsset);

并用 DecorationImage 渲染默认封面。

结论：改善但不根治。

原因：

资源流稳定了，但动画结构仍在临界点变化。

方案 C：默认封面单独分支优化（RepaintBoundary 等）#

做法：给默认封面做独立分支组件，尝试压缩重绘。

结论：仍闪。

原因：

真实封面和默认封面路径差异仍在；
动画临界点依旧可能触发分支切换。

4. 真正根因（双重）#

根因 1：动画时存在结构插拔#

播放器动画里歌词层最初是类似：

1
if (t > 0) Positioned(...)

当 t 在 0 附近跳变时，Stack 子节点会插入/移除，容易出现一帧闪动。

根因 2：默认封面与真实封面走了不同渲染路径#

真实封面：ArtworkWidget 正常路径
默认封面：专用分支路径

只要路径不一致，动画临界点就更容易出现“仅某一类素材闪”的问题。

5. 最终有效方案（代码级）#

5.1 歌词层常驻，禁止阈值插拔#

把：

1
if (t > 0) Positioned(...)

改为：

1
Positioned(
2
  ...
3
  child: IgnorePointer(
4
    ignoring: lyricsOpacity < 0.01,
5
    child: Opacity(
6
      opacity: lyricsOpacity,
7
      child: _buildLyricsSection(context, state),
8
    ),
9
  ),
10
)

效果：Stack 子节点数量在动画全过程保持稳定。

5.2 统一封面渲染链路：`ArtworkWidget` 增加强制默认图开关#

在 ArtworkWidget 新增参数：

1
final bool forceDefaultArtwork;

构造参数默认值：

1
this.forceDefaultArtwork = false,

在 _buildArtwork 顶部短路：

1
if (forceDefaultArtwork) {
2
  return placeholder ?? _DefaultArtwork(size: size);
3
}

然后在播放器动画里，无论有无封面都走 ArtworkWidget，只是无封面时启用：

1
ArtworkWidget(
2
  id: song?.id,
3
  artworkPath: song?.artworkPath,
4
  ...
5
  allowQueryArtworkFallback: false,
6
  forceDefaultArtwork: song?.artworkPath == null || song!.artworkPath!.isEmpty,
7
)

这一步是关键：把“默认封面和真实封面”收敛到一套布局/裁剪/动画容器。

5.3 保留资源稳定性措施（作为配套，不是主因）#

默认图固定 provider：

1
const AssetImage _kDefaultCoverProvider = AssetImage(_kDefaultCoverAsset);

播放器 init 后预缓存：

1
WidgetsBinding.instance.addPostFrameCallback((_) {
2
  _precacheDefaultCoverIfNeeded();
3
});

6. 关键文件变更点（便于回看）#

默认封面常量与 provider：
- lib/core/widgets/artwork_widget.dart
forceDefaultArtwork 参数与 _buildArtwork 短路逻辑：
- lib/core/widgets/artwork_widget.dart
播放器动画中的封面统一渲染调用：
- lib/features/player/presentation/screens/player_screen.dart
歌词层改为常驻透明：
- lib/features/player/presentation/screens/player_screen.dart

7. 可复用排查模板（建议保存）#

遇到“只在某类素材/状态闪烁”的动画问题时，按这个顺序：

先定位闪烁时刻：开始、中间、结束？
查结构插拔：是否有 if (t > x) 控制子树挂载？
查渲染路径分叉：同一视觉对象是否有多分支实现？
再做资源优化：precache、固定 provider、filterQuality。

经验上，前两步通常决定成败。

8. 这次的错误与改进#

错误#

先入为主把问题当成“默认图加载慢”；
前几轮都在做资源层补丁，没有第一时间稳定动画结构。

改进#

以后先看“节点是否在临界点插拔”；
优先统一渲染链路，再做性能细化。

9. 一句话总结#

这次闪烁不是“图片慢”，而是“动画树不稳”。

把节点变常驻、把路径变统一，问题自然消失。

在线播放切歌“声音和信息不一致”：一次从入口补丁到状态链路重构的排查

Mon, 09 Feb 2026 00:00:00 GMT

在线播放切歌“声音和信息不一致”：一次从入口补丁到状态链路重构的排查#

这个 Bug 折腾了我一整个下午：

在播放器里点上一首/下一首，声音切过去了；
但封面、歌名、评论按钮绑定的歌曲有时还是旧的；
有时点一下暂停，信息又“突然正常”。

最容易复现的路径是：

点播放 A（正常）
切到 B（正常）
再切回 A（声音回去了，但 UI 还显示 B）

这不是单点 bug，而是几个并发问题叠在一起。

现象：日志看起来“多数正确”，但体验不稳定#

先看表面，很多日志都很“健康”：

targetIndex 对
SWITCH success 对
currentIndex/mediaItem 也经常对

但偶发时会出现两类关键信号：

iOS cached source set ok 很快出现，但 iOS cached play ok 可能晚几秒甚至十几秒；
切歌过程中又出现 Online playlist started with ConcatenatingAudioSource 这种“启动流程晚到”日志。

这两类一叠加，就会造成：

用户已经继续点了切歌；
旧异步流程晚回来后又写状态；
UI 和音频出现错位，直到下一次播放状态事件（比如 pause）才被动刷新。

第一轮碰壁：只做“入口防重入”不够#

最开始做的是常规处理：

加 _isSwitchingOnlineTrack 锁；
正在切歌时忽略新点击；
加切歌节流。

这能减少乱点，但有两个副作用：

用户点击被吞掉，体感“按钮不灵”；
索引计算还基于旧 currentIndex，后续点击方向会错。

结论：只靠入口锁，治标不治本。

第二轮碰壁：只做 token 防串写，仍有漏网#

随后给 playAtIndex 加了 switchToken，防止旧切歌晚回来覆盖新状态。

这一步是对的，但仍有残留：

setOnlinePlaylist 自身也是异步链路；
用户手动切歌后，旧的“启动在线播放列表”流程可能继续完成并回写状态。

于是出现了一个很迷惑的现象：

切歌明明成功了，过一会儿 UI 又被“拉回去”或延迟刷新。

真正根因：不是一个 race，是三条状态链路在竞争#

最终确认是三层并发竞争：

手动切歌链路（skip -> playAtIndex -> setAudioSource/play -> commit）
在线播放启动链路（setOnlinePlaylist -> setAudioSource/play -> commit）
UI 数据源链路（一部分组件读 stream state，一部分直接读 audioManager.currentSong）

只要这三条不统一，某个链路晚到就可能覆盖另一个链路，导致“声音和信息不同步”。

最终方案（分层修复）#

1）切歌链路：token + 排队，不再简单 ignore#

在 AudioManager.playAtIndex 的在线分支里：

每次切歌递增 switchToken；
在 setSource/play/commit 前后都检查 token；
过期任务直接 stale ignored，不允许写 _currentIndex/mediaItem/queue。

同时增加了“切歌排队”而不是“切歌忽略”：

切歌进行中收到新的 next/prev，不丢弃，写入 _queuedOnlineSwitchIndex；
当前切歌完成后自动 drain 队列，执行最后一次用户意图。

这样既避免了串写，又保留了交互连续性。

2）在线播放启动链路：增加 session token，防晚到回写#

给 setOnlinePlaylist 单独加了 online start session token：

启动时记录 sessionToken；
setAudioSource 后、play 后都校验是否过期；
过期则打印 stale ... ignored 并退出，不再提交状态。

再加一条关键策略：

用户手动切歌时，主动取消 pending 的 online start session。

这一步直接解决了“切歌中又出现 Online playlist started 并污染状态”的问题。

3）iOS 缓存切歌：不再阻塞等待 `play()` Future 完成#

日志里反复出现：

iOS cached source set ok 很快
但 await _player.play() 可能很久才返回

如果等它返回再提交 UI，信息会明显滞后。

所以改成：

发起 play() 请求（异步监听成功/失败日志）；
状态提交不再被 play() Future 阻塞。

这让 UI 不会因为 iOS 的慢返回而“卡住旧歌信息”。

4）UI 层收口：统一从 `playbackState` 读当前歌曲#

播放器页面之前有双数据源：

有些组件读 playbackState.currentSong
有些组件直接读 audioManager.currentSong

这会导致同一帧内不同组件看的是不同快照。

最终把播放页关键区域收口到同一来源：

额外控制区按钮（评论/喜欢/加入/队列）
歌词当前 song id
队列高亮当前歌曲

统一由 AudioPlaybackState 驱动，避免“局部刷新好了，局部还旧”的视觉撕裂。

为什么“点暂停就会刷新”#

这个现象很有迷惑性，其实是线索：

点暂停会触发一轮新的播放状态事件（playing=false）；
UI 依赖的 stream 被强制推进一次；
之前没对齐的局部状态在这次重建里碰巧对齐了。

所以“暂停能修好”不是修复，而是状态链路竞争被下一次事件掩盖。

最终验证（复测路径）#

重点复测了这几条：

A -> B -> A（最容易复现）
连续快速上一首/下一首
在线缓存命中切歌
切歌与在线播放列表启动并发

关键日志特征变为：

旧流程：stale ... ignored
手动切歌会取消旧 start：cancel pending online start ...
切歌中点击：queued targetIndex=...
切歌完成自动接管：drain queued switch ...

最终表现恢复稳定：音频与歌名/封面/功能按钮绑定一致，不再需要“点暂停触发刷新”。

关键代码（节选）#

下面贴的是这次修复里最关键的几段代码，都是“去竞态”的核心点。

A. 在线切歌 token 防串写#

文件：lib/core/services/audio_manager.dart

1
// fields
2
int _onlineSwitchToken = 0;
3
int? _pendingOnlineSwitchIndex;
4
int? _queuedOnlineSwitchIndex;
5

6
Future<void> playAtIndex(int index) async {
7
  if (_isOnlinePlaylist && _onlineSongList != null && _urlResolver != null) {
8
    if (_isSwitchingOnlineTrack) {
9
      _queuedOnlineSwitchIndex = index;
10
      debugPrint(
11
        '[AudioManager][SWITCH] switching in progress, queue target index=$index',
12
      );
13
      return;
14
    }
15

16
    _isSwitchingOnlineTrack = true;
17
    _pendingOnlineSwitchIndex = index;
18
    final switchToken = ++_onlineSwitchToken;
19

20
    try {
21
      // ... resolve / set source / play
22

23
      if (switchToken != _onlineSwitchToken) {
24
        debugPrint('[AudioManager][SWITCH] stale switch ignored token=$switchToken');
25
        return;
26
      }
27

28
      _currentIndex = index;
29
      mediaItem.add(queue.value[index]);
30
      _updatePlaybackState();
31
    } finally {
32
      if (switchToken == _onlineSwitchToken) {
33
        _isSwitchingOnlineTrack = false;
34
        _pendingOnlineSwitchIndex = null;
35

36
        final queued = _queuedOnlineSwitchIndex;
37
        if (queued != null && queued != _currentIndex) {
38
          _queuedOnlineSwitchIndex = null;
39
          unawaited(playAtIndex(queued));
40
        } else {
41
          _queuedOnlineSwitchIndex = null;
42
        }
43
      }
44
    }
45
  }
46
}

展开收起

B. 切歌期间不忽略点击，改为“按 pending index 计算 + 入队”#

文件：lib/core/services/audio_manager.dart

1
@override
2
Future<void> skipToNext() async {
3
  final baseIndex = (_isOnlinePlaylist && _isSwitchingOnlineTrack)
4
      ? (_pendingOnlineSwitchIndex ?? _currentIndex)
5
      : _currentIndex;
6

7
  final nextIndex = baseIndex < _playlist.length - 1 ? baseIndex + 1 : 0;
8

9
  if (_isOnlinePlaylist && _isSwitchingOnlineTrack) {
10
    _queuedOnlineSwitchIndex = nextIndex;
11
    debugPrint('[AudioManager][CMD] skipToNext queued targetIndex=$nextIndex');
12
    return;
13
  }
14

15
  await playAtIndex(nextIndex);
16
}

展开收起

C. 在线播放启动流程加 session token，防“晚到回写”#

文件：lib/core/services/audio_manager.dart

1
int _onlinePlaylistSessionToken = 0;
2
bool _isSettingOnlinePlaylist = false;
3

4
Future<void> setOnlinePlaylist(...) async {
5
  final sessionToken = ++_onlinePlaylistSessionToken;
6
  _isSettingOnlinePlaylist = true;
7

8
  try {
9
    await _player.setAudioSource(_onlineConcatenatingSource!, initialIndex: 0);
10
    if (sessionToken != _onlinePlaylistSessionToken) return;
11

12
    mediaItem.add(mediaItems[_currentIndex]);
13
    _updatePlaybackState();
14
    await play();
15
    if (sessionToken != _onlinePlaylistSessionToken) return;
16
  } finally {
17
    if (sessionToken == _onlinePlaylistSessionToken) {
18
      _isSettingOnlinePlaylist = false;
19
    }
20
  }
21
}
22

23
// 手动切歌时，取消旧启动会话
24
if (_isSettingOnlinePlaylist) {
25
  _onlinePlaylistSessionToken++;
26
  _isSettingOnlinePlaylist = false;
27
}

展开收起

D. iOS 缓存切歌不再阻塞等 play() Future#

文件：lib/core/services/audio_manager.dart

1
await _setOnlineSingleSource(audioSource, playlistIndex: index);
2
debugPrint('[AudioManager][SWITCH] iOS cached source set ok index=$index');
3

4
// 不 await，避免 iOS 后台场景 play() 返回很慢导致 UI 卡旧状态
5
final playFuture = _player.play();
6
unawaited(playFuture.then((_) {
7
  debugPrint('[AudioManager][SWITCH] iOS cached play completed index=$index');
8
}));
9

10
debugPrint('[AudioManager][SWITCH] iOS cached play requested index=$index');
11

12
// 继续提交 currentIndex / mediaItem / playbackState
13
_currentIndex = index;
14
mediaItem.add(queue.value[index]);
15
_updatePlaybackState();

展开收起

E. 播放页统一从 `playbackState` 读当前歌曲#

文件：lib/features/player/presentation/screens/player_screen.dart

1
Widget _buildAdditionalControls(
2
  BuildContext context,
3
  AudioPlaybackState state,
4
) {
5
  final currentSong = state.currentSong; // 不再读 audioManager.currentSong
6
  // ...
7
}
8

9
Widget _buildLyricsSection(BuildContext context, AudioPlaybackState state) {
10
  final currentSongId = state.currentSong?.id;
11
  // ...
12
}
13

14
void _showPlayQueueSheet(BuildContext context, AudioPlaybackState state) {
15
  int currentIndex = state.currentIndex ?? -1;
16
  // fallback 再按 state.currentSong 匹配
17
}

展开收起

这几段加起来，才真正把“音频切了、UI没切”这种不一致压下去。

小结#

这个问题最大的坑是：

你以为是“切歌函数有 bug”，其实是“多条异步状态通道没有收口”。

经验总结：

音频播放器的稳定性，核心不在某个 API，而在状态流是否单一、可判定、可取消；
“忽略点击”通常只是临时止血，真正可用的是“排队 + 去重 + 过期丢弃”；
UI 必须尽量只吃一个状态源，避免同屏多个真相。

这次修完后，切歌日志终于从“看不懂谁覆盖谁”变成了“每次状态变化都有因果链”。后续再出类似问题，定位成本会低很多。

重装后收藏/喜欢歌曲不见了：一次「ID 稳定性 + 数据迁移」的修复记录

Fri, 16 Jan 2026 00:00:00 GMT

重装后收藏/喜欢不见了：一次「ID 稳定性 + 数据迁移」的修复记录#

最近有个很典型、也很容易被忽略的问题：应用重装之后，收藏的歌曲、喜欢的歌曲看起来“全没了”。

更准确地说是：收藏数据其实还在本地存储里，但 UI 匹配不到对应的歌曲，于是喜欢列表/歌单展示为空。

现象与日志#

用户侧的表现很直观：

重装 App
重新扫描本地歌曲（或重新授权）
「我喜欢的音乐」变成空
收藏/喜欢按钮状态也全变回未收藏

日志非常“打脸”：一边说 favorites 确实加载出来了，另一边却说匹配结果为 0。

1
[Favorites] Loaded 17 favorites: {804604524, 749312547, ...}
2
[Match Debug] First 3 song IDs: [1414957450, 147442901, 1927087886]
3
[Match Debug] First 3 favorites: [804604524, 749312547, 37290334]
4
[Match Debug] Matched 0 songs out of 17 favorites

这说明两件事：

favorites 的持久化没坏（能读到 17 个 id）
songs 列表也没坏（扫描出了歌曲 id）
但 favorites 里存的 id，和当前扫描出来的 song.id 已经不是同一套体系

排查路径：到底是谁变了？#

收藏/喜欢的存储很简单：本地只存 Set<int> 的 songId（shared_preferences），UI 展示时用：

1
final favoriteSongs = songs.where((s) => favorites.contains(s.id)).toList();

因此只要 s.id 的生成规则发生变化（或同一首歌在重装后拿到的 id 变了），favorites 就会“全部失效”。

我把排查重点放到两类常见不稳定来源：

1）系统媒体库 id 不稳定#

Android/iOS 的系统媒体库可能返回一个“看起来像主键”的 id（例如 on_audio_query 的 SongModel.id），但它未必承诺跨重装、跨版本、跨扫描一致。

2）用「文件绝对路径」生成 id，会被 iOS 重装打爆#

iOS 卸载重装后，App 的沙盒容器路径会变（例如 .../Application/<UUID>/Documents/... 里的 <UUID> 变了）。

如果 id 是 hash(绝对路径)，那同一个文件在新容器里就会产生完全不同的 id。

更糟的是：我之前为了修别的问题，把 id 从一种 hash 改成了另一种（比如 String.hashCode vs 自定义 hash），这也会让旧数据瞬间“断链”。

定位到关键点：收藏/歌单依赖「稳定 songId」#

播放器里有三处会依赖 songId：

喜欢/收藏（favorite_songs）
本地歌单（歌单里存 songIds）
播放状态恢复（缓存 playlist songIds + index）

只要 songId 不稳定，这三个功能都会在“升级/重装/换机”时出现类似问题。

所以修复目标不是“让匹配代码更聪明”，而是：

定义一套跨重装稳定的 songId 规则
对历史版本产生的旧 id 做迁移

解决方案一：canonical path + 稳定 hash#

我新增了一个 SongId 工具（lib/core/services/song_id.dart），做两件事：

对文件路径做 canonicalize：
- 如果文件位于 app 的 Documents 下，把“安装相关”的前缀剥离掉
- 把路径变成 "<DOCS>/Music/xxx.flac" 这种相对且稳定的形式
对 canonical path 做确定性 hash（djb2，并限定 31-bit 正整数）

核心思路：同一首歌只要相对路径不变，重装后 id 也不变。

解决方案二：启动时自动迁移旧数据#

光有新规则还不够：用户重装/升级后，preferences 里存的还是旧 id。

因此我在“扫描歌曲完成后”（LocalSongsNotifier.scanSongs()）追加了迁移步骤（lib/core/services/providers.dart）：

用当前扫描到的 songs 建一张映射表：
- key：旧算法可能生成的 legacyId（例如 filePath.hashCode、旧的 hash）
- value：当前 canonicalId（新规则算出来的 song.id）
用这张表批量改写：
- favorites（FavoritesService.migrateSongIds）
- playlists（PlaylistService.migrateSongIds，并保持原顺序去重）

迁移策略里有个小细节：如果同一个 legacyId 映射到多个 canonicalId（冲突），我会丢弃这个 legacyId 的映射，避免误把 A 歌迁到 B 歌。

验证与结果#

我补了一个最小单测，专门验证“iOS 容器路径变了，id 仍然一致”（test/song_id_test.dart）：

.../Application/AAA/Documents/Music/foo.mp3
.../Application/BBB/Documents/Music/foo.mp3

canonicalize 后都应变成 "<DOCS>/Music/foo.mp3"，因此 id 相同。

最终效果：

重装/升级后，favorites 仍然能匹配到歌曲
喜欢列表不再空
本地歌单不会因为 id 体系变化而“全失效”

小结#

这类问题的根本原因通常不是“收藏没存上”，而是 你存的是一个不稳定的引用（songId）。

经验总结：

只要你把业务数据（收藏/歌单/播放缓存）建立在某个 id 上，就要把这个 id 当作“长期协议”来设计
iOS 沙盒路径在重装后会变，绝对路径直接参与 id 计算会天然不稳定
一旦你不得不改 id 规则，务必提供迁移，否则用户数据会在升级后“看起来丢了”

iOS 本地 FLAC 拖动进度条不准：一次「日志正确但耳朵不对」的排查

Thu, 15 Jan 2026 00:00:00 GMT

iOS 本地 FLAC 拖动进度条不准：一次「日志正确但耳朵不对」的排查#

最近在重写一个 Flutter 本地音乐播放器，播放器内核用的是 just_audio + audio_service。本来一切都挺顺的，直到我开始认真测试「拖动播放界面的进度条」：UI 上的进度跳过去了，日志也说 seek 成功了，但耳朵听到的位置明显不对。

更离谱的是：哪怕你把 slider 直接拉到 100%，实际也没有播放到结尾，而是停在一个“看起来差不多但就是不对”的位置。

直接拖到结束还在播放

这个问题只在 iOS 的本地 FLAC 上稳定复现（文件放在应用沙盒里，不走系统媒体库）。

现象与复现条件#

平台：iOS（应用沙盒文件）
音频格式：FLAC
表现：
- seek 日志显示 position 已到目标值
- 实际听感偏前，拖到结尾仍未到结尾
- 歌曲时长无异常

日志示例（从 UI slider -> seek -> UI 认为“对齐”）：

1
[SLIDER] onChangeEnd: sliderValue=1.0, duration=247153ms, targetPosition=247153ms, actualPosition=5674ms
2
[SEEK] Request: target=247153ms, current=5869ms, duration=247153ms
3
[EFFECTIVE_POS] Aligned! actual=247153ms, pending=247153ms, delta=0ms
4
[SEEK] After seek(): position=247153ms

你看日志，完全没毛病：目标=247153ms、seek 后 position=247153ms、甚至 UI 的 “effectivePosition” 还打印了 Aligned!。但声音就是没到那儿。

排查路径（以及为什么这些路走不通）#

我一开始的直觉是“时长算错了 / 元数据不准”。毕竟拖到 100% 还不到尾部，很像 duration 出问题。

但很快就排掉了：同一首歌，无论用 on_audio_query 拿的 duration，还是解析 metadata 得到的 duration，显示都正常，且播放从头到尾的总时长也没问题。

接下来我开始怀疑是“UI 算法”或“状态更新延迟”，于是做了两件事：

1）把 slider 侧的 targetPosition 打印清楚#

进度条松手时我会算目标毫秒数并调用 seek（lib/features/player/presentation/screens/player_screen.dart），类似这样：

1
onChangeEnd: (value) async {
2
  final targetPosition = Duration(
3
    milliseconds: (value * duration.inMilliseconds).toInt(),
4
  );
5
  debugPrint('[SLIDER] onChangeEnd: sliderValue=$value, '
6
      'duration=${duration.inMilliseconds}ms, '
7
      'targetPosition=${targetPosition.inMilliseconds}ms, '
8
      'actualPosition=${state.position.inMilliseconds}ms');
9
  await audioManager?.seek(targetPosition);
10
}

这一步确认：targetPosition 绝对算对了，而且和 UI 上显示的时间一致。

2）把 AudioManager.seek 的前后状态也打出来#

我在 lib/core/services/audio_manager.dart 的 seek 里加了日志，并且等 ProcessingState.ready：

1
@override
2
Future<void> seek(Duration position) async {
3
  debugPrint('[SEEK] Request: target=${position.inMilliseconds}ms, '
4
      'current=${_player.position.inMilliseconds}ms, '
5
      'duration=${_player.duration?.inMilliseconds}ms');
6

7
  await _player.seek(position);
8

9
  debugPrint('[SEEK] After seek(): position=${_player.position.inMilliseconds}ms');
10

11
  await _player.processingStateStream
12
      .firstWhere((state) =>
13
          state == ProcessingState.ready ||
14
          state == ProcessingState.completed)
15
      .timeout(const Duration(seconds: 2),
16
          onTimeout: () => ProcessingState.ready);
17

18
  debugPrint('[SEEK] After ready: position=${_player.position.inMilliseconds}ms, '
19
      'processingState=${_player.processingState}');
20
}

展开收起

结果依然很诡异：position 的数值确实跳到了目标位置，ready 也到了，但实际听到的位置还是偏前。

这时候我才意识到：这不是“UI/状态没更新”，而是更底层的东西——iOS 对这个 FLAC 的 seek 本身不精确，而 just_audio 上报的 position 也不代表你耳朵听到的那一帧一定已经对齐。

定位到关键点：iOS 的精确时长/定位选项#

继续往下挖，我去翻了 just_audio 的 Darwin（iOS/macOS）实现。它本质上是用 AVURLAsset 创建 AVPlayerItem。在 Apple 的世界里，“快”和“准”是可以二选一的：默认情况下系统并不一定会用最精确的方式去解析时长与时间轴（尤其是本地文件、尤其是某些格式）。

just_audio 其实提供了一个开关，把它传到 AVURLAssetPreferPreciseDurationAndTimingKey 上：也就是 preferPreciseDurationAndTiming。

解决思路是：为 iOS 的 FLAC 文件启用精确时长/时间轴选项。

在 just_audio 里，这个选项对应：

1
DarwinAssetOptions(preferPreciseDurationAndTiming: true)

代码改动#

核心修改在 lib/core/services/audio_manager.dart，我最终做了三件事（这三件事组合起来才稳）：

播放列表构建 AudioSource 时，不再用默认的 AudioSource.uri(...)（它会根据 URI 判断类型，但我需要更明确地控制 options）。
改用 ProgressiveAudioSource(...)，并把 ProgressiveAudioSourceOptions 填进去（只对 iOS/macOS + .flac 启用精确模式）。
同时把 duration 也传给 source（song.durationAsDuration），作为一个更稳定的兜底（避免某些文件解析 duration 走近似路径）。

关键实现（节选）：

1
AudioSource _buildAudioSource(LocalSongModel song) {
2
  final filePath = song.filePath;
3
  if (filePath != null && filePath.isNotEmpty) {
4
    final file = File(filePath);
5
    if (file.existsSync()) {
6
      return _buildProgressiveSource(
7
        Uri.file(filePath),
8
        song,
9
        isFlac: filePath.toLowerCase().endsWith('.flac'),
10
      );
11
    }
12
  }
13

14
  final uri = Uri.parse(song.uri);
15
  return _buildProgressiveSource(
16
    uri,
17
    song,
18
    isFlac: uri.path.toLowerCase().endsWith('.flac'),
19
  );
20
}
21

22
AudioSource _buildProgressiveSource(
23
  Uri uri,
24
  LocalSongModel song, {
25
  required bool isFlac,
26
}) {
27
  final usePreciseTiming =
28
      isFlac && (Platform.isIOS || Platform.isMacOS);
29
  final options = usePreciseTiming
30
      ? const ProgressiveAudioSourceOptions(
31
          darwinAssetOptions:
32
              DarwinAssetOptions(preferPreciseDurationAndTiming: true),
33
        )
34
      : null;
35

36
  return ProgressiveAudioSource(
37
    uri,
38
    tag: song,
39
    duration: song.durationAsDuration,
40
    options: options,
41
  );
42
}

展开收起

然后在 setPlaylist 里统一用 _buildAudioSource 生成 playlist 的 children：

1
final audioSources = songs.map(_buildAudioSource).toList();
2
await _player.setAudioSource(
3
  ConcatenatingAudioSource(children: audioSources),
4
  initialIndex: _currentIndex,
5
);

这次修复的关键不是“再等一等”“再对齐一下 position”，而是让 iOS 在解析这个 FLAC 的时间轴时走精确路径。否则你在 Dart 层做再多校验，最终音频解码器/播放器层面还是会“跳到一个差不多的位置”。

结果#

FLAC 拖动进度条与实际听感一致
拖到尾部能真正到尾部
日志与听感完全对齐

小结#

这个问题的难点在于：你能拿到的一切“状态”都在告诉你它对了，但最终用户体验仍然是错的。
从“检查 duration/元数据”到“怀疑 UI 算法/状态延迟”再到“翻平台实现”，最后才发现真正的开关在 iOS 的 AVURLAsset 上。

如果你遇到类似情况（iOS + FLAC + seek 不准），优先试：

1
DarwinAssetOptions(preferPreciseDurationAndTiming: true)

最后补一句经验：播放器这种东西，UI 层能做的“看起来正确”很有限；一旦出现「UI 正确但耳朵不对」，多半是平台层（解码/seek/时基）的问题，不要在 Dart 层硬耗太久。

制作一个"登录或者评论领取激活码"插件

Thu, 08 Jan 2026 00:00:00 GMT

本文分享如何为你的 App 实现一个自动化激活码领取系统，支持 WordPress、Typecho 和静态博客（Astro/Hugo）。

一、后端 API（Flask）#

后端负责：生成激活码、验证请求签名、防止重复领取。

1.1 激活码模型#

1
from flask_sqlalchemy import SQLAlchemy
2

3
import random
4

5

6

7
db = SQLAlchemy()
8

9

10

11
class ActivationCode(db.Model):
12

13
id = db.Column(db.Integer, primary_key=True)
14

15
code = db.Column(db.String(20), unique=True, nullable=False)
16

17
device_id = db.Column(db.String(64)) # 绑定的设备
18

19
note = db.Column(db.String(200)) # 领取信息
20

21
is_active = db.Column(db.Boolean, default=True)
22

23
created_at = db.Column(db.DateTime, default=datetime.utcnow)
24

25

26

27
def generate_activation_code():
28

29
"""生成格式化激活码：XXXX-XXXX-XXXX-XXXX"""
30

31
chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ0123456789'
32

33
segments = [''.join(random.choices(chars, k=4)) for _ in range(4)]
34

35
return '-'.join(segments)

展开收起

1.2 领取接口#

1
@app.route('/api/get-code', methods=['POST'])
2

3
def claim_code():
4

5
data = request.get_json()
6

7
query = data.get('query', '').strip() # 用户唯一标识
8

9
secret = data.get('secret', '') # 密钥
10

11
timestamp = data.get('timestamp') # 时间戳
12

13
signature = data.get('signature', '') # HMAC 签名
14

15
# 1. 验证密钥
16

17
if secret != app.config['CLAIM_SECRET']:
18

19
return jsonify({'success': False, 'message': '密钥错误'}), 401
20

21
# 2. 验证时间戳（5分钟内有效，防止重放攻击）
22

23
if abs(time.time() - int(timestamp)) > 300:
24

25
return jsonify({'success': False, 'message': '请求已过期'}), 400
26

27
# 3. 验证签名
28

29
expected_sig = hmac.new(
30

31
secret.encode(),
32

33
f"{query}|{timestamp}|{secret}".encode(),
34

35
hashlib.sha256
36

37
).hexdigest()
38

39
if not hmac.compare_digest(signature, expected_sig):
40

41
return jsonify({'success': False, 'message': '签名验证失败'}), 401
42

43
# 4. 检查是否已领取
44

45
existing = ActivationCode.query.filter(
46

47
ActivationCode.note.like(f"Claimed by: {query} |%")
48

49
).first()
50

51
if existing:
52

53
return jsonify({'success': True, 'code': existing.code})
54

55
# 5. 生成新激活码
56

57
code = generate_activation_code()
58

59
new_code = ActivationCode(
60

61
code=code,
62

63
note=f"Claimed by: {query} | {data.get('username')} | {data.get('email')}"
64

65
)
66

67
db.session.add(new_code)
68

69
db.session.commit()
70

71
return jsonify({'success': True, 'code': code})

展开收起

1.3 安全措施#

威胁	防御措施
接口被滥用	HMAC-SHA256 签名验证
重放攻击	时间戳 5 分钟有效期
重复领取	数据库 `note` 字段记录用户标识

二、WordPress 插件#

WordPress 可以自动获取登录用户信息，实现”一键领取”。

2.1 插件结构#

文件：wp-content/plugins/activation-claimer/activation-claimer.php

1
<?php
2

3
/*
4

5
Plugin Name: Activation Code Claimer
6

7
Description: 允许已登录用户一键领取激活码
8

9
Version: 2.0
10

11
*/
12

13

14

15
if (!defined('ABSPATH')) exit;
16

17

18

19
class ActivationCodeClaimer {
20

21
private $api_url = 'https://your-api.com/api/get-code';
22

23
private $api_secret = 'your-secret-key';
24

25
private $claimed_meta_key = 'activation_code_claimed';
26

27

28

29
public function __construct() {
30

31
add_shortcode('claim_activation', [$this, 'render_form']);
32

33
}
34

35

36

37
public function render_form($atts) {
38

39
// 检查登录状态
40

41
if (!is_user_logged_in()) {
42

43
$login_url = wp_login_url(get_permalink());
44

45
return '<div class="acc-error">请先<a href="'.$login_url.'">登录</a></div>';
46

47
}
48

49

50

51
$user = wp_get_current_user();
52

53
$user_id = $user->ID;
54

55

56

57
// 检查是否已领取
58

59
$claimed_code = get_user_meta($user_id, $this->claimed_meta_key, true);
60

61
if ($claimed_code) {
62

63
return '<div class="acc-success">您的激活码：<code>'.$claimed_code.'</code></div>';
64

65
}
66

67

68

69
// 处理表单提交
70

71
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['claim_submit'])) {
72

73
return $this->handle_claim($user);
74

75
}
76

77

78

79
// 渲染表单
80

81
return $this->render_claim_form($user);
82

83
}
84

85

86

87
private function handle_claim($user) {
88

89
// 验证 Nonce
90

91
if (!wp_verify_nonce($_POST['acc_nonce'], 'acc_claim_action')) {
92

93
return '<div class="acc-error">安全验证失败</div>';
94

95
}
96

97

98

99
// 生成签名
100

101
$timestamp = time();
102

103
$user_identifier = 'wp_user_' . $user->ID;
104

105
$signature = hash_hmac('sha256',
106

107
"$user_identifier|$timestamp|{$this->api_secret}",
108

109
$this->api_secret
110

111
);
112

113

114

115
// 调用后端 API
116

117
$response = wp_remote_post($this->api_url, [
118

119
'body' => json_encode([
120

121
'query' => $user_identifier,
122

123
'username' => $user->user_login,
124

125
'email' => $user->user_email,
126

127
'timestamp' => $timestamp,
128

129
'signature' => $signature,
130

131
'secret' => $this->api_secret
132

133
]),
134

135
'headers' => ['Content-Type' => 'application/json'],
136

137
'timeout' => 15
138

139
]);
140

141

142

143
$data = json_decode(wp_remote_retrieve_body($response), true);
144

145
if ($data['success']) {
146

147
update_user_meta($user->ID, $this->claimed_meta_key, $data['code']);
148

149
return '<div class="acc-success">领取成功：<code>'.$data['code'].'</code></div>';
150

151
}
152

153
return '<div class="acc-error">'.$data['message'].'</div>';
154

155
}
156

157
}
158

159

160

161
new ActivationCodeClaimer();

展开收起

2.2 使用方法#

在文章或页面中插入短代码：

1
[claim_activation]

三、Typecho 插件#

3.1 插件结构#

文件夹：usr/plugins/ClaimActivation/Plugin.php

1
<?php
2

3
class ClaimActivation_Plugin implements Typecho_Plugin_Interface {
4

5
public static function activate() {
6

7
// 注册内容过滤器
8

9
Typecho_Plugin::factory('Widget_Abstract_Contents')
10

11
->contentEx = ['ClaimActivation_Plugin', 'contentFilter'];
12

13
return _t('插件已激活，使用 <!--claim--> 标记插入领取表单');
14

15
}
16

17

18

19
public static function deactivate() {}
20

21

22

23
public static function config(Typecho_Widget_Helper_Form $form) {
24

25
$form->addInput(new Typecho_Widget_Helper_Form_Element_Text(
26

27
'apiUrl', NULL, 'https://your-api.com/api/get-code',
28

29
_t('后端 API 地址')
30

31
));
32

33
$form->addInput(new Typecho_Widget_Helper_Form_Element_Text(
34

35
'apiSecret', NULL, 'your-secret-key',
36

37
_t('API 密钥')
38

39
));
40

41
}
42

43

44

45
public static function personalConfig(Typecho_Widget_Helper_Form $form) {}
46

47

48

49
// 内容过滤器：替换 <!--claim--> 标记
50

51
public static function contentFilter($content, $widget, $lastResult) {
52

53
$content = empty($lastResult) ? $content : $lastResult;
54

55
if (strpos($content, '<!--claim-->') !== false) {
56

57
$form = self::generateClaimForm();
58

59
$content = str_replace('<!--claim-->', $form, $content);
60

61
}
62

63
return $content;
64

65
}
66

67

68

69
private static function generateClaimForm() {
70

71
$user = Typecho_Widget::widget('Widget_User');
72

73
$options = Typecho_Widget::widget('Widget_Options');
74

75
$pluginOptions = $options->plugin('ClaimActivation');
76

77

78

79
// 未登录
80

81
if (!$user->hasLogin()) {
82

83
return '<div class="acc-error">请先<a href="'.$options->adminUrl.'">登录</a></div>';
84

85
}
86

87

88

89
// ... 其余逻辑与 WordPress 类似
90

91
// 检查是否已领取 → 生成签名 → 调用 API → 显示结果
92

93
}
94

95

96

97
private static function claimCode($userId, $username, $email, $apiUrl, $apiSecret) {
98

99
$timestamp = time();
100

101
$userIdentifier = 'typecho_user_' . $userId;
102

103
$signature = hash_hmac('sha256',
104

105
"$userIdentifier|$timestamp|$apiSecret",
106

107
$apiSecret
108

109
);
110

111

112

113
// 使用 cURL 发送请求
114

115
$ch = curl_init($apiUrl);
116

117
curl_setopt_array($ch, [
118

119
CURLOPT_POST => true,
120

121
CURLOPT_POSTFIELDS => json_encode([
122

123
'query' => $userIdentifier,
124

125
'username' => $username,
126

127
'email' => $email,
128

129
'timestamp' => $timestamp,
130

131
'signature' => $signature,
132

133
'secret' => $apiSecret
134

135
]),
136

137
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
138

139
CURLOPT_RETURNTRANSFER => true,
140

141
CURLOPT_TIMEOUT => 15
142

143
]);
144

145
$response = curl_exec($ch);
146

147
curl_close($ch);
148

149
return json_decode($response, true);
150

151
}
152

153

154

155
// 领取记录存储在 Typecho 的 options 表
156

157
private static function getClaimedCodes() {
158

159
$db = Typecho_Db::get();
160

161
$row = $db->fetchRow($db->select('value')
162

163
->from($db->getPrefix() . 'options')
164

165
->where('name = ?', 'plugin_ClaimActivation_claimed'));
166

167
return $row ? json_decode($row['value'], true) : [];
168

169
}
170

171
}

展开收起

3.2 使用方法#

在文章中插入 HTML 注释标记：

1
<!--claim-->

四、静态博客（Astro）#

静态博客无服务端，需要纯前端 JavaScript + 后端 API。

4.1 Astro 组件#

文件：src/components/ClaimCode.astro

1
---
2

3
interface Props {
4

5
apiUrl?: string;
6

7
}
8

9
const { apiUrl = 'https://your-api.com/api/claim-with-twikoo' } = Astro.props;
10

11
---
12

13

14

15
<div class="claim-wrapper" data-api-url={apiUrl}>
16

17
<div class="form-header">
18

19
<span class="icon">🎁</span>
20

21
<h3>领取激活码</h3>
22

23
<p>请输入您评论时使用的邮箱</p>
24

25
</div>
26

27
<div class="form-body">
28

29
<input type="email" id="claim-email" placeholder="your@email.com" />
30

31
<button id="claim-btn">领取激活码</button>
32

33
<p class="hint">💬 请先在下方评论区留言，使用相同邮箱即可领取</p>
34

35
</div>
36

37
<div id="result" style="display: none;"></div>
38

39
</div>
40

41

42

43
<style>
44

45
.claim-wrapper {
46

47
max-width: 420px;
48

49
padding: 1.5rem;
50

51
border-radius: 16px;
52

53
background: linear-gradient(135deg, #667eea10, #764ba210);
54

55
border: 1px solid #e0e0e0;
56

57
}
58

59
/* ... 更多样式 */
60

61
</style>
62

63

64

65
<script>
66

67
const wrapper = document.querySelector('.claim-wrapper');
68

69
const emailInput = document.getElementById('claim-email');
70

71
const claimBtn = document.getElementById('claim-btn');
72

73
const resultEl = document.getElementById('result');
74

75
const apiUrl = wrapper?.dataset.apiUrl;
76

77

78

79
claimBtn?.addEventListener('click', async () => {
80

81
const email = emailInput.value.trim();
82

83
if (!email || !email.includes('@')) {
84

85
showResult('error', '请输入有效的邮箱地址');
86

87
return;
88

89
}
90

91

92

93
claimBtn.disabled = true;
94

95
claimBtn.textContent = '验证中...';
96

97

98

99
try {
100

101
const res = await fetch(apiUrl, {
102

103
method: 'POST',
104

105
headers: { 'Content-Type': 'application/json' },
106

107
body: JSON.stringify({ email })
108

109
});
110

111
const data = await res.json();
112

113

114

115
if (data.success) {
116

117
showResult('success', `🎉 领取成功！<br><code>${data.code}</code>`);
118

119
emailInput.disabled = true;
120

121
claimBtn.style.display = 'none';
122

123
} else {
124

125
showResult('error', data.message);
126

127
claimBtn.disabled = false;
128

129
claimBtn.textContent = '领取激活码';
130

131
}
132

133
} catch (e) {
134

135
showResult('error', '网络错误，请稍后重试');
136

137
}
138

139
});
140

141

142

143
function showResult(type, message) {
144

145
resultEl.className = type;
146

147
resultEl.innerHTML = message;
148

149
resultEl.style.display = 'block';
150

151
}
152

153
</script>

展开收起

4.2 评论验证（可选）#

如果使用 Twikoo 评论系统，可以在后端验证用户是否评论过：

1
def verify_twikoo_comment(email):
2

3
from pymongo import MongoClient
4

5
client = MongoClient('mongodb+srv://...')
6

7
db = client['twikoo']
8

9
comment = db.comment.find_one({
10

11
'mail': {'$regex': f'^{email}$', '$options': 'i'}
12

13
})
14

15
client.close()
16

17
return comment is not None

展开收起

4.3 在页面中使用#

1
---
2

3
import ClaimCode from '../components/ClaimCode.astro';
4

5
---
6

7

8

9
<ClaimCode apiUrl="https://your-api.com/api/claim-with-twikoo" />
10

11

12

13
<!-- Twikoo 评论区 -->
14

15
<div id="tcomment"></div>

展开收起

五、UI 样式参考#

三种插件都使用了统一的样式设计：

1
.acc-wrapper {
2

3
max-width: 420px;
4

5
padding: 25px;
6

7
border: 1px solid #e0e0e0;
8

9
border-radius: 12px;
10

11
background: #fafafa;
12

13
}
14

15

16

17
.acc-btn {
18

19
background: linear-gradient(135deg, #667eea, #764ba2);
20

21
color: white;
22

23
border: none;
24

25
padding: 14px 28px;
26

27
border-radius: 8px;
28

29
width: 100%;
30

31
font-size: 16px;
32

33
cursor: pointer;
34

35
}
36

37

38

39
.acc-btn:hover {
40

41
transform: translateY(-2px);
42

43
box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
44

45
}
46

47

48

49
.acc-success {
50

51
background: #d4edda;
52

53
border: 1px solid #c3e6cb;
54

55
color: #155724;
56

57
padding: 20px;
58

59
border-radius: 8px;
60

61
text-align: center;
62

63
}
64

65

66

67
.acc-code-display {
68

69
font-family: 'Courier New', monospace;
70

71
font-size: 1.4em;
72

73
font-weight: bold;
74

75
background: #fff;
76

77
padding: 10px 15px;
78

79
border: 2px dashed #28a745;
80

81
border-radius: 6px;
82

83
letter-spacing: 2px;
84

85
}

展开收起

六、部署清单#

步骤	说明
1. 部署后端	Flask API 部署到服务器
2. 配置 CORS	允许前端域名跨域访问
3. 设置密钥	前后端使用相同的 `CLAIM_SECRET`
4. 安装插件	根据博客类型选择对应插件
5. 测试验证	使用不同用户测试领取流程

总结#

博客类型	用户身份来源	使用方式
WordPress	登录用户	`[claim_activation]` 短代码
Typecho	登录用户	`<!--claim-->` 标记
Astro/静态	用户输入邮箱	`<ClaimCode />` 组件

核心安全机制：

HMAC-SHA256 签名验证请求来源
时间戳 防止重放攻击
用户标识 防止重复领取

希望这篇教程对你有所帮助，欢迎评论区讨论！

SollinPlayer更新计划（长期更新）

Wed, 07 Jan 2026 00:00:00 GMT

本文章为长期更新，列出后期的更新计划。

各位有什么意见反馈也可以在本页面留言。

有想对我说的话可以在留言板留言。

安卓端：#

添加在线播放音质选择
同步桌面端备份数据
添加错误码具体信息
添加找回密码功能

iOS端:#

修复navidrome歌曲只能显示200首
添加在线功能的开关
无法支持完整CarPlay (没有开发者账号，仅靠自签名无法实现CarPlay，需要 Apple的授权，目前可以通过 CarPlay 的系统”正在播放”应用控制你的音乐)
同步桌面端备份数据
导入歌单

桌面端：#

修复在播放界面时下一首了歌词不及时跳转到第一句的问题
添加快捷键，支持快速播放暂停下一曲

抖音视频下载工具 - 可以一键下载无水印的收藏、主页、喜欢的所有视频

Mon, 05 Jan 2026 00:00:00 GMT

起因#

这两天在整理项目，突然发现去年上半年开源的一个抖音视频下载工具居然还能继续解析使用，那就贴上仓库地址吧。其实这个项目是给我家里人用的，因为他们喜欢把收藏的一些视频下载下来，放到车机上面去，我一个一个下载太复杂了，就诞生了该项目。 ::aru:shutup:: 声明：本项目所有接口均来源于网络分享，仅可开发学习使用，请下载后24H内删除相关所有代码，勿用于违规违法等场景！如有侵权、联系删除！

仓库地址：抖音视频下载工具Github链接

演示图#

首页.png

下载中心.png

下面是Readme.md。

抖音视频下载工具#

一个基于PyQt5开发的桌面应用程序，支持下载抖音收藏、用户主页和喜欢的视频。

功能特点#

🎯 支持多种下载模式：
- 下载收藏夹中的视频
- 下载用户主页发布的视频
- 下载用户喜欢的视频
📥 批量下载视频，支持断点续传
🎨 现代化深色主题界面
📊 实时显示下载进度
🔄 支持暂停/继续/取消下载
📁 可自定义下载目录
🎮 全局下载任务控制（全部开始/暂停/取消）
💾 支持导出视频链接列表

安装说明#

环境要求#

Python 3.7+
PyQt5
PyQtWebEngine

依赖安装#

Terminal window

1
pip install PyQt5 PyQtWebEngine requests

运行程序#

Terminal window

1
python app.py

使用说明#

启动程序后，选择要使用的功能：
- 下载收藏视频：输入收藏页面URL
- 下载用户主页视频：输入用户ID或主页URL
- 下载喜欢视频：输入用户ID或喜欢页面URL
登录您的抖音账号（如果需要）
点击”提取数据到下载中心”按钮开始抓取视频信息
在下载中心可以：
- 选择下载目录
- 控制单个视频的下载（开始/暂停/取消）
- 使用全局控制按钮管理所有下载任务
- 查看下载进度和状态
- 打开下载目录查看已下载的视频

注意事项#

请确保您有足够的磁盘空间存储视频
下载速度可能受网络条件和抖音服务器限制影响
建议在稳定的网络环境下使用
请遵守抖音的使用条款和版权规定
对于需要用户ID的功能，您可以：
- 直接输入用户ID
- 输入用户主页URL，程序会自动提取用户ID

技术特点#

使用PyQt5构建现代化GUI界面
实现多线程下载，避免界面卡顿
采用深色主题，提供舒适的视觉体验
支持视频信息的本地保存和导出
实现断点续传功能，支持下载任务的暂停和继续
智能URL解析，自动提取用户ID

更新日志#

v1.1.0#

新增用户主页视频下载功能
新增用户喜欢视频下载功能
优化用户界面，添加功能选择按钮
支持用户ID和URL两种输入方式

v1.0.0#

实现基本的视频抓取和下载功能
添加下载管理功能
实现深色主题界面
添加批量任务控制功能
支持自定义下载目录

许可证#

本项目基于MIT许可证开源。

贡献#

欢迎提交Issue和Pull Request来帮助改进这个项目。

FlaskHTTPStudio - 在线webHTTP 请求测试工具（开源）

Sun, 04 Jan 2026 00:00:00 GMT

FlaskHTTPStudio 介绍#

一个功能强大的 HTTP 请求测试工具，支持 cURL 解析、请求编辑、预设规则、历史记录等功能。基于 Flask + 原生 JavaScript 构建，提供现代化的 Web 界面和完善的安全防护。

开源地址#

FlaskHTTPStudio-Github地址欢迎各位Star、Fork。

功能演示#

cURL 解析#

从浏览器开发者工具直接粘贴 cURL 命令，自动解析为可编辑的请求表单。

curl 解析.png

请求编辑器#

支持多种 HTTP 方法、Query 参数、Headers 和 Body 类型的可视化编辑。

请求编辑器.png

预设规则系统#

配置智能预设规则，支持 KV 改值和 JSON Path 深层修改，可按域名和路径过滤作用域。

规则编辑器.png

历史记录与收藏#

自动保存请求历史和响应数据，支持收藏、搜索和一键回放。

历史记录收藏.png

核心特性#

1. cURL 解析#

支持从浏览器开发者工具直接粘贴 cURL 命令（Copy as cURL bash）
自动解析 URL、请求方法、Headers、Query 参数、Body 等
支持多种 cURL 选项：
- -X / --request: HTTP 方法
- -H / --header: 请求头
- -d / --data / --data-raw / --data-binary: 请求体
- --data-urlencode: URL 编码数据
- --json: JSON 数据（自动设置 Content-Type）
- -F / --form: multipart/form-data
- -b / --cookie: Cookies
- -u / --user: Basic 认证
- -x / --proxy: 代理设置
- -k / --insecure: 跳过 SSL 验证
- -L / --location: 跟随重定向
- -m / --max-time: 超时设置
- -G / --get: 强制使用 GET 方法
- -I / --head: HEAD 请求
- --compressed: 压缩传输

2. 请求编辑器#

基础配置#

HTTP 方法: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
URL 编辑: 支持完整 URL 输入
Query 参数:
- 可视化 KV 编辑器（实时同步）
- 文本模式编辑（key=value 格式）
- 双向同步功能
Headers 管理:
- 可视化 KV 编辑器（实时同步）
- 文本模式编辑（Key: Value 格式）
- 双向同步功能

Body 类型支持#

none: 无请求体
json: JSON 格式（支持 JSON Path 预设修改）
form-urlencoded: 表单 URL 编码（key=value 每行一个）
multipart: 文件上传（支持 key=@file 语法）
raw: 原始数据（支持文本或文件上传）

3. 预设规则系统#

强大的参数预设和自动化修改系统，支持：

规则类型#

KV 改值: 修改 Query 参数、Headers 或 Body 中的键值对
JSON Path 改值: 使用路径语法修改 JSON Body 中的深层字段
- 支持点号路径：data.realtime
- 支持数组索引：items[0].id

规则配置#

规则名: 唯一标识符
目标: Query / Headers / Body(kv)
匹配 key/path: 要修改的字段名或 JSON 路径
默认替换值: 预设的默认值
弹窗输入: 应用时是否弹窗让用户输入
作用域过滤:
- 域名匹配（支持包含匹配）
- 路径匹配（支持包含匹配）
启用/禁用: 控制规则是否生效
自动应用: cURL 解析后自动应用该规则

规则管理#

保存/更新规则
编辑现有规则
启用/禁用切换
单独应用规则
批量应用（命中作用域的所有规则）
导出/导入 JSON（规则迁移和备份）
清空全部规则

4. 历史记录与收藏#

自动保存: 每次发送请求自动保存到历史记录（保留响应数据）
收藏功能: 标记重要请求为收藏
搜索过滤: 按 URL、Method、时间搜索
完整快照: 保存请求的所有参数和配置
回放功能:
- 加载历史请求到编辑器
- 直接回放并发送
- 查看保存的响应数据
记录管理:
- 删除单条记录
- 清空全部历史
- 最多保存 80 条历史记录

5. 高级选项#

Timeout: 请求超时时间（1-120 秒）
Redirects: 是否跟随重定向
Verify SSL: SSL 证书验证开关
Proxy: HTTP/HTTPS 代理设置
Basic Auth: HTTP Basic 认证（user 格式）
Cookies: Cookie 字符串（a=1; b=2 格式）

6. 响应查看器#

响应抽屉（移动端友好）#

状态信息: HTTP 状态码、原因短语、最终 URL
性能指标: 请求耗时（毫秒）、响应大小（字节）
Headers 展示: 完整响应头
Body 展示:
- 源码模式（纯文本/JSON 格式化）
- HTML 预览模式（仅 text/html 响应）
- 模式切换按钮
下载功能: 下载完整响应体（支持二进制文件）
截断提示: 超过 2MB 的响应会显示预览截断提示

7. 安全防护#

SSRF 防护（核心安全模块）#

协议限制: 仅允许 http/https 协议
端口白名单: 默认仅允许 80 和 443 端口
内网地址阻断:
- 127.0.0.0/8 (localhost)
- 10.0.0.0/8 (私有网络 A)
- 172.16.0.0/12 (私有网络 B)
- 192.168.0.0/16 (私有网络 C)
- 169.254.0.0/16 (链路本地)
- IPv6 本地地址 (::1, fc00::/7, fe80::/10)
DNS 解析验证: 检查域名解析的所有 IP 地址
重定向二次验证: 跟随重定向后再次验证最终 URL
单标签域名阻断: 禁止无点域名（如 localhost）
.local 域阻断: 禁止 mDNS 域名

其他安全措施#

响应大小限制: 预览限制 2MB，防止内存溢出
上传大小限制: 最大 50MB
临时存储: 响应下载 ID 有效期 5 分钟，最多 100 条
自动清理: 过期下载链接自动清理

8. 数据持久化#

所有数据保存在浏览器 localStorage：

预设规则: httpstudio_presets_v2
历史记录: httpstudio_history_v1
收藏记录: httpstudio_star_v1
服务端不落盘: 所有数据仅在客户端存储

9. 用户界面#

响应式设计#

桌面端: 手风琴面板，支持点击和悬停展开
移动端: 底部操作栏，抽屉式响应查看
自适应布局: 根据屏幕尺寸自动调整

交互特性#

实时同步: KV 编辑器与文本框实时双向同步
Tab 切换: Request / Presets / Advanced 标签页
面板折叠: 手风琴式面板，支持悬停延迟展开（300ms）
快捷操作:
- 一键导出 cURL
- 一键清空表单
- 一键应用预设
- 快速收藏当前请求

视觉反馈#

状态提示: 成功/失败/警告消息
加载状态: 发送中显示加载提示
取消功能: 发送中可点击按钮取消请求
颜色标识:
- 成功响应（绿色）
- 失败响应（红色）
- 提示信息（灰色）

10. 工具功能#

示例填充: 一键填充示例 cURL 命令
导出 cURL: 将当前请求导出为 cURL 命令（复制到剪贴板）
清空表单: 重置所有输入字段
文件上传:
- multipart 模式支持多文件上传
- raw 模式支持单文件作为 Body

技术架构#

后端（Flask）#

框架: Flask 2.3+
HTTP 客户端: requests 2.31+
核心模块:
- curl_parser.py: cURL 命令解析器（支持 shlex 词法分析）
- sender.py: HTTP 请求发送器（支持流式响应）
- response_store.py: 响应临时存储（内存缓存，TTL 5 分钟）
- security.py: SSRF 安全防护模块

前端#

原生 JavaScript: 无框架依赖
现代 CSS: Flexbox/Grid 布局
API 通信: Fetch API + FormData
本地存储: localStorage API
响应式设计: 移动端优先

API 端点#

GET /: 主页面
POST /api/parse_curl: 解析 cURL 命令
POST /api/send: 发送 HTTP 请求
GET /api/download/<download_id>: 下载响应体

安装与运行#

环境要求#

Python 3.8+
pip

安装步骤#

克隆项目

Terminal window

1
git clone https://github.com/Ryderwe/FlaskHTTPStudio.git
2
cd FlaskHTTPStudio

安装依赖

Terminal window

1
pip install -r requirements.txt

运行应用

Terminal window

1
python app.py

访问应用

1
http://127.0.0.1:5000

生产部署建议#

使用 gunicorn 或 uwsgi 作为 WSGI 服务器
配置 Nginx 反向代理
启用 HTTPS
设置适当的防火墙规则
考虑添加身份认证

使用场景#

1. API 调试#

从浏览器开发者工具复制 cURL 命令，快速重放和修改请求。

2. 接口测试#

使用预设规则批量修改参数，测试不同场景。

3. 参数化测试#

配置 JSON Path 预设，快速修改深层 JSON 字段。

4. 请求收藏#

保存常用 API 请求，支持快速回放。

5. 团队协作#

导出预设规则 JSON，分享给团队成员。

使用示例#

示例 1: 解析 cURL 并发送#

从浏览器开发者工具复制 cURL (bash)
粘贴到 “cURL (bash) 解析” 面板
点击 “解析 → 编辑器”
自动填充所有字段并应用预设规则
点击 “发送” 查看响应

示例 2: 创建预设规则#

切换到 “Presets” 标签
配置规则：
- 规则名: update_timestamp
- 类型: JSON Path 改值
- 目标: Body(kv)
- 匹配 path: data.timestamp
- 默认值: 2024-01-01T00:00:00Z
- 作用域域名: api.example.com
- 启用: true
- 自动应用: true
点击 “保存/更新”
下次解析包含该域名的请求时自动应用

示例 3: 文件上传#

选择 Body 类型为 multipart
在 Body 文本框输入：
```
1
file=@upload
2
description=测试文件
```
在自动生成的文件选择器中选择文件
点击发送

安全注意事项#

默认安全策略#

禁止访问内网: 所有内网地址被阻断
端口限制: 仅允许 80 和 443 端口
重定向验证: 防止通过重定向绕过安全检查

自定义安全策略#

如需访问特定内网服务或非标准端口，需修改 core/security.py:

1
# 允许其他端口
2
DEFAULT_ALLOWED_PORTS = {80, 443, 8080, 3000}
3

4
# 或在调用时传入
5
validate_public_url(url, allowed_ports={80, 443, 8080})

生产环境建议#

部署在隔离网络环境
添加身份认证和授权
配置请求速率限制
启用访问日志审计
定期更新依赖包

项目结构#

1
FlaskHTTPStudio/
2
├── app.py                 # Flask 应用主文件
3
├── requirements.txt       # Python 依赖
4
├── core/                  # 核心模块
5
│   ├── __init__.py
6
│   ├── curl_parser.py     # cURL 解析器
7
│   ├── sender.py          # HTTP 请求发送器
8
│   ├── response_store.py  # 响应临时存储
9
│   └── security.py        # SSRF 安全防护
10
├── templates/             # HTML 模板
11
│   └── index.html         # 主页面
12
└── static/                # 静态资源
13
    ├── app.css            # 样式文件
14
    └── app.js             # JavaScript 逻辑

开发计划#

已实现功能#

✅ cURL 命令解析
✅ 多种 Body 类型支持
✅ 预设规则系统
✅ JSON Path 修改
✅ 历史记录和收藏
✅ 响应查看和下载
✅ SSRF 安全防护
✅ 移动端适配
✅ 导入/导出功能

未来计划#

⏳ WebSocket 支持
⏳ GraphQL 请求支持
⏳ 环境变量管理
⏳ 请求链（Chain Requests）
⏳ 批量请求测试
⏳ 性能测试（压测）
⏳ Mock 服务器
⏳ API 文档生成

常见问题#

Q: 为什么无法访问 localhost？#

A: 出于安全考虑，默认禁止访问所有内网地址。如需访问本地服务，请修改 core/security.py 中的安全策略。

Q: 响应被截断了怎么办？#

A: 超过 2MB 的响应会被截断预览。可以使用下载按钮获取完整内容，或修改 core/sender.py 中的 MAX_PREVIEW_BYTES 常量。

Q: 历史记录保存在哪里？#

A: 所有数据保存在浏览器的 localStorage 中，服务端不存储任何数据。清除浏览器数据会导致历史记录丢失。

Q: 如何备份预设规则？#

A: 在 Presets 标签页点击 “导出 JSON”，将规则复制保存。需要恢复时点击 “导入 JSON” 粘贴即可。

Q: 支持哪些 cURL 选项？#

A: 支持大部分常用选项，详见 “核心特性 - cURL 解析” 部分。不支持的选项会被忽略。

iOS 版 SollinPlayer 已发布！

Sat, 03 Jan 2026 00:00:00 GMT

折腾了一个多月，终于把这个 iOS 音乐播放器搞出来了#

最近终于把手上这个音乐播放器项目收尾了，从最开始的想法到现在能用，前前后后折腾了好几个月。趁着还有印象，写篇文章记录一下。

为什么要做这个？#

说实话，App Store 上的音乐 App 已经够多了。但用了一圈下来，总觉得差点意思：

想听网易云的歌？得装网易云
想听 QQ 音乐？得再装一个
家里 NAS 上存了一堆无损？还得再找个支持 WebDAV 的
更别提有些歌这个平台有那个平台没有…

所以就想着，能不能做一个”全都要”的播放器？本地、在线、NAS 全支持，而且界面得好看。

先看效果#

主界面#

底部是常驻的迷你播放器，点一下就能展开完整播放界面。资料库这边可以按歌曲、专辑、艺术家来浏览，用起来和系统音乐 App 差不多的逻辑。

播放界面#

播放界面花了不少心思。背景会自动取当前歌曲封面做模糊，看起来比纯黑舒服多了。左右滑动可以切换队列、封面、歌词三个页面。

歌词同步#

IMG_3319.PNG

歌词这块支持 LRC 格式的逐行同步，当前播放的那句会高亮显示。双击某一句可以直接跳到那个时间点播放，还挺方便的。

有些歌词时间不太准，可以单独给每首歌设置偏移量，调一次下次就记住了。

在线搜索#

IMG_3336.PNG

搜索这块接了网易云、QQ音乐、酷我几个平台的接口。搜到的歌可以直接播放，也可以批量选中加到歌单里。

音质可以选 128k、320k 或者无损，在设置里改就行。

WebDAV 播放#

IMG_3325.PNG

这个是我自己用得最多的功能。家里群晖上存了不少无损，配置好 WebDAV 地址和账号密码就能直接播放。

播放的时候是边播边缓存的，不用等整首歌下载完才能听。而且音频的封面、歌手这些元数据都能正常识别。

主题切换#

IMG_3322.PNG

内置了几套主题，除了经典的 iOS 风格，还有个新拟态风格和一个粉粉的可爱风格。粉粉主题还能把封面换成磁带的样式，挺有意思的。

播放界面的背景也可以自定义，除了封面模糊，还能选纯色、渐变，或者干脆自己传张图。

均衡器#

加了个 10 段均衡器，内置了摇滚、流行、古典这些常用预设。喜欢折腾的也可以自己调。不过因为技术限制，均衡器只对本地文件有效，在线播放用不了。

歌单管理#

歌单分本地和在线两种，本地歌单只能加本地歌，在线歌单只能加在线歌，这样播放的时候不会乱。

支持多选批量添加、滑动删除、批量删除这些操作，管理起来挺顺手的。

一些技术细节#

整个项目是纯 SwiftUI 写的，最低支持 iOS 16。

播放核心用的 AVFoundation，均衡器那块用了 AVAudioEngine 做实时处理。WebDAV 流式播放踩了不少坑，最后用 AVURLAsset 配合自定义的资源加载器才搞定。

数据存储没用 Core Data，直接 UserDefaults 加 JSON 文件，简单够用。

还想做的#

目前能想到的还有这些：

CarPlay 支持
Apple Watch App
歌词翻译显示
更多在线音乐源
iPad 适配

最后#

这个项目断断续续做了挺久，中间重构过好几次。现在总算是能拿出来见人了，虽然还有不少可以改进的地方，但基本功能都齐了。

最后更新：2026年1月

SollinPlayer 激活码兑换领取（暂停领取）

Fri, 02 Jan 2026 00:00:00 GMT

虽然入不敷出，但本软件依旧永不收费！为爱发电！

也可以对作者进行打赏哦（会更有开发动力的！）｜点我去打赏！

TG 群聊：SollinPlayer 交流群 QQ 群聊：SollinPlayer qq群-853534298

领取入口#

领取步骤：加群（QQ或tg） -> 评论区留言(在网站的评论区，不是群里面发消息！) -> 输入评论区留的邮箱领取
iOS 激活码领取：面向ipa 自签 ios 版本用户。
安卓下载兑换码领取：适用于安卓包下载兑换码获取。

操作步骤#

先确认自己需要的客户端平台，再点击对应入口。
按页面提示填写必要信息（为防止盗刷，请先评论区留言后再领取兑换码、激活码）。
领取后立刻备份激活码或兑换码，避免刷新页面后丢失。
完成兑换后在当前页面留言反馈异常，方便追踪。

注意事项#

激活码与兑换码具有时效性，超过页面注明的截止时间可能失效。
每位用户仅限领取一次，重复提交会被系统自动过滤。
勿在公开渠道分享自己的兑换码或账号截图，以免被他人盗用。
若遇到验证码或下载链接失效，可在留言区附上截图，我们会集中处理。

保持页面收藏，后续活动或补发也会在这里第一时间更新。

月明星稀

Swift：iOS 控制中心媒体播放状态与软件内不同步的解决办法和排查思路

iOS 控制中心媒体播放状态与软件内不同步的解决办法&排查思路：AVAudioEngine 暂停只关 playerNode 的坑#

先说最终结论#

1. 现象和复现条件#

2. 第一轮：怀疑 nowPlayingInfo / playbackState 的写入顺序#

3. 第二轮：怀疑 playCommand / pauseCommand 的可用性开关#

4. 第三轮：先证明，再改#

5. 定位到关键点：AVAudioEngine 还在 running#

6. 修复：暂停时同步 pause 整个 engine#

7. 三轮修改的价值分布#

8. 经验总结#

附：最终 diff（节选）#

Flutter/iOS 后台自动切歌与通知栏手动“下一首”稳定实现方法

Flutter/iOS 后台自动切歌与通知栏“下一首”稳定实现方法#

先说最终结论#

1. 问题现象：看起来像“偶发失灵”，本质是多条状态链路抢写#

1.1 自动切歌偶发不触发#

1.2 通知栏/锁屏点下一首偶发没反应#

1.3 声音切过去了，但元数据还是旧的#

1.4 日志多数正确，但体验依然错#

2. 第一轮误判：以为只是“切歌函数写得不够严谨”#

3. 第二轮误判：加了 token，为什么还会被旧状态拉回去？#

4. 真正根因：不是一个 race，而是四条链路在竞争#

5. 最终方案：把所有入口统一收口到一条主链路#

6. 先解决自动切歌：完成事件只负责转发，不直接切 source#

7. 再解决通知栏/锁屏 next：原生只桥接，Flutter 统一处理#

7.1 Swift 侧不写业务逻辑，只桥接命令#

7.2 Flutter 里的媒体按钮也统一走 skip 方法#

8. 真正的核心：在线切歌状态机必须同时解决 3 件事#

8.1 skipToNext：切歌中不忽略，而是入队#

9. playAtIndex：这才是整个系统真正的中心#

10. iOS 后台最关键的坑：缓存切歌时，不要等 play() Future 返回#

11. 只修切歌还不够：在线播放列表启动流程也要防“晚到回写”#

12. 通知栏为什么会显示错歌？因为系统的 queueIndex 未必可信#

12.1 queueIndex 优先使用自己维护的 _currentIndex#

12.2 切歌成功后主动推送新的 mediaItem#

13. 一个容易忽略的细节：idle 不一定应该映射成系统 idle#

14. 复测时我主要盯哪些日志#

15. 本方法要点#

15.1 自动切歌最终调用 skipToNext()#

15.2 在线切歌增加这四个状态字段#

15.3 切歌中不要简单 return，要记录 queued target#

15.4 如果有在线播放列表初始化流程，也必须带 session token#

15.5 iOS 后台缓存切歌时，不要等 await player.play()#

15.6 queueIndex 优先用自己维护的业务索引#

16. 小结#

我的音乐App-SollinPlayer，被Apple审核员判“涉黄”了

记一次离谱的App Store审核：纯音乐App被判定涉黄#

[LiveContainer] IOS无限制安装应用教程

前言#

第一步：下载沙漏#

第二步：开启开发者模式#

第三步：下载iloader#

第四步：登录id后安装软件#

第五步：安装过程#

第六步：使用说明#

注意事项（自动续签说明）#

虚拟定位#

Android/Flyme 通知栏“暂停后继续播放无响应”技术复盘：根因、关键代码与最终稳定方案

Android/Flyme 通知栏“暂停后继续播放无响应”技术复盘：根因、关键代码与最终稳定方案#

1. 问题现象与复现#

2. 第一阶段：先清表层问题#

2.1 去掉 stop 按钮，固定 3 个控制位#

2.2 click() 不再依赖 playbackState.playing#

2.3 onNotificationDeleted() 不再 stop#

3. 第二阶段：建立可观测性（先证明再改）#

4. 真正根因：await _player.play() 语义误用#

4.1 旧写法（有风险）#

4.2 日志证据#

5. 核心修复：改成“快速派发 + 异步观察”#

5.1 新增派发器 _dispatchPlayerPlay#

5.2 play() 改造#

6. Flyme 兼容层：把所有入口收敛到同一恢复链路#

索引自愈#

7. 最终稳定点：Android 中间键改成单一 playPause#

8. 最终验证（B14）#

9. 经验总结（面向工程）#

播放页默认封面切换闪烁（技术细节版）：从资源猜测到动画结构稳定性的完整修复

播放页默认封面切换闪烁（技术细节版）：从资源猜测到动画结构稳定性的完整修复#

10. iOS 后台最关键的坑：缓存切歌时，不要等 `play()` Future 返回#

12.1 queueIndex 优先使用自己维护的 `_currentIndex`#

15.1 自动切歌最终调用 `skipToNext()`#

15.5 iOS 后台缓存切歌时，不要等 `await player.play()`#

15.6 `queueIndex` 优先用自己维护的业务索引#

4. 真正根因：`await _player.play()` 语义误用#

5.1 新增派发器 `_dispatchPlayerPlay`#

5.2 `play()` 改造#

7. 最终稳定点：Android 中间键改成单一 `playPause`#

5.2 统一封面渲染链路：`ArtworkWidget` 增加强制默认图开关#

3）iOS 缓存切歌：不再阻塞等待 `play()` Future 完成#

4）UI 层收口：统一从 `playbackState` 读当前歌曲#

E. 播放页统一从 `playbackState` 读当前歌曲#

重装后收藏/喜欢歌曲不见了：一次「ID 稳定性 + 数据迁移」的修复记录