Ionic 5中使用File Transfer无法从URL下载PDF文件问题求助

云原生阿岚

2026-10-6

问题原因排查

插件版本不匹配或安装不全：Ionic 5对依赖包版本要求严格，若仅安装了npm包未安装对应cordova原生插件，或是@ionic-native/file、@ionic-native/file-transfer版本高于5.x，都会出现功能调用失败的问题。
平台权限缺失：Android 10及以上版本访问externalDataDirectory需要申请读写存储权限，iOS需要在Info.plist配置网络访问白名单和文件存储权限，否则请求会被系统直接拦截。
证书校验失败：你代码中download方法第三个参数传值为true，代表开启SSL证书校验，若目标服务器证书为自签名、过期或是不在系统信任列表内，会直接触发错误回调。
无有效错误日志：当前你的错误回调仅打印了无意义字符串，无法根据错误码定位具体是网络、权限还是路径问题。

解决方法

第一步：校验并重新安装匹配版本的插件
执行以下命令安装对应版本的依赖，注意Ionic 5必须使用5.x版本的@ionic-native系列包：

ionic cordova plugin add cordova-plugin-file-transfer
ionic cordova plugin add cordova-plugin-file
npm install @ionic-native/file@5.x @ionic-native/file-transfer@5.x @ionic-native/android-permissions@5.x

第二步：补全平台权限配置
安卓端在AndroidManifest.xml中添加权限声明：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

iOS端在Info.plist中添加配置：

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>
<key>UIFileSharingEnabled</key>
<true/>

第三步：调整代码补全权限申请和错误日志
修改后的参考代码如下，测试阶段可临时关闭证书校验排查问题：

import { File } from '@ionic-native/file/ngx';
import { FileTransfer,  FileTransferObject } from '@ionic-native/file-transfer/ngx';
import { AndroidPermissions } from '@ionic-native/android-permissions/ngx';

constructor(private transfer: FileTransfer, private file: File, private router: Router, private androidPermissions: AndroidPermissions) { }

// 先申请权限再调用下载
checkPermissionAndDownload(){
  this.androidPermissions.checkPermission(this.androidPermissions.PERMISSION.WRITE_EXTERNAL_STORAGE).then(
    result => {
      if(result.hasPermission){
        this.download()
      }else{
        this.androidPermissions.requestPermission(this.androidPermissions.PERMISSION.WRITE_EXTERNAL_STORAGE).then(res=>{
          if(res.hasPermission) this.download()
        })
      }
    },
    err => this.androidPermissions.requestPermission(this.androidPermissions.PERMISSION.WRITE_EXTERNAL_STORAGE)
  );
}

download(){
    const url = 'https://file-examples-com.github.io/uploads/2017/10/file-sample_150kB.pdf';
    const fileTransfer: FileTransferObject = this.transfer.create();
    // 测试阶段可把第三个参数改为false跳过证书校验，确认逻辑正常后按需改回true
    fileTransfer.download(url, this.file.externalDataDirectory + 'file.pdf', false).then((entry) => {
      console.log('下载完成，存储路径: ' + entry.toURL());
    }, (error) => {
      // 打印完整错误信息定位问题，常见错误码：1=文件不存在 2=URL无效 3=连接异常 4=权限拒绝 5=证书校验失败
      console.log("下载失败，错误详情：", error);
      console.log("错误码：", error.code, "请求地址：", error.source, "存储路径：", error.target);
    });      
}

第四步：路径兼容测试
如果仍下载失败，可将存储路径替换为this.file.dataDirectory测试，部分定制Android系统对外部存储路径的权限限制更严格，使用应用内部存储路径兼容性更好。

内容的提问来源于stack exchange，提问作者Lokesh Kolli