global.json 概述

本文适用于： ✔️ .NET Core 3.1 SDK 及更高版本

使用 global.json 文件可以定义运行 .NET CLI 命令时使用哪个.NET SDK 版本。选择.NET SDK 版本与指定项目目标的运行时版本无关。 .NET SDK 版本指示使用哪个版本的 .NET CLI。本文介绍如何使用 global.json 选择 SDK 版本。

如果始终想要使用计算机上安装的最新 SDK 版本，则不需要 global.json 文件。但在 CI（持续集成）方案中，通常需要为使用的 SDK 版本指定可接受的范围。 global.json 文件具有功能，它提供灵活的方法来指定可接受的版本范围。例如，以下 global.json 文件用于为计算机上安装的 10.0.100 或任何更高版本中 10.0 的特性版本或补丁进行选择：

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  }
}

依赖于 .NET SDK 中的两个组件来搜索 global.json 文件。每个组件都从不同的位置开始，并向上搜索祖先目录。

.NET SDK 多路复用器处理dotnet CLI 命令。它从当前工作目录开始，这不一定与项目目录相同。
.NET MSBuild 项目 SDK 解析程序在生成过程中解析项目 SDK。它从包含解决方案文件的目录（如果存在）开始。如果不存在解决方案文件，则从包含当前项目文件的目录开始。如果两个文件都不存在，则使用当前工作目录。

有关指定运行时版本而不是 SDK 版本的信息，请参阅目标框架。

global.json 架构

`sdk`

类型：object

指定要选择.NET SDK 的信息。

`version`

类型：string

要使用的.NET SDK 的版本。

此字段：

需要完整版本号，例如 10.0.100。
不支持 10、10.0 或 10.0.x 等版本号。
不支持通配符。
不支持版本范围。

`allowPrerelease`

类型：boolean
自以下版本起提供：.NET Core 3.0 SDK。

指示在选择要使用的 SDK 版本时，SDK 解析程序是否应考虑预发布版本。

如果未显式设置此值，则默认值取决于是否从Visual Studio运行：

如果不在使用Visual Studio，则默认值为 true。
如果您在使用 Visual Studio，它会使用请求的预发行版状态。也就是说，如果使用 Visual Studio 预览版，或者设置 使用 .NET SDK 的预览选项（在 Tools>Options>Environment>Preview Features）默认值为 true。否则，默认值为 false。

`rollForward`

类型：string
自以下版本起提供：.NET Core 3.0 SDK。

选择 SDK 版本时要使用的前滚策略，可作为特定 SDK 版本缺失时的回退，或者作为使用更高版本的指令。必须为版本指定一个 rollForward 值，除非将其设置为 latestMajor。默认的前滚行为由匹配规则确定。

要了解可用策略及其行为，请考虑以下格式为 x.y.znn 的 SDK 版本定义：

x 是主版本。
y 是次版本。
z 是功能区段。
nn 是修补程序版本。

下表列出了 rollForward 键的可能值：

Value	Behavior
`patch`	使用指定的版本。如果找不到，则前滚到最新的修补程序级别。如果找不到，则失败。此值是早期 SDK 版本中的旧行为。
`feature`	对指定的主版本、次版本和功能区段使用最新的修补程序级别。如果找不到，则前滚到同一主/次版本中的下一个较高功能区段，并使用该功能区段的最新修补程序级别。如果找不到，则失败。
`minor`	对指定的主版本、次版本和功能区段使用最新的修补程序级别。如果找不到，则前滚到同一主/次版本中的下一个较高功能区段，并使用该功能区段的最新修补程序级别。如果找不到，则前滚到同一主版本中的下一个较高次版本和功能区段，并使用该功能区段的最新修补程序级别。如果找不到，则失败。
`major`	对指定的主版本、次版本和功能区段使用最新的修补程序级别。如果找不到，则前滚到同一主/次版本中的下一个较高功能区段，并使用该功能区段的最新修补程序级别。如果找不到，则前滚到同一主版本中的下一个较高次版本和功能区段，并使用该功能区段的最新修补程序级别。如果找不到，则前滚到下一个较高主版本、次版本和功能区段，并使用该功能区段的最新修补程序级别。如果找不到，则失败。
`latestPatch`	使用安装的最新修补程序级别，该级别与请求的主版本、次版本和功能区段匹配，并且该修补程序级别大于或等于指定的值。如果找不到，则失败。
`latestFeature`	使用安装的最高功能区段和修补程序级别，其与请求的主版本和次版本匹配，并且该功能区段和修补级别大于或等于指定的值。如果找不到，则失败。
`latestMinor`	使用安装的最高次版本、功能区段和修补程序级别，其与请求的主版本匹配，并且该次版本、功能区段和修补级别大于或等于指定的值。如果找不到，则失败。
`latestMajor`	使用安装的最高.NET SDK，其版本大于或等于指定值。如果找不到，则失败。
`disable`	不前滚。必须完全匹配。

`paths`

类型：string 的数组
自以下版本起提供：.NET 10 SDK。

指定搜索兼容.NET SDK 时应考虑的位置。路径可以是绝对路径，也可以是相对 global.json 文件位置的相对路径。特殊值 $host$ 表示与正在运行 dotnet 的可执行文件对应的位置。

按照定义的顺序搜索这些路径，并使用第一个匹配的 SDK。

此功能允许使用本地 SDK 安装（如相对于仓库根目录的 SDK 或放置在自定义文件夹中的 SDK），这些安装并未在系统上进行全局安装。

仅当使用与 .NET SDK 交互的命令（如 dotnet run）时，“路径”功能才有效。它不会影响运行本机 apphost 启动器（app.exe）、运行 dotnet app.dll或运行 dotnet exec app.dll等方案。若要使用“路径”功能，必须使用 SDK 命令，例如 dotnet run。

`errorMessage`

类型：string
自以下版本起提供：.NET 10 SDK。

指定 SDK 解析程序找不到兼容的.NET SDK 时显示的自定义错误消息。

`msbuild-sdks`

类型：object

可便于在一个位置（而不是在各个项目中）控制项目 SDK 版本。有关详细信息，请参阅如何解析项目 SDK。

`test`

类型：object

指定有关测试的信息。

`runner`

类型：string
自以下版本起提供：.NET 10.0 SDK。

用于发现和运行测试的测试运行器。

global.json 中的注释

global.json 文件中的注释支持使用 JavaScript 或 C# 样式的注释。例如：

{
   // This is a comment.
  "sdk": {
    "version": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Examples

以下示例演示如何禁止使用预发行版版本：

{
  "sdk": {
    "allowPrerelease": false
  }
}

下面的示例展示了如何使用安装的最高版本，此版本大于或等于指定的版本。所示的 JSON 不允许任何低于 7.0.200 的 SDK 版本，而允许 7.0.200 或任何更高版本（包括 8.0.xxx）。

{
  "sdk": {
    "version": "7.0.200",
    "rollForward": "latestMajor"
  }
}

下面的示例演示如何使用完全指定的版本：

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "disable"
  }
}

下面的示例展示了如何使用特定主要版本和次要版本的已安装最新功能区段和修补程序版本。所示的 JSON 不允许任何低于 8.0.302 的 SDK 版本，而允许 8.0.302 或任何更高的 8.0.xxx 版本（如 8.0.303 或 8.0.402）。

{
  "sdk": {
    "version": "8.0.302",
    "rollForward": "latestFeature"
  }
}

下面的示例展示了如何使用特定版本的已安装最高修补程序版本。所示的 JSON 不允许任何低于 8.0.102 的 SDK 版本，而允许 8.0.102 或任何更高的 8.0.1xx 版本（如 8.0.103 或 8.0.199）。

{
  "sdk": {
    "version": "8.0.102",
    "rollForward": "latestPatch"
  }
}

以下示例演示如何指定其他 SDK 搜索路径和自定义错误消息：

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

以下示例显示了指定的无效版本。命令 dotnet --info 的输出显示错误消息：“版本'10.0'对'sdk/version'值无效。

{
  "sdk": {
    "version": "10.0",
    "rollForward": "latestFeature"
  }
}

以下示例演示如何指定 Microsoft.Testing.Platform 为测试运行程序：

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

global.json 和 .NET CLI

若要在 global.json 文件中设置 SDK 版本，最好能知道计算机上安装了哪些 SDK 版本。有关如何执行此作的信息，请参阅如何检查是否已安装.NET。

若要在计算机上安装其他.NET SDK 版本，请访问 Download .NET 页。

可执行 dotnet new 命令，在当前目录中创建一个新的 global.json 文件，如下例所示：

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

匹配规则

Note

匹配规则由 dotnet.exe 入口点控制，该入口点在所有已安装.NET运行时中都是常见的。如果并行安装多个运行时，或者使用的是 global.json 文件，则使用.NET运行时的最新安装版本的匹配规则。

在确定要使用的 SDK 版本时，以下规则适用：

如果未找到 global.json 文件，或者 global.json 未指定 SDK 版本和值，则使用安装的最高 SDK 版本（相当于将设置为 allowPrerelease）rollForwardlatestMajor。是否考虑 SDK 预发布版本取决于 dotnet 的调用方式：
- 如果你不在 Visual Studio 中，将考虑预发行版版本。
- 如果您在使用 Visual Studio，它会使用请求的预发行版状态。也就是说，如果使用 Visual Studio 预览版，或者设置 使用 .NET SDK 的预览选项（在 Tools>Options>Environment>Preview Features），则考虑预发行版本；否则，仅考虑发布版本。
如果找到了未指定 SDK 版本但指定了值的 global.json 文件，则使用安装的最高 SDK 版本（相当于将 allowPrerelease 设置为 rollForward）。最新 SDK 版本是发布版本还是预发布版本取决于 allowPrerelease 的值。 true 指示考虑预发布版本；false 指示仅考虑发布版本。
如果找到 global.json 文件，并且该文件指定了 SDK 版本：
- 如果未设置 rollForward 值，它将使用 patch 作为默认 rollForward 策略。否则，请在 rollForward 部分中检查每个值及其行为。
- 有关是否考虑预发布版本以及未设置 allowPrerelease 时的默认行为的信息，请参阅 allowPrerelease 部分。

针对生成警告的疑难解答

以下警告指示项目是使用 .NET SDK 的预发行版编译的：

你使用的是 .NET 的预览版。请参阅：https://aka.ms/dotnet-support-policy

.NET SDK 版本具有高质量的历史和承诺。但是，如果不希望使用预发布版本，请在 allowPrerelease 部分中查看可以使用的各种策略。对于从未安装过 .NET Core 3.0 或更高版本的运行时或 SDK 的计算机，需要创建 global.json 文件并指定要使用的确切版本。
以下警告指示项目面向 EF Core 1.0 或 1.1，这与 .NET Core 2.1 SDK 及更高版本不兼容：

启动项目 '{startupProject}' 面向框架 '.NETCoreApp' 的版本 '{targetFrameworkVersion}'。此版本的Entity Framework Core .NET命令行工具仅支持版本 2.0 或更高版本。有关使用旧版工具的信息，请参阅 https://go.microsoft.com/fwlink/?linkid=871254。

从 .NET Core 2.1 SDK（版本 2.1.300）开始，dotnet ef 命令包含在 SDK 中。若要编译项目，请在计算机上安装 .NET Core 2.0 SDK（版本 2.1.201）或更早版本，并使用 global.json 文件定义所需的 SDK 版本。有关 dotnet ef 命令的详细信息，请参阅 EF Core .NET 命令行工具。
如果使用 global.json保留特定版本的 .NET SDK，请注意，Visual Studio只安装.NET SDK 的单个副本。因此，如果升级Visual Studio版本，它将删除用于安装新版本的 .NET SDK 的早期版本。即使旧版本属于不同的主版本，仍会删除它。

为了避免Visual Studio删除 .NET SDK 的版本，请从 download 页面安装独立.NET SDK。但是，如果这样做，则不再通过Visual Studio获得该版本的 .NET SDK 自动更新，并且可能会面临安全问题的风险。

另请参阅

如何解析 SDK 项目

反馈

此页面是否有帮助？

Last updated on 2026-03-11

通过

global.json 概述

global.json 架构

sdk

version

allowPrerelease

rollForward

paths

errorMessage

msbuild-sdks

test

runner