MSBuild执行nuget restore触发NU1701致构建失败的原因及解决

API 探路者

2026-8-29

问题根因

NuGet依赖解析逻辑存在环境差异：Visual Studio内置的NuGet还原模块默认开启兼容资产自动回退适配，针对.NET Standard 2.0项目引用.NET Framework类库的场景，会自动将NU1701标记为低优先级提示，不会中断构建流程；命令行单独调用MSBuild/独立版nuget.exe执行还原时，若使用的NuGet版本低于VS内置版本，会将NU1701默认按错误处理，同时无法正确匹配fo-dicom的依赖组——从给出的nuspec内容可以看到，4.0.8.1版本的fo-dicom仅为.NET Framework 4.5声明了fo-dicom.Desktop依赖，未配置.NET Standard 2.0对应的依赖项，命令行解析时找不到匹配目标框架的资产，就会自动拉取.NET Framework版本的包做兼容性回退，触发NU1701警告并升级为构建错误。
环境版本不匹配：VS 2019及以上版本内置的NuGet版本均在5.0以上，针对.NET Standard 2.0与.NET Framework 4.6.1+的兼容场景做了特殊逻辑适配；如果命令行使用的是独立安装的旧版MSBuild、或5.0以下版本的nuget.exe，没有搭载VS配套的NuGet编译目标文件，就会出现和VS内还原行为不一致的问题。
包本身存在配置缺陷：fo-dicom 4.0.8.1版本的nuspec存在配置遗漏，该版本实际已经提供了适配.NET Standard的fo-dicom.Core包，但元包没有为.NET Standard/.NET Core目标框架声明正确的依赖组，VS还原时会做隐式依赖修正，命令行环境没有这层隐式处理逻辑，就会出现依赖拉取错误。

可行解决方案

方案1：对齐命令行构建环境和VS的组件版本
不要使用单独下载的旧版nuget.exe、独立安装的MSBuild执行还原和构建，直接调用VS安装目录下的MSBuild程序执行操作，以VS2022社区版为例，执行命令为：
```
"C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe" 你的项目文件路径.csproj /t:restore,build
```
这种方式会直接复用VS内置的NuGet解析逻辑，和VS内手动点还原、构建的行为完全一致，不会出现解析差异。
方案2：升级fo-dicom到修复了配置缺陷的版本
直接将fo-dicom包升级到4.0.10及以上的稳定版本，后续版本已经补全了.NET Standard 2.0对应的依赖组声明，不会再错误将.NET Framework专属的fo-dicom.Desktop包拉取到.NET Standard项目中，从根源上消除NU1701警告。
方案3：锁定旧版本时手动配置依赖引用
如果因为兼容性要求必须使用4.0.8.1版本，就不要直接引用fo-dicom元包，改为在csproj中按目标框架条件引用对应分包：.NET Standard 2.0目标直接引用跨平台的fo-dicom.Core包，.NET Framework目标引用fo-dicom.Desktop包，配置示例如下：
```
<ItemGroup>
  <PackageReference Include="fo-dicom.Core" Version="4.0.8.1" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
  <PackageReference Include="fo-dicom.Desktop" Version="4.0.8.1" Condition="'$(TargetFramework.StartsWith('net4'))'" />
</ItemGroup>
```
方案4：临时绕过警告（仅作应急使用，不推荐）
如果需要快速跑通构建，可以在项目文件中加入配置，将NU1701从错误降级为警告，同时开启包目标回退支持：
```
<PropertyGroup>
  <NoWarn>$(NoWarn);NU1701</NoWarn>
  <RestorePackageTargetFallback>$(RestorePackageTargetFallback);net461</RestorePackageTargetFallback>
</PropertyGroup>
```
该方案仅绕过检查，没有解决实际的依赖匹配问题，可能在运行时出现类型加载、平台调用相关的异常。

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