PAYATHON 2026

无法安装 dotnet-ef:包中缺少 DotnetToolSettings.xml

技术问小赵

nuget.org 上的包本身缺文件并不常见。更常见的是本机 NuGet 缓存或 global tool 存储损坏,也可能是安装时用了镜像、私有源,或 package source mapping 指向了不完整、错误的包。建议先卸载旧版 dotnet-ef,清理 NuGet 和工具缓存,再强制只从 nuget.org 安装 10.0.12。多数情况下这样处理能恢复。

1. 确认并卸载旧的 global tool

报错里出现 failed to update,说明本机可能已有 dotnet-ef。先查看:

dotnet tool list --global

如果列表里有 dotnet-ef,先卸载:

dotnet tool uninstall --global dotnet-ef

如果卸载也失败,可以手动清理工具入口和 store 中残留的 dotnet-ef:

rm -f ~/.dotnet/tools/dotnet-ef
rm -rf ~/.dotnet/tools/.store/dotnet-ef

2. 清理 NuGet 和工具缓存

dotnet nuget locals all --clear
rm -rf ~/.nuget/packages/dotnet-ef
rm -rf ~/.dotnet/tools/.store/dotnet-ef

这一步是为了排除下载到一半的 nupkg、损坏的 global-packages 缓存,以及旧版工具留下的缓存目录。

3. 用只包含 nuget.org 的临时 NuGet.Config 安装

在当前目录新建 NuGet.Config,内容如下:

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

然后执行:

dotnet tool install --global dotnet-ef --version 10.0.12 --configfile ./NuGet.Config --ignore-failed-sources

如果之前有私有源、镜像源或 package source mapping,请先确认它们没有把 dotnet-ef 指向错误源;临时只用上面的 nuget.org 配置可以排除这类干扰。

4. 仍需排查时,确认包内路径是否正确

.NET tool 包里的设置文件通常应位于:

tools/<tfm>/any/DotnetToolSettings.xml

例如 tools/net10.0/any/DotnetToolSettings.xml。可以下载 nupkg 并检查:

curl -L -o dotnet-ef.10.0.12.nupkg https://api.nuget.org/v3-flatcontainer/dotnet-ef/10.0.12/dotnet-ef.10.0.12.nupkg
unzip -l dotnet-ef.10.0.12.nupkg | grep DotnetToolSettings.xml

如果这个文件不在 tools/<tfm>/any/ 下面,而是放在其他位置,说明包结构不符合 dotnet tool 的要求,换源或换版本才有意义。不要手动把 DotnetToolSettings.xml 塞进本地缓存或工具目录,这通常解决不了 NuGet 安装校验问题。

如果确认文件存在且路径正确,但仍报同样错误,再检查是否启用了 packageSourceMapping,以及 ~/.nuget/NuGet/NuGet.Config 或项目目录下的配置是否覆盖了临时配置。若包内有多个 TFM,且你怀疑框架选择不对,可显式指定与包内路径一致的 TFM,例如:

dotnet tool install --global dotnet-ef --version 10.0.12 --framework net10.0 --configfile ./NuGet.Config

5. 验证安装

安装成功后检查版本:

dotnet ef --version

也可以再次查看 global tool:

dotnet tool list --global

如果 10.0.12 的源或包本身确实有问题,可以先安装同主版本中一个可用的版本,再切回目标版本;最终仍以 nuget.org 上实际存在且包结构正确的版本为准。

备注:内容仅供参考。