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 檔案會選擇 8.0.300 或更新的特性群組或修補程式，適用於電腦上已安裝的 8.0 版本：

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

.NET SDK 工具會在目前的工作目錄 (這不一定與專案目錄相同) 或其中一個上層目錄中尋找 global.json 檔案。

如需指定執行時間版本而非 SDK 版本的相關資訊，請參閱目標架構。

global.json 結構描述

`sdk`

類型:object

指定要選取的 .NET SDK 的相關資訊。

`version`

類型:string

要使用的 .NET SDK 版本。

這個欄位：

沒有萬用字元支援；也就是說，您必須指定完整版本號碼。
不支援版本範圍。

`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 Preview 3 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 Preview 3 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."
  }
}

下列範例示範如何指定 Microsoft.Testing.Platform 為測試執行器：

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

global.json 和 .NET CLI

若要在 global.json 檔案中設定 SDK 版本，了解電腦上安裝的 SDK 版本會很有幫助。如需如何執行這項操作的資訊，請參閱如何檢查 .NET 是否已安裝。

若要在機器上安裝其他 .NET SDK 版本，請造訪下載 .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 的預覽版本，或是設定 [使用 .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 Core .NET 命令列工具。
如果您使用 global.json 維持特定版本的 .NET SDK，須留意 Visual Studio 只會安裝 .NET SDK 的單一複本。因此，如果升級 Visual Studio 版本，將會移除先前用來安裝新版本的舊版 .NET SDK。即使是不同的主要 .NET 版本，舊版本也會被移除。

若要避免 Visual Studio 移除 .NET SDK 的版本，請從下載頁面安裝獨立 .NET SDK。不過，如果您這麼做，則就無法再透過 Visual Studio 取得該 .NET SDK 版本的自動更新，而且可能會面臨安全性問題的風險。

另請參閱

解析專案 SDK 的方式

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-22

共用方式為

global.json 概觀

global.json 結構描述

sdk

version

allowPrerelease

rollForward

paths

errorMessage

msbuild-sdks

test

runner