Cordova Android从13.0.0迁移至14.0.1后deviceready触发时LocalFileSystem未定义问题排查

DevOps 小满

2026-4-7

嗨，我之前升级cordova-android到14.0.1的时候也碰到过几乎一模一样的问题，给你梳理几个靠谱的排查方向，应该能解决LocalFileSystem未定义的问题：

检查cordova-file-plugin的版本兼容性：cordova-android@14.0.1对插件的兼容性要求有更新，旧版本的cordova-plugin-file可能不支持这个版本的核心库。你可以先执行cordova plugin remove cordova-plugin-file，然后重新安装最新稳定版：cordova plugin add cordova-plugin-file@latest。安装完成后记得清理一下构建缓存——直接删除platforms/android和plugins目录，再重新执行cordova prepare android，之后再构建测试。
确认LocalFileSystem的访问方式是否变更：部分插件在适配高版本cordova-android时，会调整全局变量的导出策略，不再把LocalFileSystem直接挂载到window对象上。你可以试试把代码里直接访问LocalFileSystem.PERSISTENT的地方，改成cordova.plugins.file.LocalFileSystem.PERSISTENT，看看是否能正常获取到。如果这个有效，说明插件的变量导出方式变了，需要统一通过cordova.plugins.file命名空间来访问相关API。
验证存储权限与构建配置：Android 14（对应cordova-android14）对存储权限的管控更严格，你需要确保config.xml里已经配置了必要的权限：
```
<platform name="android">
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" tools:ignore="ScopedStorage" />
</platform>
```
另外，如果你的应用还没适配Scoped Storage，可以临时添加<preference name="AndroidInsecureFileModeEnabled" value="true" />到config.xml的Android平台配置里（当然长期来看还是建议适配Scoped Storage）。最后别忘了执行cordova clean android清理构建缓存后再重新打包。
排查插件冲突问题：有些第三方插件可能和cordova-plugin-file存在初始化冲突，导致file插件的全局变量无法正常注册。你可以先暂时移除所有非必要的插件，只保留cordova-plugin-file和cordova核心插件，然后测试应用是否还会出现LocalFileSystem未定义的问题。如果问题消失，再逐个重新添加插件，找到引发冲突的那个插件后，要么升级该插件版本，要么寻找替代方案。

我当时是升级了cordova-plugin-file的版本就解决了这个问题，你可以按照上面的顺序排查，应该很快就能搞定！

内容来源于stack exchange