dotnet restore或NuGet还原失败时，错误可能来自三套认证：HTTP代理、私有包源和目标平台账号。代理常返回407，包源常返回401或403，TLS错误则与CA、域名和系统时间有关。若不先分层，很容易把包源令牌改了很多次，真正的问题却是代理未认证。
一、NuGet还原会访问哪些地址
客户端先访问包源服务索引，再按索引返回的资源地址查询版本、元数据和包内容。私有源还可能使用重定向、对象存储或独立认证端点。因此浏览器打开包源首页，不能证明还原链路完整可用。
二、nuget.config为什么有多个层级
| 层级 | 典型范围 | 风险 |
|---|---|---|
| 计算机级 | 整台构建机 | 影响所有用户和任务 |
| 用户级 | 当前运行账号 | CI服务账号可能读取另一份 |
| 解决方案或目录级 | 特定项目树 | 可能被提交到仓库 |
| 命令显式指定 | 单次还原 | 路径与秘密需妥善管理 |
排查时应显示配置来源或逐步指定明确配置文件，避免修改了开发者用户配置，而CI实际以服务账号读取另一目录。
三、代理、包源和凭据要分开看
NuGet代理配置用于连接网络出口；包源配置决定访问哪些仓库；凭据提供程序或源凭据用于目标仓库认证。记录错误时应保留状态码和目标主机，但对Authorization、代理密码和签名URL做脱敏。
四、dotnet、nuget.exe和IDE是否完全一致
它们共享NuGet生态，但运行时、配置路径、凭据提供程序和系统网络栈可能不同。命令行成功而Visual Studio失败时，应比较实际工具版本、运行账号和配置来源；CI失败时还要检查Agent服务环境。不要只用IDE界面的一次操作下结论。
五、环境变量在哪里生效
代理环境变量必须存在于执行还原的进程中。终端里的变量不一定传给IDE、Jenkins、GitLab Runner或容器。对于.NET应用默认代理来源，可参考.NET HttpClient代理与连接池。
六、私有源凭据怎样保护
- 优先使用官方或组织支持的凭据提供程序；
- CI中使用受保护、掩码的秘密变量；
- 不要提交含明文密码的nuget.config；
- 限制用户配置文件的读取权限；
- 避免详细日志输出完整源URL查询参数。
七、证书报错检查哪个信任库
确认执行命令的操作系统、容器和.NET运行时实际使用的CA。企业代理如果进行受控TLS检查，需要把合法根证书安全分发到相应环境。不要通过关闭证书验证或改用HTTP源解决，包完整性和源身份验证同样重要。
TLS检查顺序见HTTPS代理证书错误排查。
八、缓存为什么会误导判断
本地全局包缓存可能让一次还原完全不访问网络。要验证代理时，可选用授权测试项目和一个缓存中不存在的无敏感包，或从诊断日志确认实际请求。不要为了测试在共享构建机粗暴删除全部缓存，这会影响其他任务并制造流量峰值。
九、NO_PROXY和内部包源
内部包源可能应直连，公共源则通过企业代理。应按客户端支持的语法配置精确域名，并测试服务索引及实际包地址。若内部源把下载重定向到另一个主机，绕过列表也需要按安全策略覆盖该真实目标。
十、常见错误的分层判断
- 407：代理认证、凭据或认证机制；
- 401/403：包源令牌、权限或凭据提供程序；
- NU1301等服务索引错误：继续检查DNS、连接、代理和源状态；
- TLS错误：系统时间、CA、证书链和域名；
- 超时：确定发生在连接、首字节还是包内容下载。
十一、排查流程
- 记录.NET SDK、NuGet客户端与系统版本；
- 列出包源和实际配置文件来源；
- 用同一运行账号执行最小restore；
- 区分407、401、TLS和下载超时；
- 确认服务索引后的真实下载主机；
- 验证内部源绕过与公共源代理路径；
- 清理临时凭据并重新执行受控验证。
十二、结论
NuGet还原问题需要同时看配置层级、网络出口和包源认证。先确认命令读取哪份nuget.config，再沿服务索引到包内容逐段验证，才能避免被缓存和IDE环境差异误导。
