.NET MAUI安卓端iText7 v8.0.5发布模式PDF生成失败问题

可能的核心原因 #

• 发布模式默认启用的**代码链接（Linker）**裁剪了iText7 8.0.5的必要依赖代码，导致运行时无法正常初始化PDF生成逻辑
• AOT编译兼容性问题：iText7 8.0.5部分代码逻辑不兼容.NET MAUI Android的AOT编译规则，发布模式下编译后无法执行
• 8.0.5版本新增的依赖项在发布打包时未被正确包含

具体排查与解决步骤 #

1. 调整Linker配置，避免裁剪iText7核心程序集 #

在项目的.csproj文件中，针对Android发布配置添加保留规则：

<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|net8.0-android|AnyCPU'">
  <!-- 仅链接SDK，保留iText相关程序集 -->
  <AndroidLinkMode>SdkOnly</AndroidLinkMode>
  <AndroidLinkSkip>itext.io;itext.kernel;itext.layout;itext.forms</AndroidLinkSkip>
</PropertyGroup>

如果不确定具体需要保留的程序集，可以临时将AndroidLinkMode设为None（注意会增大APK体积），测试是否能正常生成PDF，以此验证是否是Linker的问题。

2. 禁用AOT编译测试 #

如果启用了AOT，尝试关闭它验证问题是否消失：

<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|net8.0-android|AnyCPU'">
  <RunAOTCompilation>false</RunAOTCompilation>
</PropertyGroup>

若问题解决，说明是iText7 8.0.5与AOT的兼容性Bug，建议向iText官方提交反馈。

3. 确认依赖包完整性 #

清理NuGet缓存后，重新安装iText7 8.0.5的所有核心包，确保itext.io、itext.kernel、itext.layout等依赖都被正确引用且打包到发布版本中。

4. 捕获静默异常，获取具体错误信息 #

发布模式下无日志的话，添加全局异常捕获逻辑，用adb logcat查看详细错误：
在MainActivity.cs中添加：

protected override void OnCreate(Bundle savedInstanceState)
{
    base.OnCreate(savedInstanceState);

    // 捕获AppDomain未处理异常
    AppDomain.CurrentDomain.UnhandledException += (sender, e) =>
    {
        var ex = e.ExceptionObject as Exception;
        System.Diagnostics.Debug.WriteLine($"Uncaught Exception: {ex?.ToString()}");
    };

    // 捕获Android平台未处理异常
    AndroidEnvironment.UnhandledExceptionRaiser += (sender, e) =>
    {
        System.Diagnostics.Debug.WriteLine($"Android Uncaught Exception: {e.Exception.ToString()}");
        e.Handled = true;
    };
}

发布安装后，通过命令行执行adb logcat *:S MyAppTag:D（替换为你的应用标签），查看是否有PDF生成过程中的异常信息。

总结 #

优先排查Linker和AOT的配置问题，这是.NET MAUI Android发布模式下第三方库常见的兼容性坑。如果调整配置后问题仍存在，大概率是iText7 8.0.5的Android特定Bug，建议暂时回退到8.0.4版本，同时向官方提交问题反馈。

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