Docfx 在 Linux 环境下找不到 .NET Core SDK 的解决方案

在 Linux 环境下使用 Docfx 工具生成文档时，可能会遇到一个常见问题：Docfx 无法找到已安装的 .NET Core SDK，即使通过 dotnet --info 命令确认 SDK 已正确安装。本文将深入分析这个问题的原因，并提供详细的解决方案。

问题现象

当在 Ubuntu 系统上运行 docfx 命令时，可能会收到如下错误信息：

System.IO.DirectoryNotFoundException: Could not find a part of the path '/usr/share/dotnet/packs/Microsoft.NETCore.App.Ref'
DocfxException: Cannot find .NET Core SDK to compile the project

尽管 dotnet --info 显示 SDK 已安装：

.NET SDK:
 Version:           8.0.300
 Commit:            326f6e68b2

根本原因

这个问题通常是由于 .NET SDK 安装不完整或安装过程中出现问题导致的。具体表现为缺少 /usr/share/dotnet/packs/ 目录及其内容，这个目录包含了 .NET Core 的引用程序集，是 Docfx 编译项目所必需的。

解决方案

完整卸载并重新安装 .NET SDK

1. 完全卸载现有 .NET 组件

sudo apt remove 'dotnet*'
sudo apt remove 'aspnetcore*'
sudo rm -rf /usr/share/dotnet/
sudo rm /etc/apt/sources.list.d/microsoft-prod.list

2. 清理系统并更新包列表

sudo apt-get autoremove
sudo apt-get update

3. 重新安装 .NET SDK

sudo apt-get install -y dotnet-sdk-8.0

验证安装

安装完成后，执行以下命令验证：

dotnet --info
ls /usr/share/dotnet/packs/

应该能看到完整的 .NET SDK 信息和 packs 目录下的内容。

预防措施

1. 使用官方推荐的安装方法：通过微软官方提供的安装脚本或文档指导进行安装，避免使用非官方源。

2. 检查安装完整性：安装后检查关键目录是否存在，特别是 /usr/share/dotnet/packs/。

3. 保持环境变量正确：确保 PATH 环境变量中包含 /usr/share/dotnet/。

技术背景

Docfx 依赖 .NET SDK 来完成以下工作：

• 解析 C# 源代码和项目文件
• 提取元数据信息
• 生成 API 文档

当 Docfx 无法找到 SDK 中的引用程序集时，就无法完成这些工作，导致构建失败。packs 目录包含了 .NET 的共享框架和引用程序集，是 SDK 的重要组成部分。

通过完整的卸载和重新安装，可以确保所有必要的组件都正确安装到位，解决 Docfx 找不到 SDK 的问题。