构建与使用 Avalonia 本地 NuGet 包CreateNugetPackages 与 BuildToNuGetCache 实战指南【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia本篇指南围绕 Avalonia 仓库的 docs/nuget.md 展开系统讲解如何通过 Nuke 构建脚本在本地生成 Avalonia 的 NuGet 包CreateNugetPackages目标以及如何借助BuildToNuGetCache目标把构建产物直接打入本机 NuGet 全局缓存从而在二次开发、改源码调试、验证本地修改时快速获得可用的包。读完本文你将掌握跨平台的包构建命令、版本与构建配置控制以及绕过本地 feed 配置直接消费自编译 Avalonia 的完整套路。一、构建本地 NuGet 包的整体流程Avalonia 的仓库构建体系基于 Nuke.NET Universal Build Automation。CreateNugetPackages是产出最终.nupkg的核心目标它在 nukebuild/Build.cs 中定义依赖链如下CreateNugetPackages └─ CreateIntermediateNugetPackages 对解决方案执行 dotnet pack产出中间包 └─ Compile 先编译整个解决方案从 nukebuild/Build.cs 的源码可以看到CreateIntermediateNugetPackages会对根目录的dirs.projParameters.MSBuildSolution定义于 nukebuild/BuildParameters.cs执行DotNetPack随后CreateNugetPackages目标完成三道关键工序修补 Build.Tasks通过BuildTasksPatcher.PatchBuildTasksInPackage使用 ILRepack 工具对Avalonia.Build.Tasks中间包进行处理合并子包读取 nukebuild/numerge.json 中的合并配置使用 Numerge 的NugetPackageMerger.Merge把Avalonia.Build.Tasks、Avalonia.Generators、Avalonia.Analyzers.CSharp、Avalonia.Analyzers.VisualBasic、Avalonia.Analyzers.CodeFixes.CSharp等子包合并进主Avalonia包MergeAll: true同时也合并Avalonia.Win32.Automation到Avalonia.Win32生成引用程序集调用RefAssemblyGenerator.GenerateRefAsmsInPackage为Avalonia.version.nupkg与其配套的.snupkg生成 ref 程序集。最终产物会被放入artifacts\nuget目录NugetRoot ArtifactsDir / nuget见 nukebuild/BuildParameters.cs。二、三种调用方式与跨平台命令1. 仓库内置构建脚本推荐用于 CI 化、无全局工具环境WindowsPowerShell.\build.ps1 CreateNugetPackagesLinux/macOS./build.sh CreateNugetPackages这两个脚本位于仓库根目录其引导逻辑是优先使用本机已安装且与 global.json当前要求 SDK10.0.201匹配的 dotnet CLI若不可用则自动下载对应版本的 SDK 到.nuke/temp。随后编译 nukebuild/_build.csproj 并用dotnet run --project nukebuild/_build.csproj --no-build -- 目标参数把命令行参数透传给 Nuke见 build.sh、build.ps1。2. Nuke 全局工具跨平台一致推荐日常开发如果你安装了 Nuke 的 dotnet global tool命令为nuke可以直接nuke CreateNugetPackages本文后续命令统一假设你已安装 Nuke 全局工具因为它跨平台调用方式一致你随时可以用./build.sh或.\build.ps1替换其中的nuke注意平台相关脚本路径不同。构建成功后生成的 NuGet 包位于artifacts\nuget目录。三、控制构建配置与包版本1. 使用 Release 配置构建默认情况下包以 Debug 配置构建。若要生成 Release 版本添加--configuration参数nuke CreateNugetPackages --configuration Release该参数对应 nukebuild/BuildParameters.cs 中声明的[Parameter(Name configuration)]且默认值本身就是Release见 nukebuild/BuildParameters.cs也就是说不传该参数时其实默认就是 Release显式传入Debug等值可以覆盖默认行为。配置值会通过ApplySettingCore中的SetConfiguration注入到每个 dotnet 命令nukebuild/Build.cs。2. 强制指定 NuGet 版本默认的包版本号来自 build/SharedVersion.props 中的Version节点当前仓库为12.2.999由BuildParameters.GetVersion()读取见 nukebuild/BuildParameters.cs。想临时指定版本使用--force-nuget-versionnuke CreateNugetPackages --force-nuget-version 11.4.0该参数对应[Parameter(Name force-nuget-version)]nukebuild/BuildParameters.cs其优先级高于版本文件Version b.ForceNugetVersion ?? GetVersion()nukebuild/BuildParameters.cs。指定的版本会同时作为PackageVersionMSBuild 属性注入到打包过程nukebuild/Build.cs。在 Azure CI 环境中若未发布分支版本还会被追加-cibuildBuildId-alpha后缀nukebuild/BuildParameters.cs。此外仓库根目录的 Directory.Packages.propsCentral Package Management负责统一管理依赖包版本构建 Avalonia 自身的包时依赖清单即由此集中约束。四、直接构建到本机 NuGet 缓存BuildToNuGetCache1. 为什么需要它CreateNugetPackages 的几个坑直接用CreateNugetPackages产出包再消费会遇到三类典型问题需要自行搭建本地 NuGet feed必须配置NuGet.Config指向本地源才能让消费项目还原到这些包Avalonia.Native 缺失在非 macOS 操作系统上构建时Avalonia.Native基于 Xcode 项目的原生宿主不会被编译导致使用Avalonia.Desktop时报 NuGet 错误。这是因为原生编译目标CompileNative带有OnlyWhenStatic(() EnvironmentInfo.IsOsx)的平台限制见 nukebuild/Build.cs容易引入版本管理混乱手改版本号、忘记覆盖旧版本等都会让“我这包是哪次编译的”变成难题。2. 一键命令为解决上述问题仓库提供了BuildToNuGetCache目标nuke --target BuildToNuGetCache --configuration Release该命令会先执行CreateNugetPackages生成完整包依赖关系见 nukebuild/Build.cs把每个.nupkg解压到本机 NuGet 全局缓存目录通常为~/.nuget/packages下的包id小写/9999.0.0-localbuild/路径并写入.nupkg.metadata文件见 nukebuild/Build.cs。包版本统一为9999.0.0-localbuild该常量定义于 nukebuild/BuildParameters.cspublic const string LocalBuildVersion 9999.0.0-localbuild。当isPackingToLocalCache为真时BuildParameters会把Version强制替换为该常量nukebuild/BuildParameters.cs。与此同时ApplySettingCore会在打包到本地缓存时自动附加一组 MSBuild 属性nukebuild/Build.cs属性值作用ForcePackAvaloniaNativeTrue强制打入 Avalonia.Native 原生包规避非 macOS 平台缺包问题SkipObscurePlatformsTrue跳过次要平台目标加快打包SkipBuildingSamplesTrue跳过示例工程只关注库本体SkipBuildingTestsTrue跳过测试工程显著缩短构建链路3. 消费本地修改的工作流每次修改 Avalonia 源码后只需再次运行nuke --target BuildToNuGetCache --configuration Release新包会替换~/.nuget/packages下的旧包并重置缓存MSBuild 在下一次还原时自动拾取最新内容无需手动清理缓存或维护本地 feed。这特别适合“改源码 → 跑本地 demo/测试 → 验证效果”的迭代循环例如配合 samples/Sandbox 或 tests/BuildTests该测试目录专门用于验证打包后的 Avalonia 能被外部工程正确编译、甚至原生 AOT 运行见 nukebuild/Build.cs 的VerifyXamlCompilation。仓库还提供了现成的快捷脚本 nukebuild/build-to-cache.sh等价于dotnet run --project nukebuild/_build.csproj -- --target BuildToNuGetCache --skip CompileHtmlPreviewer Compile Clean它额外跳过了CompileHtmlPreviewer、Compile、Clean等前置目标进一步缩短本地迭代耗时。4. 注意事项BuildToNuGetCache会把包写入全局用户缓存Linux/macOS 为~/.nuget/packagesWindows 为%USERPROFILE%\.nuget\packages该目录下的9999.0.0-localbuild包是“本地构建专用版本”与官方发布版本互不干扰若你的消费工程启用了NuGetAudit或严格版本约束请确保它允许还原9999.0.0-localbuild这样的预发布版本号该目标内部通过SettingsUtility.GetGlobalPackagesFolder(Settings.LoadDefaultSettings(RootDirectory))解析全局包目录nukebuild/Build.cs若你自定义过 NuGet 配置实际目录以该解析结果为准。五、验证与调试配套的测试基建构建与打包的正确性在仓库中是有测试保障的tests/BuildTests 是一组专门的外部消费工程含BuildTests.Desktop、BuildTests.Browser、BuildTests.Android、BuildTests.iOS、BuildTests.FSharp、BuildTests.NativeAot、BuildTests.WpfHybrid等CI 会用刚打包出的 Avalonia 版本还原并编译它们再通过XamlCompilationVerifier校验程序集内嵌 XAML 是否被正确编译nukebuild/Build.csnukebuild/numerge.json 是包合并的“事实来源”如果你手动检查artifacts\nuget下的产物结构会发现主Avalonia包内集成了生成器与分析器组件这是MergeAll: true的直接体现。六、常见问题速查问题解决方案非 macOS 平台使用Avalonia.Desktop报原生包缺失改用BuildToNuGetCache会自动设置ForcePackAvaloniaNativeTrue或参考 native/Avalonia.Native/README.md 在支持的平台自行编译原生库想发布 Release 包加--configuration Release想用自定义版本号加--force-nuget-version 版本产物位置artifacts\nuget中间产物在build-intermediate\nuget不想配置本地 feed直接用BuildToNuGetCache写入全局缓存消费方以9999.0.0-localbuild还原总而言之日常源码调试优先使用BuildToNuGetCache发布/分发场景使用CreateNugetPackages加--configuration、--force-nuget-version精确控制产物两条路径都由 nukebuild/Build.cs 与 nukebuild/BuildParameters.cs 统一驱动理解这几个文件即可完全掌控 Avalonia 的本地打包链路。【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
构建与使用 Avalonia 本地 NuGet 包：CreateNugetPackages 与 BuildToNuGetCache 实战指南
构建与使用 Avalonia 本地 NuGet 包CreateNugetPackages 与 BuildToNuGetCache 实战指南【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia本篇指南围绕 Avalonia 仓库的 docs/nuget.md 展开系统讲解如何通过 Nuke 构建脚本在本地生成 Avalonia 的 NuGet 包CreateNugetPackages目标以及如何借助BuildToNuGetCache目标把构建产物直接打入本机 NuGet 全局缓存从而在二次开发、改源码调试、验证本地修改时快速获得可用的包。读完本文你将掌握跨平台的包构建命令、版本与构建配置控制以及绕过本地 feed 配置直接消费自编译 Avalonia 的完整套路。一、构建本地 NuGet 包的整体流程Avalonia 的仓库构建体系基于 Nuke.NET Universal Build Automation。CreateNugetPackages是产出最终.nupkg的核心目标它在 nukebuild/Build.cs 中定义依赖链如下CreateNugetPackages └─ CreateIntermediateNugetPackages 对解决方案执行 dotnet pack产出中间包 └─ Compile 先编译整个解决方案从 nukebuild/Build.cs 的源码可以看到CreateIntermediateNugetPackages会对根目录的dirs.projParameters.MSBuildSolution定义于 nukebuild/BuildParameters.cs执行DotNetPack随后CreateNugetPackages目标完成三道关键工序修补 Build.Tasks通过BuildTasksPatcher.PatchBuildTasksInPackage使用 ILRepack 工具对Avalonia.Build.Tasks中间包进行处理合并子包读取 nukebuild/numerge.json 中的合并配置使用 Numerge 的NugetPackageMerger.Merge把Avalonia.Build.Tasks、Avalonia.Generators、Avalonia.Analyzers.CSharp、Avalonia.Analyzers.VisualBasic、Avalonia.Analyzers.CodeFixes.CSharp等子包合并进主Avalonia包MergeAll: true同时也合并Avalonia.Win32.Automation到Avalonia.Win32生成引用程序集调用RefAssemblyGenerator.GenerateRefAsmsInPackage为Avalonia.version.nupkg与其配套的.snupkg生成 ref 程序集。最终产物会被放入artifacts\nuget目录NugetRoot ArtifactsDir / nuget见 nukebuild/BuildParameters.cs。二、三种调用方式与跨平台命令1. 仓库内置构建脚本推荐用于 CI 化、无全局工具环境WindowsPowerShell.\build.ps1 CreateNugetPackagesLinux/macOS./build.sh CreateNugetPackages这两个脚本位于仓库根目录其引导逻辑是优先使用本机已安装且与 global.json当前要求 SDK10.0.201匹配的 dotnet CLI若不可用则自动下载对应版本的 SDK 到.nuke/temp。随后编译 nukebuild/_build.csproj 并用dotnet run --project nukebuild/_build.csproj --no-build -- 目标参数把命令行参数透传给 Nuke见 build.sh、build.ps1。2. Nuke 全局工具跨平台一致推荐日常开发如果你安装了 Nuke 的 dotnet global tool命令为nuke可以直接nuke CreateNugetPackages本文后续命令统一假设你已安装 Nuke 全局工具因为它跨平台调用方式一致你随时可以用./build.sh或.\build.ps1替换其中的nuke注意平台相关脚本路径不同。构建成功后生成的 NuGet 包位于artifacts\nuget目录。三、控制构建配置与包版本1. 使用 Release 配置构建默认情况下包以 Debug 配置构建。若要生成 Release 版本添加--configuration参数nuke CreateNugetPackages --configuration Release该参数对应 nukebuild/BuildParameters.cs 中声明的[Parameter(Name configuration)]且默认值本身就是Release见 nukebuild/BuildParameters.cs也就是说不传该参数时其实默认就是 Release显式传入Debug等值可以覆盖默认行为。配置值会通过ApplySettingCore中的SetConfiguration注入到每个 dotnet 命令nukebuild/Build.cs。2. 强制指定 NuGet 版本默认的包版本号来自 build/SharedVersion.props 中的Version节点当前仓库为12.2.999由BuildParameters.GetVersion()读取见 nukebuild/BuildParameters.cs。想临时指定版本使用--force-nuget-versionnuke CreateNugetPackages --force-nuget-version 11.4.0该参数对应[Parameter(Name force-nuget-version)]nukebuild/BuildParameters.cs其优先级高于版本文件Version b.ForceNugetVersion ?? GetVersion()nukebuild/BuildParameters.cs。指定的版本会同时作为PackageVersionMSBuild 属性注入到打包过程nukebuild/Build.cs。在 Azure CI 环境中若未发布分支版本还会被追加-cibuildBuildId-alpha后缀nukebuild/BuildParameters.cs。此外仓库根目录的 Directory.Packages.propsCentral Package Management负责统一管理依赖包版本构建 Avalonia 自身的包时依赖清单即由此集中约束。四、直接构建到本机 NuGet 缓存BuildToNuGetCache1. 为什么需要它CreateNugetPackages 的几个坑直接用CreateNugetPackages产出包再消费会遇到三类典型问题需要自行搭建本地 NuGet feed必须配置NuGet.Config指向本地源才能让消费项目还原到这些包Avalonia.Native 缺失在非 macOS 操作系统上构建时Avalonia.Native基于 Xcode 项目的原生宿主不会被编译导致使用Avalonia.Desktop时报 NuGet 错误。这是因为原生编译目标CompileNative带有OnlyWhenStatic(() EnvironmentInfo.IsOsx)的平台限制见 nukebuild/Build.cs容易引入版本管理混乱手改版本号、忘记覆盖旧版本等都会让“我这包是哪次编译的”变成难题。2. 一键命令为解决上述问题仓库提供了BuildToNuGetCache目标nuke --target BuildToNuGetCache --configuration Release该命令会先执行CreateNugetPackages生成完整包依赖关系见 nukebuild/Build.cs把每个.nupkg解压到本机 NuGet 全局缓存目录通常为~/.nuget/packages下的包id小写/9999.0.0-localbuild/路径并写入.nupkg.metadata文件见 nukebuild/Build.cs。包版本统一为9999.0.0-localbuild该常量定义于 nukebuild/BuildParameters.cspublic const string LocalBuildVersion 9999.0.0-localbuild。当isPackingToLocalCache为真时BuildParameters会把Version强制替换为该常量nukebuild/BuildParameters.cs。与此同时ApplySettingCore会在打包到本地缓存时自动附加一组 MSBuild 属性nukebuild/Build.cs属性值作用ForcePackAvaloniaNativeTrue强制打入 Avalonia.Native 原生包规避非 macOS 平台缺包问题SkipObscurePlatformsTrue跳过次要平台目标加快打包SkipBuildingSamplesTrue跳过示例工程只关注库本体SkipBuildingTestsTrue跳过测试工程显著缩短构建链路3. 消费本地修改的工作流每次修改 Avalonia 源码后只需再次运行nuke --target BuildToNuGetCache --configuration Release新包会替换~/.nuget/packages下的旧包并重置缓存MSBuild 在下一次还原时自动拾取最新内容无需手动清理缓存或维护本地 feed。这特别适合“改源码 → 跑本地 demo/测试 → 验证效果”的迭代循环例如配合 samples/Sandbox 或 tests/BuildTests该测试目录专门用于验证打包后的 Avalonia 能被外部工程正确编译、甚至原生 AOT 运行见 nukebuild/Build.cs 的VerifyXamlCompilation。仓库还提供了现成的快捷脚本 nukebuild/build-to-cache.sh等价于dotnet run --project nukebuild/_build.csproj -- --target BuildToNuGetCache --skip CompileHtmlPreviewer Compile Clean它额外跳过了CompileHtmlPreviewer、Compile、Clean等前置目标进一步缩短本地迭代耗时。4. 注意事项BuildToNuGetCache会把包写入全局用户缓存Linux/macOS 为~/.nuget/packagesWindows 为%USERPROFILE%\.nuget\packages该目录下的9999.0.0-localbuild包是“本地构建专用版本”与官方发布版本互不干扰若你的消费工程启用了NuGetAudit或严格版本约束请确保它允许还原9999.0.0-localbuild这样的预发布版本号该目标内部通过SettingsUtility.GetGlobalPackagesFolder(Settings.LoadDefaultSettings(RootDirectory))解析全局包目录nukebuild/Build.cs若你自定义过 NuGet 配置实际目录以该解析结果为准。五、验证与调试配套的测试基建构建与打包的正确性在仓库中是有测试保障的tests/BuildTests 是一组专门的外部消费工程含BuildTests.Desktop、BuildTests.Browser、BuildTests.Android、BuildTests.iOS、BuildTests.FSharp、BuildTests.NativeAot、BuildTests.WpfHybrid等CI 会用刚打包出的 Avalonia 版本还原并编译它们再通过XamlCompilationVerifier校验程序集内嵌 XAML 是否被正确编译nukebuild/Build.csnukebuild/numerge.json 是包合并的“事实来源”如果你手动检查artifacts\nuget下的产物结构会发现主Avalonia包内集成了生成器与分析器组件这是MergeAll: true的直接体现。六、常见问题速查问题解决方案非 macOS 平台使用Avalonia.Desktop报原生包缺失改用BuildToNuGetCache会自动设置ForcePackAvaloniaNativeTrue或参考 native/Avalonia.Native/README.md 在支持的平台自行编译原生库想发布 Release 包加--configuration Release想用自定义版本号加--force-nuget-version 版本产物位置artifacts\nuget中间产物在build-intermediate\nuget不想配置本地 feed直接用BuildToNuGetCache写入全局缓存消费方以9999.0.0-localbuild还原总而言之日常源码调试优先使用BuildToNuGetCache发布/分发场景使用CreateNugetPackages加--configuration、--force-nuget-version精确控制产物两条路径都由 nukebuild/Build.cs 与 nukebuild/BuildParameters.cs 统一驱动理解这几个文件即可完全掌控 Avalonia 的本地打包链路。【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
