无法使用dotnet tool install命令安装任何.NET工具的问题

问题现象 #

执行dotnet tool install --global dotnet-ef或其他.NET全局工具安装命令时，触发以下错误：

C:\Users%USERNAME%\AppData\Local\Temp\147383a8-b714-4336-bb96-30c0670ea37d\restore.csproj : error NU1211: Project restore must have a single package reference(s).
C:\Users\abby.rahimi\AppData\Local\Temp\147383a8-b714-4336-bb96-30c0670ea37d\restore.csproj : error NU1212: Invalid project-package combination for Microsoft.DotNet.Analyzers.Compatibility 0.2.12-alpha. DotnetToolReference project style can only contain references of the DotnetTool type
The tool package could not be restored.
Tool 'dotnet-ef' failed to install. This failure may have been caused by:

• You are attempting to install a preview release and did not use the --version option to specify the version.
• A package by this name was found, but it was not a .NET tool.
• The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
• You mistyped the name of the tool.

所有.NET全局工具均无法安装，已尝试指定版本、忽略源错误、重装SDK、清理工具目录等方法无效，网络可正常访问NuGet官方源。

解决方案 #

错误根源是全局NuGet配置中混入了非DotnetTool类型的引用（如分析器包），导致安装工具时临时生成的restore.csproj被强制添加无效引用，违反Tool项目的规则。可通过以下步骤修复：

1. 检查并修正全局NuGet配置

   • 打开C:\Users\<你的用户名>\AppData\Roaming\NuGet\NuGet.Config
   • 查找并移除全局级别的<PackageReference>或分析器相关配置（尤其是Microsoft.DotNet.Analyzers.Compatibility相关条目）
   • 确保配置中仅保留包源和必要的工具相关设置

2. 检查系统级NuGet配置

   • 查看C:\Program Files (x86)\NuGet\Config下的配置文件，确认没有全局强制添加的非Tool类引用，如有则移除

3. 清理NuGet缓存
   执行命令清理所有NuGet本地缓存：

   dotnet nuget locals all --clear
   

   清理完成后重新尝试安装工具：

   dotnet tool install --global dotnet-ef
   

4. 临时使用干净的NuGet配置

   • 创建仅包含NuGet官方源的干净配置文件clean-nuget.config，内容如下：

     <?xml version="1.0" encoding="utf-8"?>
     <configuration>
       <packageSources>
         <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
       </packageSources>
     </configuration>
     

   • 使用该配置文件安装工具：

     dotnet tool install --global dotnet-ef --configfile "C:\temp\clean-nuget.config"
     

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