告别Android 14存储权限崩溃：LitePal数据库适配全攻略

Android 14（API 34）引入的存储权限变更和作用域存储强化，让许多基于SQLite的应用面临数据库读写失败问题。作为轻量级ORM框架，LitePal通过灵活的配置选项和存储路径管理，可帮助开发者平滑过渡到新权限体系。本文将从权限声明、存储路径迁移、适配代码实现三个维度，提供完整的Android 14兼容方案。

一、Android 14存储权限痛点解析

Android 14对外部存储访问实施更严格的限制：

• 取消WRITE_EXTERNAL_STORAGE权限，默认禁止应用写入非应用私有目录
• 外部存储根目录（如/sdcard/）写入需通过SAF（存储访问框架）申请
• 应用私有目录（/data/data/<package>/）访问无需权限，但需适配作用域存储路径规则

LitePal默认配置下，当litepal.xml中storage设为external时，数据库文件存储在getExternalFilesDir("") + "/databases/"目录。该路径在Android 14中虽仍属应用私有外部存储（无需权限），但需注意：

// Connector.java中外部存储路径构建逻辑
if ("external".equalsIgnoreCase(litePalAttr.getStorage())) {
    dbName = LitePalApplication.getContext().getExternalFilesDir("") + "/databases/" + dbName;
}

二、权限声明与配置适配

2.1 最小权限清单配置

在AndroidManifest.xml中移除废弃权限，添加必要声明：

<!-- 移除WRITE_EXTERNAL_STORAGE -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<!-- 添加Android 13+媒体权限（如需访问相册等） -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

2.2 LitePal存储模式选择

通过litepal.xml配置存储路径，推荐三种适配方案：

存储模式	配置值	路径示例	权限要求	适用场景
内部存储	internal	/data/data/com.example.app/databases/	无	数据隐私性高，无需迁移
应用私有外部存储	external	/Android/data/com.example.app/files/databases/	无	需较大存储空间，兼容旧版本
自定义外部路径	custom/path	/sdcard/custom/path/	SAF权限申请	需共享数据库文件

推荐配置（兼容Android 14且无需权限）：

<!-- sample/src/main/assets/litepal.xml -->
<storage value="external" />

三、数据库路径迁移实现

若原应用使用自定义外部路径（如/sdcard/MyApp/db/），需迁移至应用私有目录，迁移流程如下：

3.1 路径检测与迁移触发

// 在Application onCreate中执行
private void migrateDatabaseIfNeeded() {
    LitePalAttr attr = LitePalAttr.getInstance();
    if ("old/custom/path".equals(attr.getStorage())) {
        // 1. 获取旧路径数据库
        String oldPath = Environment.getExternalStorageDirectory() + "/old/custom/path/dbname.db";
        // 2. 获取新路径 [Connector.java逻辑]
        String newPath = LitePalApplication.getContext().getExternalFilesDir("") + "/databases/dbname.db";
        // 3. 执行文件复制
        FileUtils.copyFile(oldPath, newPath);
        // 4. 更新配置为external模式
        updateLitePalStorageConfig("external");
    }
}

3.2 配置更新工具类

通过反射更新LitePal运行时配置（需谨慎使用）：

public class LitePalConfigUpdater {
    public static void updateStorage(String storageType) {
        try {
            LitePalAttr attr = LitePalAttr.getInstance();
            Field storageField = LitePalAttr.class.getDeclaredField("storage");
            storageField.setAccessible(true);
            storageField.set(attr, storageType);
            // 重置数据库连接 [Connector.java#L109]
            Connector.clearLitePalOpenHelperInstance();
        } catch (Exception e) {
            LitePalLog.e("Config update failed", e);
        }
    }
}

四、运行时权限动态申请（如需）

若确需访问公共目录，需通过SAF框架申请权限：

// 启动SAF文件选择器
Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);
startActivityForResult(intent, 1001);

// 处理权限回调
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == 1001 && resultCode == RESULT_OK) {
        Uri uri = data.getData();
        getContentResolver().takePersistableUriPermission(uri, 
            Intent.FLAG_GRANT_READ_URI_PERMISSION | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
        // 使用DocumentFile操作数据库文件
        DocumentFile dbFile = DocumentFile.fromTreeUri(this, uri).createFile("application/x-sqlite3", "mydb.db");
    }
}

五、完整适配代码示例

5.1 Application初始化

public class MyApplication extends LitePalApplication {
    @Override
    public void onCreate() {
        super.onCreate();
        // 初始化LitePal [LitePalApplication.java#L38]
        LitePal.initialize(this);
        // 检查并迁移数据库
        migrateDatabaseIfNeeded();
    }
    
    // 迁移逻辑实现...
}

5.2 配置文件最佳实践

<!-- 推荐的Android 14适配配置 [sample/src/main/assets/litepal.xml] -->
<litepal>
    <dbname value="myapp.db" />
    <version value="2" />
    <storage value="external" /> <!-- 应用私有外部存储 -->
    <list>
        <mapping class="org.litepal.litepalsample.model.Album" />
        <mapping class="org.litepal.litepalsample.model.Song" />
    </list>
</litepal>

六、兼容性测试矩阵

Android版本	存储模式	测试要点
Android 14	internal	数据库创建/升级/查询
Android 14	external	卸载应用后数据是否保留
Android 13	external	旧路径访问权限检查
Android 10	custom	作用域存储适配性

通过adb shell am set-debug-app -w com.example.app命令可模拟不同API级别下的存储行为。

七、总结与注意事项

1. 优先使用应用私有存储：internal或external模式可避免所有权限问题
2. 配置变更需谨慎：修改litepal.xml后需测试数据库升级逻辑
3. 监控存储状态：通过Environment.getExternalStorageState()检查外部存储可用性
4. 日志调试：开启LitePal日志查看路径构建过程 [LitePalLog.java]

通过上述方案，LitePal应用可在Android 14上实现零权限数据库操作，同时保持与旧版本兼容。完整示例代码可参考sample模块中的Album和Song数据模型实现。