dotnet restore报NU1101与NU1301还原失败的排查方法(NuGet.Config包源、--ignore-failed-sources与--no-cache定位)

dotnet restore或Visual Studio里还原NuGet包时突然报error NU1101: Unable to find package,或者error NU1301: Unable to load the service index for source,编译停在还原阶段,project.assets.json没生成,后面还会连带报NETSDK1004: Assets file not found。这类问题跟代码写没写对无关,是NuGet没找到包、或者其中一条包源连不上。把这两个码分清是第一步:NU1101说的是配置的源里压根没有这个包,NU1301说的是某条源取不到服务索引,定位方向完全不同。


先把当前生效的源列出来

NuGet的配置是分层的,用户级配置、解决方案目录里的NuGet.Config、项目目录里的NuGet.Config、还有CI里注入的环境变量,一层层叠加,越靠近项目的优先级越高。别凭记忆猜有哪些源,dotnet nuget list source会把当前目录实际生效的源全部列出来,包括从父目录继承来的、被disabledPackageSources禁用的那几条,禁用状态也会标出来。之前接手过一台构建机,包全在global-packages缓存里,本地还原长期不报错,换一台空缓存的CI机器第一次跑就炸NU1301,原因是项目根目录的NuGet.Config里留着一条两年前就下线的内网源。排查时先确认这条命令的输出,再用--configfile指定某一份配置、或者用-s直接给一个源覆盖掉所有继承来的配置,能很快判断问题出在配置层级还是网络。

一条被禁用的源也会出现在列表里,别漏看enabled那一列。

dotnet nuget list source
dotnet restore --configfile ./NuGet.Config -s https://api.nuget.org/v3/index.json

NU1301顺着报错里那个URL查

NU1301的完整报错是Unable to load the service index for source加一个地址,地址就是出问题的那条源。NuGet在还原时向每条源请求一个叫服务索引的JSON文档,取不到就直接停,哪怕要的包全在nuget.org上也不继续。常见成因不外乎几个:地址拼错或者域名解析不了,报错里跟着No such host is known;公司网络要走HTTPS_PROXY、HTTP_PROXY、NO_PROXY,代理变量没带进CI容器;内网HTTPS代理换了证书,机器不信任,报SSL connection could not be established;私有源如Azure Artifacts的凭据过期,要dotnet restore --interactive让凭据提供程序重新登录。实测内网一条拼错的feed地址能潜伏几个月,因为包都在本地缓存,直到清空obj重来才暴露。临时让构建继续跑可以加--ignore-failed-sources,它把NU1301降成NU1801警告,只要缺的包能从别的源拿到就放行;别把这个开关长期写进CI脚本,私有源真断了、包又只在它上面,构建会悄悄用别的源解析,产物不对还看不出来。

dotnet restore --ignore-failed-sources
dotnet restore --interactive

现场见过的坑是代理变量只在IDE里配了,命令行和CI容器都没有,同一份代码两处结果不一样。

NU1101查包名、版本和目标框架

NU1101说的是源里找不到这个包Id,可能是名字拼错、私有包没配对应的源、或者版本被下架。相邻的几个码要顺手分清:NU1102是包在但指定版本不存在,NU1202是包与项目目标框架不兼容,NU1605是检测到包降级、某条传递依赖把已解析的高版本往回压。见过把Newtonsoft.Json 13.0.1、13.0.2、13.0.3,写成13.0.0.3的,查了半天一直以为是源挂了,其实是手写版本号多打一位。开packageSourceMapping的项目还要看包名有没有被映射到某条源上,没匹配的包直接按找不到处理。目标框架也常出事,net6.0的项目去装只支持net8.0的包,报的是NU1202而不是NU1101,别按NU1101的方向查。

缓存污染与packages.lock.json

另一类NU1101跟源无关,是本地缓存里的元数据坏了,NuGet反复读一个错哈希。dotnet nuget locals all --list先把几个缓存目录列出来,只清HTTP缓存用dotnet nuget locals http-cache --clear,确认包本身坏了再动all --clear,后者会把global-packages里下载过的包全清掉,断网环境别随便跑。恢复还原用--no-cache绕开HTTP缓存、--force删掉project.assets.json重算依赖图,这两个参数常配合用。开了packages.lock.json的项目还多一层:--locked-mode不许改锁文件,改了csproj里的PackageReference版本却没更新锁文件,还原直接失败,本地先跑dotnet restore --force-evaluate重新生成锁文件再提交,别在CI上把--locked-mode摘掉绕过去。踩过一次的是容器镜像里带着旧obj目录,改了包版本还原还是用旧lock,查下来才发现挂载卷没清。

dotnet nuget locals all --list
dotnet nuget locals http-cache --clear
dotnet restore --no-cache --force

.NET SDK 8.0.100、9.0.100、10.0.100、10.0.401,和Visual Studio 17.8、17.9、17.10、17.11、17.12,几代工具的还原行为与报错措辞都有细微差别,--force-evaluate、--use-lock-file这类参数是逐步加进来的,老版本SDK不认新参数。查问题时先dotnet --version看落在哪一代,别拿新语法去套旧环境。

几个容易混的报错码

NU1101是包找不到,NU1102是版本不存在,NU1202是框架不兼容,NU1301是源不可达,NU1605是包降级,NU1801是--ignore-failed-sources把源失败降级后的警告,NU1900是漏洞检查那一步取不到数据给的警告,NETSDK1004是project.assets.json缺失、通常是上一次还原没成功留下的尾巴。一条实用的分法:报错里带URL和service index字样的往网络查,带包Id和版本号的往配置与依赖查,带Assets file的先删obj重来。这几个码混在一起报时,按第一条error定位,后面的多半是连带结果。

现场遇到过的组合是私有源凭据过期报NU1301,把--ignore-failed-sources加到CI脚本里,结果某个只在私有源上的包被公共源的同名包顶替,构建过了、产物不对。按报错码分头定位,比反复删obj和清缓存省时间。数据截至2026年11月。