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 檔案具有一項 rollForward 功能，可提供彈性的方式來指定可接受的版本範圍。例如，以下 global.json 檔案選擇了 10.0.100 或任何已安裝於機器上的 10.0 版本更新的功能頻帶或補丁：

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

你依賴 .NET SDK 中的兩個元件來搜尋 global.json 檔案。每個元件從不同位置開始，並透過祖先目錄往上搜尋：

.NET SDK muxer 處理 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 的預覽版選項，則預設值為true。否則，預設值為 false。

`rollForward`

類型: string
自 .NET Core 3.0 SDK 開始提供。

選取 SDK 版本時要使用的前滾策略，可以是在特定 SDK 版本遺失時作為後援，或是作為使用較新版本的指導。除非您將版本設定為 rollForward，否則必須以 latestMajor 值指定。預設向前移動行為取決於匹配規則。

若要了解可用的原則及其行為，請考慮下列 SDK 版本的定義格式 x.y.znn：

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（例如放在存放庫根目錄旁或自訂資料夾中），而非全域安裝於系統上。

「路徑」功能僅在使用與 .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 版本或 allowPrerelease 值，則會使用最高安裝的 SDK 版本 (相當於設定 rollForward 為 latestMajor)。是否考慮發行前版本 SDK 版本，取決於叫用 dotnet 的方式：
- 如果你不在Visual Studio中，則會考慮使用預發行版本。
- 如果你在 Visual Studio，它會使用所要求的預發布狀態。也就是說，如果你使用的是 Visual Studio 的預覽版，或者在 Tools>Options>Environment>Preview Features 中設定 使用 .NET SDK 的預覽版本 選項，則會考慮使用預發行版本；否則，僅使用發行版本。
如果找到未指定 SDK 版本但指定值的 allowPrerelease 檔案，則會使用最高安裝的 SDK 版本 (相當於設定 rollForward 為 latestMajor)。最新的 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 核心.NET命令列工具。
如果你使用 global.json 來維持特定版本的 .NET SDK，請注意 Visual Studio 只會安裝一份 .NET SDK 的副本。所以如果你升級 Visual Studio 版本，它會移除之前用來安裝新版本的 .NET SDK 版本。即使它屬於不同的主要 .NET 版本，舊版本也會被移除。

為避免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