📦 Directory.Packages.props 详解：NuGet 包的中央管理最佳实践

在 .NET 开发中，如何高效管理 NuGet 包版本 一直是个挑战。项目变多，包的版本不一致，维护起来非常麻烦。
好消息是，从 .NET 6 开始，Microsoft 引入了 Central Package Management（中央包管理），让 Directory.Packages.props 文件来 统一管理所有 NuGet 包的版本。

📌 什么是 Directory.Packages.props？

Directory.Packages.props 是一个 MSBuild 配置文件，用于 集中定义 解决方案中所有项目所需的 NuGet 包版本。

💡 传统管理方式（项目级包管理）

• 每个 .csproj 文件都单独管理 PackageReference。
• 版本不同步，容易导致版本冲突和依赖问题。
• 维护成本高。

✅ 采用 Directory.Packages.props 的优点

• 版本统一：所有项目共享相同的包版本，避免冲突。
• 维护简便：只需在一个文件中更新包版本，而不需要修改多个 .csproj 文件。
• 构建更快：减少 NuGet 解析依赖的时间，提高 CI/CD 效率。

📌 如何启用 Directory.Packages.props？

1️⃣ 在解决方案根目录创建 Directory.Packages.props

在 .sln 解决方案文件所在的 根目录，创建 Directory.Packages.props 文件（注意是 props 不是 csproj！）。

```xml
<Project>
  <PropertyGroup>
    <!-- 启用中央包管理 -->
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <!-- 统一管理 NuGet 包的版本 -->
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageVersion Include="Serilog" Version="2.12.0" />
    <PackageVersion Include="Autofac" Version="6.4.0" />
  </ItemGroup>
</Project>

2️⃣ 修改 .csproj 文件，删除版本号

在项目的 .csproj 文件中：

• 移除 Version 属性，只保留 PackageReference。

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" />
  <PackageReference Include="Serilog" />
  <PackageReference Include="Autofac" />
</ItemGroup>

这样 csproj 就不再管理版本号，而是完全由 Directory.Packages.props 统一管理！

3️⃣ 运行 dotnet restore

执行 NuGet 还原，让 .NET SDK 解析新的中央包管理。

dotnet restore

📌 高级用法

🔹 1. 支持多个 .NET 目标框架

<ItemGroup Condition=" '$(TargetFramework)' == 'net6.0' ">
  <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="7.0.20" />
</ItemGroup>

<ItemGroup Condition=" '$(TargetFramework)' == 'net8.0' ">
  <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
</ItemGroup>

🔹 2. 统一管理企业级框架的版本

如果你有多个 Framework* 开头的内部 NuGet 包（比如 FrameworkCore、FrameworkUI.Wpf），可以使用 MSBuild 变量 统一版本：

<PropertyGroup>
  <FrameworkVersion>1.1.1</FrameworkVersion>
</PropertyGroup>

<ItemGroup>
  <!-- 自动为 Framework* 开头的包应用相同版本 -->
  <PackageVersion Include="Framework*" Version="$(FrameworkVersion)" />
</ItemGroup>

📌 常见错误及解决方案

❌ NU1008: 使用中央包管理的项目不应定义 PackageReference 版本

原因：你的 .csproj 仍然有 PackageReference 带 Version 属性。

✅ 解决方法：

• 移除 .csproj 里的 Version，让 Directory.Packages.props 统一管理。

❌ NU1102: 找不到指定版本的包

原因：

• 包名错误 或者 版本号不存在。
• nuget.config 配置有误。

✅ 解决方法：

• 确保 PackageVersion 中的 包名正确。
• 运行 dotnet restore --force，清理缓存。

💡 这样，所有 Framework* 开头的包都会自动使用 FrameworkVersion！

📌 总结

✅ Directory.Packages.props 是现代 .NET 解决方案的最佳实践，适用于 大型企业项目、团队开发、CI/CD 自动化。