DocFX构建时持续提示“No .NET API detected for project”问题求助

常见原因及对应解决方法 #

• 项目配置路径错误
  检查docfx.json里metadata节点的src路径是否指向正确的.NET项目文件（.csproj/.vbproj），相对路径要确保是相对于docfx.json的位置。比如：

  "metadata": [
    {
      "src": [
        {
          "files": ["**/*.csproj"],
          "src": "../MyDotNetProject"
        }
      ],
      "dest": "api"
    }
  ]
  

  确认路径拼写正确，能正常找到目标项目。

• 项目未完成编译
  DocFX依赖项目的编译输出提取API元数据，先手动构建项目：

  dotnet build
  

  确保编译无错误后，再执行docfx docfx.json --serve。

• DocFX与.NET SDK版本不兼容
  部分DocFX版本对.NET 6+项目的支持需要匹配的SDK版本。如果是全局工具安装的DocFX，尝试更新到最新稳定版：

  dotnet tool update -g docfx
  

  若存在版本适配问题，可降级到与项目SDK兼容的DocFX版本。

• 默认项目的API配置缺失
  用docfx init生成的默认项目，若docfx.json里没有metadata配置项，手动添加指向示例项目的路径配置，确保能识别到.NET项目文件。

• GitHub Pages构建环境依赖不足
  在GitHub Actions构建脚本中，先安装对应版本的.NET SDK，再完成项目编译，最后执行DocFX构建。示例Workflow片段：

  - name: Setup .NET
    uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '8.x' # 替换为你的项目SDK版本
  
  - name: Build .NET Project
    run: dotnet build ./path/to/your/project.csproj --configuration Release
  
  - name: Build DocFX Site
    run: docfx docfx.json
  

内容的提问来源于stack exchange，提问作者Tea-F-Tea