Flutter应用模拟器正常，真机HTML转PDF无限加载问题排查

1. 修正本地资源路径逻辑 #

模拟器和真机的文件沙箱规则不同，硬编码路径大概率会在真机上失效。改用path_provider获取合法的应用存储路径：

final directory = await getApplicationDocumentsDirectory();
final htmlFilePath = '${directory.path}/target.html';

避免直接使用/storage/emulated/0/这类绝对路径，这类路径在真机上需要额外的特殊权限，且不同厂商适配逻辑不一致。

2. 补全权限配置与动态申请 #

即便添加了静态权限，Android 10+还需要动态申请存储权限，同时适配Android 13+的媒体权限：

• 在AndroidManifest.xml中补充权限：

  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <!-- Android 13+ 媒体权限 -->
  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
  

• 在Flutter代码中动态申请权限（依赖permission_handler包）：

  final storageStatus = await Permission.storage.request();
  if (storageStatus.isGranted) {
    // 执行PDF转换逻辑
  } else {
    // 提示用户开启存储权限
  }
  

3. 调试Printing.convertHtml逻辑 #

真机卡住大概率是HTML内容或转换参数的问题：

• 先测试纯文本HTML，排除远程图片、外部CSS等资源加载超时的可能；
• 添加超时处理，避免无限加载：

  try {
    final pdfBytes = await Printing.convertHtml(
      format: PdfPageFormat.a4,
      html: htmlContent,
    ).timeout(const Duration(seconds: 20));
    // 保存或导出PDF
  } on TimeoutException {
    // 提示用户转换超时
  } catch (e) {
    print('转换异常详情: $e');
  }
  

4. 查看真机日志定位问题 #

通过adb命令抓取Flutter日志，直接查看转换过程中的错误信息：

adb logcat -s flutter

重点关注是否有文件读取失败、资源加载异常等报错。

5. 排查依赖版本兼容性 #

检查printing和pdf包的版本是否匹配，尝试更新到最新稳定版：

dependencies:
  printing: ^5.12.0
  pdf: ^3.10.0

内容的提问来源于stack exchange，提问作者Abdelrhman Ayman