{"record":{"id":"9bed94fc1e09cd2b","repo":"maotoumao/MusicFree","slug":"error-9bed94","errorCode":null,"errorMessage":"状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限","messagePattern":"状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/native/lyricUtil/index.ts","lineNumber":59,"sourceCode":"    /** 检查权限 */\n    checkSystemAlertPermission: () => Promise<boolean>;\n    /** 请求悬浮窗 */\n    requestSystemAlertPermission: () => Promise<boolean>;\n}\n\nconst LyricUtil: ILyricUtil = NativeModules.LyricUtil;\n\nconst originalShowStatusBarLyric = LyricUtil.showStatusBarLyric;\n\nconst showStatusBarLyric: ILyricUtil[\"showStatusBarLyric\"] = async (\n    initLyric,\n    config,\n) => {\n    try {\n        await originalShowStatusBarLyric(initLyric, config);\n    } catch (e) {\n        errorLog(\"状态栏歌词开启失败\", e);\n        Toast.warn(\"状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限\");\n        Config.setConfig(\"lyric.showStatusBarLyric\", false);\n    }\n};\n\nLyricUtil.showStatusBarLyric = showStatusBarLyric;\n\nexport default LyricUtil;\n","sourceCodeStart":41,"sourceCodeEnd":67,"githubUrl":"https://github.com/maotoumao/MusicFree/blob/d118b18b3d0c904400f7eea7bf99c0ceec6c1aee/src/native/lyricUtil/index.ts#L41-L67","documentation":"showStatusBarLyric in src/native/lyricUtil/index.ts wraps the native call: when originalShowStatusBarLyric rejects, it logs, shows a warning toast telling the user to enable the floating-window (悬浮窗) permission in system settings, and auto-disables lyric.showStatusBarLyric in config. The thrown native error is about Android's overlay permission being missing.","triggerScenarios":"Calling LyricUtil.showStatusBarLyric while the app lacks SYSTEM_ALERT_WINDOW / floating window permission on Android, so the native module rejects when trying to draw the status-bar lyric view.","commonSituations":"Fresh install where the user never granted 'display over other apps'; OEM ROMs (MIUI, EMUI) revoking overlay permission after updates; permission denied per-app in system settings; running on devices where the lyric service requires extra permission.","solutions":["Guide the user to Settings → Apps → this app → 'Display over other apps' and enable it, then re-enable status bar lyric.","Before calling, check/request overlay permission via the native module (e.g. checkPermission + jumpToSettings) instead of relying on the failure toast.","Note the config already auto-reverts (lyric.showStatusBarLyric=false); re-enable it after granting permission."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const hasOverlay = await LyricUtil.checkPermission?.();\nif (!hasOverlay) {\n  LyricUtil.jumpToPermissionSettings?.();\n  return; // don't attempt until granted\n}","typeGuard":null,"tryCatchPattern":"try {\n  await LyricUtil.showStatusBarLyric(lyric, config);\n} catch (e) {\n  Config.setConfig('lyric.showStatusBarLyric', false);\n  Toast.warn(t('lyric.overlayPermissionRequired'));\n}","preventionTips":["Check/request SYSTEM_ALERT_WINDOW permission before enabling status bar lyric.","Provide a settings shortcut that opens the app's overlay permission page.","Remember the permission may be revoked by OEM ROMs after updates — re-check on app start.","Keep the auto-disable behavior so the app doesn't repeatedly fail."],"tags":["android","permission","native-module","lyric","overlay"],"backgroundTag":"missing-overlay-permission","analyzedSha":"d118b18b3d0c904400f7eea7bf99c0ceec6c1aee","analyzedAt":"2026-08-30T11:49:12.932Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}