What causes "安装失败: ${res.message}" in maotoumao/MusicFree?

Read the res.message in the toast — it names the installer's failure (network, invalid code, etc.) and fix that specific cause.

maotoumao/MusicFree · warning

安装失败: ${res.message}

Error message

安装失败: ${res.message}

What it means

handleLinkingUrl in src/entry/bootstrap/bootstrap.ts installs a plugin from a deep-link/URL; the install promise resolves with {success, pluginName, message}. When success is false the code toasts `安装失败: ${res.message}` ("install failed"). The thrown-looking message is a user-facing toast carrying the installer's failure reason.

Source

Thrown at src/entry/bootstrap/bootstrap.ts:250

                    .split(",")
                    .map(decodeURIComponent);
                await Promise.all(
                    plugins.map(it =>
                        PluginManager.installPluginFromUrl(it).catch(emptyFunction),
                    ),
                );
                Toast.success("安装成功~");
            } else if (url.endsWith(".js")) {
                PluginManager.installPluginFromLocalFile(url, {
                    notCheckVersion: Config.getConfig(
                        "basic.notCheckPluginVersion",
                    ),
                })
                    .then(res => {
                        if (res.success) {
                            Toast.success(`插件「${res.pluginName}」安装成功~`);
                        } else {
                            Toast.warn("安装失败: " + res.message);
                        }
                    })
                    .catch(e => {
                        console.log(e);
                        Toast.warn(e?.message ?? "无法识别此插件");
                    });
            } else if (supportLocalMediaType.some(it => url.endsWith(it))) {
                // 本地播放
                const musicItem = await PluginManager.getByHash(
                    localPluginHash,
                )?.instance?.importMusicItem?.(url);
                console.log(musicItem);
                if (musicItem) {
                    TrackPlayer.play(musicItem);
                }
            }
        } catch { }
    }

View on GitHub (pinned to d118b18b3d)

Solutions

Read the res.message in the toast — it names the installer's failure (network, invalid code, etc.) and fix that specific cause.
Open the plugin URL in a browser to confirm it serves raw JS, not an HTML page or 404.
Retry on a different network / without proxy; GitHub raw links are often blocked in some regions.
Install the plugin by re-sharing a valid link or from the plugin marketplace instead of the deep link.

Defensive patterns

Strategy: try-catch

Validate before calling

const resp = await fetch(pluginUrl, { method: 'HEAD' });
const ct = resp.headers.get('content-type') ?? '';
if (!resp.ok || ct.includes('text/html')) throw new Error('URL 不是有效的插件文件');

Type guard

function isInstallResult(r: unknown): r is { success: boolean; pluginName?: string; message?: string } {
  return !!r && typeof (r as any).success === 'boolean';
}

Try / catch

installPluginFromUrl(url)
  .then(res => res.success
    ? Toast.success(`插件「${res.pluginName}」安装成功~`)
    : Toast.warn('安装失败: ' + res.message))
  .catch(e => Toast.warn(e?.message ?? '无法识别此插件'));

Prevention

Verify the link serves raw JS (not an HTML page) before installing.
Prefer marketplace/official sources over hand-copied deep links.
Retry on another network if GitHub raw/CDN hosts are blocked in your region.
Surface res.message clearly so the user knows whether it's network or content failure.

When it happens

Trigger: Opening a musicfree:// (or similar) plugin install link where the downloader reports failure: URL unreachable, response is not valid JS/plugin code, hash mismatch, plugin storage error, or the target host refuses the request.

Common situations: Sharing plugin links whose host is down or behind a firewall/CDN block; link pointing to an HTML error page instead of plugin JS; expired GitHub release/raw links; network proxy interfering; plugin source requires headers the installer doesn't send.

Related errors

AI-assisted analysis of maotoumao/MusicFree@d118b18b3d (2026-08-30). Data as JSON: /api/errors/defba24ae5012201. Report an issue: GitHub.