WinUI 3 NuGet包自定义字体引用失效问题求助

一、确认NuGet包的字体打包配置 #

不管选择Content还是Resource方式，都必须在.nuspec文件中明确包含字体文件，否则打包后字体不会被正确分发：

• Content方式：
  在.nuspec的<files>节点中添加：

  <files>
    <!-- 适配不同引用方式的目录结构 -->
    <file src="Assets\Fonts\*.ttf" target="contentFiles\any\any\Assets\Fonts" />
    <file src="Assets\Fonts\*.ttf" target="content\Assets\Fonts" />
  </files>
  

  同时确保字体文件的复制到输出目录设为「始终复制」，生成操作设为「Content」。

• Resource方式：
  将字体文件的生成操作设为「Resource」，然后在.nuspec中添加：

  <files>
    <!-- 替换为你的WinUI3目标框架版本 -->
    <file src="Assets\Fonts\*.ttf" target="lib\net6.0-windows10.0.19041.0\Assets\Fonts" />
  </files>
  

二、修正字体引用路径 #

NuGet包引用时，不能用本地项目的相对路径，必须使用ms-appx:///协议：

• Content方式：路径基于最终应用的根目录，示例：

  <FontFamily>ms-appx:///Assets/Fonts/CustomIconFont.ttf#CustomIconFontFamily</FontFamily>
  

• Resource方式：路径必须包含NuGet包的程序集名称（注意不是NuGet包ID），示例：

  <FontFamily>ms-appx:///YourNuGetAssemblyName/Assets/Fonts/CustomIconFont.ttf#CustomIconFontFamily</FontFamily>
  

  提示：字体的#后面是字体内部族名，不是文件名！右键字体文件选择「预览」，窗口标题显示的就是族名，必须准确匹配。

三、验证NuGet包的文件结构 #

将.nupkg文件重命名为.zip解压，检查：

• Content方式：确认content和contentFiles目录下存在字体文件；
• Resource方式：确认对应框架的lib目录下存在字体文件。
  如果文件缺失，说明.nuspec配置有误，需要调整路径。

四、检查App.xaml的字体注册 #

确保在Application.Resources中的字体注册路径正确，示例：

<Application.Resources>
    <ResourceDictionary>
        <FontFamily x:Key="CustomIconFont">ms-appx:///Assets/Fonts/CustomIconFont.ttf#CustomIconFontFamily</FontFamily>
    </ResourceDictionary>
</Application.Resources>

常见坑点 #

• 混淆字体文件名和内部族名：这是最常见的错误，必须用字体预览工具确认族名；
• 程序集名称与NuGet包ID不一致：Resource方式的路径必须使用程序集名称，而非包ID；
• 未正确配置.nuspec：遗漏<files>节点会导致字体文件不被打包进NuGet包。

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