如何排查 dotnet restore 的速度问题

🔍 dotnet restore 到底在做什么？

当你运行 dotnet restore 时，它本质上是在调用 MSBuild 的 Restore 目标，并交由 NuGet 来完成实际的包管理工作。核心流程如下：

1. 解析依赖图：NuGet 会读取项目文件（.csproj）中的 PackageReference，并分析所有直接和间接（传递）依赖项，构建出一个完整的依赖关系图。
2. 检查本地缓存：它会优先检查用户全局的 NuGet 包缓存（通常在 ~/.nuget/packages）。如果所有包都已存在，这一步会非常快。
3. 下载缺失包：对于缓存中不存在的包，NuGet 会从配置的包源（如 nuget.org 或私有仓库）下载它们。网络请求是主要耗时来源。
4. 执行安全验证：从 nuget.org 下载的包都带有数字签名。NuGet 会验证这些签名，并可能在线检查证书的吊销状态。如果网络受限，这个检查会等待超时。
5. 生成资产文件：最后，NuGet 会在项目的 obj 文件夹中生成一个 project.assets.json 文件。这个文件记录了所有依赖项及其资源路径，供后续的 build 或 run 命令使用。

🐢 导致延迟的常见“元凶”

根据运行环境，耗时可能由以下一个或多个因素叠加造成：

• 网络源不可达或响应慢：如果你配置的某个包源（尤其是旧的或私有的源）无法访问，NuGet 会进行多次重试，等待很长时间才会超时失败。有案例显示，这可能导致 Restore 进程卡住超过 1.5 小时。
• 包签名验证的在线检查：在隔离网络或防火墙严格的环境中，验证签名时发起的证书吊销检查请求会被阻塞，导致每个包都等待网络超时。一个典型的例子是，一个包的“添加”操作耗时 3 分钟，而本地包只需几毫秒。
• 特定 SDK 版本的性能回退：某些 .NET SDK 版本可能存在已知的性能问题。例如，有报告指出从 9.0.101 升级到 9.0.200 后，dotnet restore 从 2 秒变成了 1 分 41 秒，并消耗大量内存。
• IPv6 网络问题：在部分 Linux 环境（如 Ubuntu 24.04）中，NuGet 可能尝试通过 IPv6 连接，若网络配置不当，会导致连接挂起。将系统网络设置改为优先使用 IPv4 可以解决此问题。
• 磁盘 I/O 或 CPU 瓶颈：在 CI/CD 管道中，如果构建代理的磁盘 I/O 或 CPU 资源紧张，解压大量包和写入缓存文件也会变慢。

🛠️ 如何诊断：让 Restore 过程“开口说话”

要定位具体原因，需要让 dotnet restore 输出更详细的日志。

1. 使用详细日志运行 Restore
运行以下命令，并将输出重定向到文件以便分析：

dotnet restore --verbosity diagnostic > restore_diagnostic.log 2>&1

日志中会包含每个 HTTP 请求、缓存查找和签名验证的详细信息。可以搜索 NU1301（源不可达错误）、timeout、retry 等关键词来定位问题。

2. 生成并分析 MSBuild 二进制日志 (Binlog)
这是最强大的诊断工具，能完整记录构建/还原的时间线：

dotnet restore -bl:restore.binlog

生成 restore.binlog 文件后，可以使用 MSBuild Structured Log Viewer 工具打开它。它能以时间线形式展示每个 Target 和 Task 的耗时，让你精确看到时间花在了哪个环节（例如网络请求、签名验证或文件复制）。

3. 尝试禁用签名验证来排查
如果怀疑是签名验证导致的网络等待，可以尝试设置环境变量来禁用它（注意：这会降低安全性，仅建议用于诊断）：

# Windows (PowerShell)
$env:DOTNET_NUGET_SIGNATURE_VERIFICATION="false"; dotnet restore

# Linux / macOS
export DOTNET_NUGET_SIGNATURE_VERIFICATION=false
dotnet restore

如果恢复速度显著提升，基本可以确定问题根源在于网络受限环境下的证书检查。

💡 针对性的优化建议

• 精简包源：检查 NuGet.config，移除不再使用或不可达的包源。对于暂时不可用的源，可以临时使用 --ignore-failed-sources 选项。
• 清理并重建缓存：如果怀疑缓存损坏，可以清理所有 NuGet 本地缓存后重试：

  dotnet nuget locals all --clear
  dotnet restore
  

• 调整网络优先级：在出现 IPv6 相关挂起的系统上，尝试禁用 IPv6 或调整其优先级，强制使用 IPv4。
• 关注 SDK 版本：如果问题在升级 SDK 后出现，可以尝试回退到上一个稳定版本，或关注官方仓库（如 dotnet/sdk）的 Issue 以获取修复信息。

可以先运行一次带诊断日志的 restore，然后观察日志中是否有大量的重试或超时记录。如果想进一步分析具体的日志内容，可以发LLM看看。