#650·MusicFree

[Feature Request] 建议移动端插件沙箱对齐桌面端规范，支持 musicfree/storage 本地持久化存储

Author: mengkuikunCreated Sep 3, 2026Updated Sep 7, 2026

Labelsfeature

提需求之前，请先确认

已经阅读过Q&A (https://musicfree.catcat.work/qa/mobile.html)
新需求不是仅仅满足个人口味的需求
新需求不与其他已有issue重复
我可以在代码、测试上提供帮助

需求描述

1. 当前存在的痛点是什么？

多端 API 规范不一致：在 MusicFree 桌面端（MusicFreeDesktop）中，猫头猫大佬已经在插件沙箱中封装并提供了官方的 require("musicfree/storage") 模块（底层持久化写入本地磁盘文件），使得插件可以自由存储配置、状态及本地缓存数据；
移动端缺失持久化能力：但在移动端（React Native 架构）中，插件沙箱的 packages 白名单列表里遗漏了 musicfree/storage。同时，移动端沙箱也不存在 Web 标准的 localStorage 或 IndexedDB；
退出重启数据丢失与重复耗流：导致插件在移动端运行时，所有动态数据、解析缓存都只能停留在 JavaScript 运行内存（RAM）中。手机一旦被系统杀后台或重新启动，数据全部蒸发，冷启动时不得不再次消耗手机流量重新联网拉取，且在弱网、飞行模式或无信号的离线环境下完全无法使用。

2. 希望如何解决这个问题？

建议移动端与桌面端保持规范统一，在移动端插件沙箱中同样注入 musicfree/storage 模块，提供一致的异步持久化 API（getItem, setItem, removeItem）。

由于移动端宿主工程底层已经引入了高性能的腾讯 MMKV（getOrCreateMMKV），实现起来非常轻量，仅需在移动端宿主源码中增加几行代码即可为插件开放底层的物理持久化支持。

3. 预期的使用体验是怎样的？

插件开发者只需要遵循一套官方规范：

javascript

const storage = require("musicfree/storage");
await storage.setItem(key, value);
const val = await storage.getItem(key);

附件信息（可选）

markdown

### 参考技术实现（供作者快速参考）：

在移动端源码文件 `src/core/pluginManager/plugin.ts` 中，可直接复用工程内置的 MMKV 单例实现：

```typescript
// 1. 引入移动端既有的 MMKV 工具函数
import getOrCreateMMKV from "@/utils/getOrCreateMMKV";

// 2. 创建插件专属持久化 MMKV 实例
const pluginStorageMMKV = getOrCreateMMKV("plugin.storage");

const mobilePluginStorage = {
    getItem: async (key: string): Promise<string | null> => {
        return pluginStorageMMKV.getString(key) ?? null;
    },
    setItem: async (key: string, val: string): Promise<void> => {
        pluginStorageMMKV.set(key, String(val));
    },
    removeItem: async (key: string): Promise<void> => {
        pluginStorageMMKV.delete(key);
    },
};

// 3. 在 packages 映射对象中暴露该模块：
const packages: Record<string, any> = {
    cheerio,
    "crypto-js": CryptoJs,
    axios,
    dayjs,
    "big-integer": bigInt,
    qs,
    he,
    "@react-native-cookies/cookies": deprecatedCookieManager,
    webdav,
    "musicfree/storage": mobilePluginStorage, // <-- 对齐桌面端插件持久化规范
};

Source: maotoumao/MusicFree

View original on GitHub View discussion on GitHub