maotoumao/MusicFree · warning

无法识别此插件

Error message

无法识别此插件

What it means

This is the fallback message shown when installing a plugin from a local .js file via a deep link fails and the thrown error has no usable `message`. `PluginManager.installPluginFromLocalFile` rejects when the file cannot be read, evaluated, or validated as a plugin, and handleLinkingUrl surfaces `e?.message ?? "无法识别此插件"` as a warning toast. It means the file the OS handed the app was not recognized as a valid MusicFree plugin.

Source

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

                    ),
                );
                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 { }
    }

    // 开启监听
    Linking.addEventListener("url", data => {
        if (data.url) {
            handleLinkingUrl(data.url);

View on GitHub (pinned to d118b18b3d)

Solutions

1. Re-download/re-share the plugin .js file and confirm it fully exists and is non-empty before opening it with the app.
2. Open the .js in an editor or run it in Node to verify it parses and exports a valid plugin object (srcUrl, platform, etc.).
3. Enable/verify the plugin-version check bypass setting (`basic.notCheckPluginVersion`) if the plugin targets a different plugin API version.
4. Update the plugin to a version compatible with the installed app version.
5. Check console.log output (the handler logs the caught error) for the underlying read/eval error to pinpoint the cause.

Example fix

// before: opening a partially downloaded file
Linking.openURL('file:///storage/emulated/0/Download/plugin.js'); // still 0 bytes

// after: verify the file first
const stat = await RNFS.stat('/storage/emulated/0/Download/plugin.js');
if (stat.isFile() && stat.size > 0) {
    Linking.openURL('file:///storage/emulated/0/Download/plugin.js');
}

import { installPluginFromLocalFile } from '@/core/pluginManager';

async function canInstallLocalPlugin(path: string) {
    return path.endsWith('.js') && path.length > 3;
}

if (!(await canInstallLocalPlugin(url))) {
    Toast.warn('不是有效的插件文件');
    return;
}
await installPluginFromLocalFile(url)
    .then(res => res.success
        ? Toast.success(`插件「${res.pluginName}」安装成功~`)
        : Toast.warn('安装失败: ' + res.message))
    .catch(e => Toast.warn(e?.message ?? '无法识别此插件'));

function isPluginError(e: unknown): e is { message?: string } {
    return typeof e === 'object' && e !== null && ('message' in e);
}

try {
    const res = await PluginManager.installPluginFromLocalFile(url);
    if (!res.success) throw new Error(res.message);
    Toast.success(`插件「${res.pluginName}」安装成功~`);
} catch (e) {
    console.log(e);
    Toast.warn(e?.message ?? '无法识别此插件');
}

When it happens

Trigger: Opening a `file://.../*.js` deep link or share intent where the local plugin file is missing, unreadable, empty, contains a syntax error, or does not export the plugin contract (e.g. missing `_path`/`srcUrl`/required hooks); also when plugin version checks fail and the loader throws instead of resolving with {success:false}.

Common situations: User taps a plugin file in a file manager before download completes; the shared file URI points to a cache location the app cannot read after reboot; the plugin author published a broken or minified-incompatible .js; plugin was built for a newer plugin-API version than the app supports.

Related errors

• toast.failToImportMusic
• toast.failToImportSheet
• 搜索结果为空
• mediakey不完整
• 安装失败: ${res.message}

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