在本地使用 global.json 路徑測試預發布的 .NET SDKs。

從 .NET 10 開始，global.json 檔案支援一個 sdk.paths 屬性，告訴 .NET CLI 在預設系統位置之外應該在哪裡尋找 SDK 安裝。這個功能讓你可以把預發布的 SDK 安裝到專案本地資料夾，並且只在你工作該專案時使用。這個過程不會修改系統層級的安裝，也不會改變你的機器層級或使用者層 PATH 級環境變數。（安裝腳本可能會暫時在目前的 shell 會話中更新 PATH ，但這種變更不會持續。）

無論你想嘗試新的語言功能、評估團隊的預覽版本，或是在 CI 中驗證你的開源函式庫與即將發布的 SDK 版本，sdk.paths 都提供一種安全且可逆的方法來實現。如果出了問題，你刪除一個資料夾，就會回到原點。

備註

本文全文以 .NET 11（撰寫時的預釋版本）作為範例。此功能 sdk.paths 適用於任何 SDK 版本，無論是預發布或穩定版，無論是現有或未來。在安裝指令裡替換11.0preview成你需要的版本和品質。

先決條件

.NET 10 或更新版本安裝在你的系統上，確保你的 dotnet 上的 PATH 主機是版本 10.0 或更新。主機是系統範圍內dotnet可供整台機器使用的執行檔。當您運行任意 dotnet 命令時，這個主機是第一個被啟動的：它會讀取 global.json，決定使用哪個 SDK 版本，然後將控制權交給該 SDK。在這篇教學文章中，你會利用該系統性主機引導 CLI 朝向本地安裝的預覽 SDK。
終端機或命令提示字元（bash、zsh、PowerShell 或命令提示字元）。
（可選）一個 Git 倉庫，你想要設定預發布版 SDK 的範圍。

這很重要

sdk.paths 功能需要 .NET 10 或更新版本 host（即你 dotnet 上的 PATH 執行檔）。如果你的系統整體主機是 .NET 8 或 .NET 9，它不會辨識 paths 屬性，會退回到預設解析度行為。你仍然可以透過直接呼叫 ./.dotnet/dotnet（或在 Windows 上用 .\.dotnet\dotnet）來使用本地 SDK，這樣可以繞過系統主機。

要驗證你的主機版本，請執行 dotnet --info 並尋找輸出頂部附近的主機區塊：

Host:
  Version:      10.0.0
  Architecture: x64
  Commit:       abc123def4

Version該行應該顯示10.0或之後。主機版本 並不是dotnet --version 所報告的 SDK 版本。如果主機顯示較舊版本（例如 8.0.x 或 9.0.x），請安裝 .NET 10+ 系統級別版本，以更新 PATH 上的 dotnet 主機。

sdk.paths 的運作方式

sdk.paths 屬性是一個包含資料夾路徑的 JSON 陣列，.NET 主機用來搜尋 SDK 的安裝位置。主機依照你列出的順序搜尋這些路徑，並使用第一個符合版本限制的 global.jsonSDK 。

兩個關鍵細節：

路徑是相對於global.json檔案位置來說的，而不是相對於您的目前工作目錄。 如果你的 global.json 位於 repo 根目錄，並且你指定了 ".dotnet"，主機會在 repo 根目錄的 .dotnet 資料夾中尋找 SDK，即使你從子目錄執行 dotnet 指令。
$host$ 是一個特殊的標記器代表系統範圍的 .NET 安裝目錄（即你dotnet 上 PATH 執行檔的位置）。當你想要系統 SDK 作為備援時，就把它納入 $host$ 陣列中。

備註

$host$ 標記與整個 paths 屬性僅被 .NET 10+ 主機識別。舊主機完全忽略這些問題——不會產生錯誤，而是跳過該屬性並回退到預設的 SDK 解析度。

例如，以下設定指示主機先在本地 .dotnet 資料夾中尋找 SDK，然後回退到系統安裝：

{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}

如果你在陣列中省略 $host$ ，主機只會搜尋你指定的目錄。如果沒有一個包含匹配的 SDK，指令就會失敗——當你想強制執行特定 SDK 存在時，這會很有用。

你可以列出超過兩個條目。例如，你可以分別為預覽版和穩定版 SDK 分開資料夾，並依序搜尋它們： [".dotnet-preview", ".dotnet-stable", "$host$"]。

步驟 1：在本地安裝預發布的 SDK

使用官方的 dotnet-install 腳本，將預發布的 SDK 下載到專案本地目錄中。這些腳本不需要管理員權限，也不會修改你的系統 PATH 或任何系統性安裝。

macOS / Linux
Windows （PowerShell）

curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

Invoke-WebRequest 'https://dot.net/v1/dotnet-install.ps1' -OutFile 'dotnet-install.ps1'
.\dotnet-install.ps1 -Channel 11.0 -Quality preview -InstallDir .dotnet

備註

如果腳本執行被系統的執行策略阻擋，請以以下方式執行安裝腳本： powershell -ExecutionPolicy Bypass -File .\dotnet-install.ps1 -Channel 11.0 -Quality preview -InstallDir .dotnet

（ --install-dir 或 -InstallDir）參數會把 SDK 放在你目前目錄裡的 .dotnet 資料夾裡。你的電腦上沒有其他地方寫入任何檔案。

小提示

這個 --quality 參數接受三個值： daily （最新的夜間建置）、 preview （最新的官方預覽版）和 GA （最新的穩定版版本）。你也可以用 --version 來安裝完全相同的 SDK 版本，例如 --version 11.0.100-preview.2.26159.112。

步驟二：將 .dotnet/ 加入 .gitignore

本地 SDK 安裝容量可能高達數百兆位元組。把它加入你的 .gitignore 檔案，以防止納入版本控制系統。

macOS / Linux
Windows （PowerShell）

echo '.dotnet/' >> .gitignore

Add-Content -Path .gitignore -Value '.dotnet/'

如果你的專案已經有 .gitignore，請確認在提交前 .dotnet/ 沒有被追蹤：

git status --ignored

備註

每位開發者（以及每個 CI 代理）都會獨立執行安裝腳本。這個 .dotnet 資料夾是本地快取，不是共用的產物。

步驟三：設定 global.json

在你的儲存庫根建立或更新一個 global.json 檔案。至少，您只需要 paths 屬性即可開始：

{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}

這會告訴主機先在本地 .dotnet 資料夾找 SDK，然後回退到系統安裝。不需要版本號——主機選擇他找到的最新 SDK。

為了更精確的控制，你可以鎖定最低版本並設定版本前移行為。

{
  "sdk": {
    "version": "11.0.100-preview.2.26159.112",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "$host$"],
    "errorMessage": "Required .NET SDK not found. Run the install-dotnet script for your platform to install it locally."
  }
}

以下是每個物業的特色：

房產	Purpose
`version`	專案要求的最低 SDK 版本。
`allowPrerelease`	允許主電腦在版本向前滾動時選擇預發行的 SDK 版本。在測試預覽時設定為 `true` 。
`rollForward`	控制主機在沒有確切版本時如何選擇新版 SDK。 `latestFeature` 允許在同一 Major.Minor 版本內向前轉至較新的功能頻段。
`paths`	目錄用來搜尋 SDK 安裝，依序排列。 `".dotnet"` 是本地資料夾; `"$host$"` 是系統預設值。
`errorMessage`	當找不到匹配的 SDK 時會顯示自訂訊息。用它來告訴貢獻者如何設定他們的環境。

小提示

將".dotnet"列在"$host$"之前表示本地的預發布 SDK 會優先。如果你想讓系統 SDK 在符合版本限制時勝出，就反過來排序。

小提示

改變主意了？請參考本文末尾的「清理」部分。系統檔案不會被動過。

快速入門：一體化指令

現在你已經了解每個步驟的功能，這裡有一個指令，可以一次執行步驟 1 到 3。把你作業系統的指令貼到專案根目錄的終端機裡。

macOS / Linux
Windows （PowerShell）

curl -sSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh \
  && bash /tmp/dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet \
  && rm /tmp/dotnet-install.sh \
  && echo '.dotnet/' >> .gitignore \
  && cat > global.json << 'EOF'
{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}
EOF
echo "Installed: $(.dotnet/dotnet --version)"

Invoke-WebRequest 'https://dot.net/v1/dotnet-install.ps1' -OutFile "$env:TEMP\dotnet-install.ps1"
& "$env:TEMP\dotnet-install.ps1" -Channel 11.0 -Quality preview -InstallDir .dotnet
Remove-Item "$env:TEMP\dotnet-install.ps1"
Add-Content -Path .gitignore -Value '.dotnet/'
@'
{
  "sdk": {
    "paths": [".dotnet", "$host$"]
  }
}
'@ | Set-Content -Path global.json
Write-Host "Installed: $(& .\.dotnet\dotnet.exe --version)"

步驟 4：建立團隊安裝腳本（可選）

當多人同時使用同一儲存庫時，便利腳本可以避免大家都必須記住安裝指令。在你的倉庫根目錄中，為每個平台建立一個腳本。這些腳本能安裝 SDK、建立 global.json、更新 .gitignore，並可選擇安裝工作負載——全部在一個步驟中完成。

install-dotnet.sh （macOS/Linux）：

macOS / Linux
Windows （PowerShell）

#!/usr/bin/env bash
set -e

# -------- Configuration --------
CHANNEL="11.0"
QUALITY="preview"
# Uncomment the workloads your project needs:
# WORKLOADS="maui wasm-tools"
# --------------------------------

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
INSTALL_DIR="$SCRIPT_DIR/.dotnet"

echo "Installing .NET $CHANNEL ($QUALITY) SDK to $INSTALL_DIR ..."

curl -sSL https://dot.net/v1/dotnet-install.sh -o "$SCRIPT_DIR/dotnet-install.sh"
chmod +x "$SCRIPT_DIR/dotnet-install.sh"
"$SCRIPT_DIR/dotnet-install.sh" --channel "$CHANNEL" --quality "$QUALITY" --install-dir "$INSTALL_DIR"
rm -f "$SCRIPT_DIR/dotnet-install.sh"

# Auto-detect the installed SDK version
SDK_VERSION="$("$INSTALL_DIR/dotnet" --version)"

# Create global.json with the installed version
cat > "$SCRIPT_DIR/global.json" << EOF
{
  "sdk": {
    "version": "$SDK_VERSION",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "\$host\$"],
    "errorMessage": "Required .NET SDK not found. Run ./install-dotnet.sh (macOS/Linux) or .\\\\install-dotnet.ps1 (Windows) to install it locally."
  }
}
EOF

# Ensure .dotnet/ is in .gitignore
if ! grep -qxF '.dotnet/' "$SCRIPT_DIR/.gitignore" 2>/dev/null; then
    echo '.dotnet/' >> "$SCRIPT_DIR/.gitignore"
fi

# Install workloads if configured
if [ -n "${WORKLOADS:-}" ]; then
    echo "Installing workloads: $WORKLOADS"
    # shellcheck disable=SC2086
    "$INSTALL_DIR/dotnet" workload install $WORKLOADS
fi

echo ""
echo "Done! SDK $SDK_VERSION installed to $INSTALL_DIR"
echo "Run 'dotnet --version' to verify."

$ErrorActionPreference = 'Stop'

# -------- Configuration --------
$Channel  = '11.0'
$Quality  = 'preview'
# Uncomment the workloads your project needs:
# $Workloads = @('maui', 'wasm-tools')
# --------------------------------

$scriptDir  = Split-Path -Parent $MyInvocation.MyCommand.Definition
$installDir = Join-Path $scriptDir '.dotnet'

Write-Host "Installing .NET $Channel ($Quality) SDK to $installDir ..."

$installerPath = Join-Path $scriptDir 'dotnet-install.ps1'
Invoke-WebRequest 'https://dot.net/v1/dotnet-install.ps1' -OutFile $installerPath
& $installerPath -Channel $Channel -Quality $Quality -InstallDir $installDir
Remove-Item $installerPath -ErrorAction SilentlyContinue

# Auto-detect the installed SDK version
$sdkVersion = & (Join-Path $installDir 'dotnet.exe') --version

# Create global.json with the installed version
@"
{
  "sdk": {
    "version": "$sdkVersion",
    "allowPrerelease": true,
    "rollForward": "latestFeature",
    "paths": [".dotnet", "`$host`$"],
    "errorMessage": "Required .NET SDK not found. Run ./install-dotnet.sh (macOS/Linux) or .\\install-dotnet.ps1 (Windows) to install it locally."
  }
}
"@ | Set-Content -Path (Join-Path $scriptDir 'global.json') -Encoding UTF8

# Ensure .dotnet/ is in .gitignore
$gitignorePath = Join-Path $scriptDir '.gitignore'
if (!(Test-Path $gitignorePath) -or !(Select-String -Path $gitignorePath -Pattern '^\s*\.dotnet/\s*$' -Quiet)) {
    Add-Content -Path $gitignorePath -Value '.dotnet/'
}

# Install workloads if configured
if ($Workloads) {
    Write-Host "Installing workloads: $($Workloads -join ', ')"
    & (Join-Path $installDir 'dotnet.exe') workload install @Workloads
}

Write-Host ""
Write-Host "Done! SDK $sdkVersion installed to $installDir"
Write-Host "Run 'dotnet --version' to verify."

讓 shell 腳本可執行，並將兩個腳本都加入你的儲存庫：

chmod +x install-dotnet.sh
git add install-dotnet.sh install-dotnet.ps1

有了這些已納入的腳本，errorMessageglobal.json 可以指示貢獻者執行適合他們平台的腳本。新團隊成員會複製倉庫，執行腳本，準備開始建置——不需要手動安裝 SDK 步驟。

步驟五：驗證安裝狀況

從包含你 global.json （或任何子目錄）的目錄中，執行以下指令以確認主機正在解析本地的預發布 SDK：

dotnet --version

輸出應該會顯示你安裝的預發布版本，例如：

11.0.100-preview.2.26159.112

想更詳細了解是哪個 SDK 被解析以及載入來源，請執行：

dotnet --info

在輸出中尋找 基底路徑 線。它應該指向與你的專案相關的.dotnet資料夾，以確認正在使用本地安裝。

備註

如果輸出顯示的是你的系統 SDK 版本而非預發布版本，請檢查以下事項：

Host 版本與 SDK 版本：Host 版本（在 dotnet --infoHost 標題下顯示）決定是否可以理解 paths。必須是 10.0 或更高。 SDK 版本（以 dotnet --version表示）是主機程序 global.json後解決的版本。
該 global.json 檔案位於你目前工作目錄的父目錄中。
資料夾 .dotnet 包含完整的 SDK 安裝（檢查是否有 sdk 子資料夾）。

步驟 6：在本地 SDK 安裝工作負載（可選）

安裝本地 SDK 後，你可以在上面安裝像是 .NET MAUI 或 Blazor WebAssembly AOT 這類可選的工作負載。本地 SDK 上安裝的工作負載完全獨立於系統整體安裝的工作負載。

安裝一個工作負載

務必從包含你 global.json （或其子目錄）的資料夾執行這個。直接使用本地 dotnet 二進位檔來確保工作負載安裝在本地 SDK 中，而非系統安裝：

macOS / Linux
Windows （PowerShell）

./.dotnet/dotnet workload install maui

.\.dotnet\dotnet.exe workload install maui

這很重要

工作負載指令時，務必使用 ./.dotnet/dotnet（或在 Windows 上使用 .\.dotnet\dotnet）。這個global.jsonpaths功能正確路由指令，例如dotnet build和dotnet run，以正確執行SDK解析，但 workload 指令會將元資料存儲在執行它們的主機的dotnet根目錄下。當你使用系統主機時，工作負載會被放在系統安裝中，而非本地安裝。這是一個已知的缺口，涉及sdk.paths與DOTNET_ROOT之間的互動。直接使用本地二進位檔，確保工作負載能安裝並追蹤在正確的位置。

備註

在 macOS 和 Linux 上，使用本地 SDK 時不需要sudo工作負載安裝。該 .dotnet/ 資料夾是使用者擁有的，因此所有工作負載檔案都是以你正常的使用者權限寫入的。這與系統性安裝不同，後者可能需要提升權限。

常見工作負載

下表列出常用的工作負載：

[工作負載]	安裝指令
.NET MAUI	`./.dotnet/dotnet workload install maui`
ASP.NET Core （Blazor WASM AOT）	`./.dotnet/dotnet workload install wasm-tools`

你可以在一個指令中安裝多個工作負載：

macOS / Linux
Windows （PowerShell）

./.dotnet/dotnet workload install maui wasm-tools

.\.dotnet\dotnet.exe workload install maui wasm-tools

驗證已安裝的工作負載

要查看本地 SDK 上安裝了哪些工作負載：

macOS / Linux
Windows （PowerShell）

./.dotnet/dotnet workload list

.\.dotnet\dotnet.exe workload list

小提示

安裝在本地 SDK 上的工作負載會儲存在目錄 .dotnet/ 中。刪除目錄會移除 SDK 及其所有工作負載。共享下載快取（例如 ~/.nuget/packages）可能會保留，但不會影響你的系統。

步驟7：在CI中使用預發布的SDK（可選）

同樣的方法也適用於持續整合流程。不過，CI 執行器可能沒有預裝 .NET 10+ 主機，所以你必須先確定主機有空，再依賴 sdk.paths。

GitHub Actions 範例

以下工作流程是使用 actions/setup-dotnet 安裝一台 .NET 10 主機，然後在本地安裝 .NET 11 預覽版 SDK。 setup-dotnet 步驟確保執行者在 PATH 上有一個 .NET 10+ 的主機，能讀取 paths 中的 global.json 屬性。

name: Build with preview SDK

on: [push, pull_request]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]

    steps:
      - uses: actions/checkout@v4

      - name: Install .NET 10 host
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'
          dotnet-quality: 'preview'

      - name: Cache local SDK
        uses: actions/cache@v4
        with:
          path: .dotnet
          key: dotnet-local-${{ matrix.os }}-${{ hashFiles('global.json') }}

      - name: Install .NET 11 preview SDK locally
        # Use bash shell explicitly — Windows runners default to PowerShell,
        # which doesn't support the curl/chmod/shell-script syntax below.
        shell: bash
        run: |
          curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
          chmod +x dotnet-install.sh
          ./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

      - name: Build
        run: dotnet build

      - name: Test
        run: dotnet test

因為global.json在你的儲存庫裡已經有paths設定，dotnet build和dotnet test步驟會自動取得本地 SDK。不需要更改 CI 代理的全系統安裝。

小提示

此步在執行間快取 .dotnet/ 目錄，以作業系統和 global.json 的雜湊值為鍵。當你在 global.json 中更新 SDK 版本時，系統會自動更新快取。

備註

該區段在 strategy.matrix 多個作業系統上執行建置。你可以在安裝步驟中加入 sdk-version 一個維度，將矩陣擴展到針對多個 SDK 版本進行測試。

備用：直接使用本地主機

如果你無法在運行器上安裝.NET 10+（例如在鎖定的 CI 環境中），請直接呼叫本地 SDK 的主機，而不是依賴系統本身 dotnet：

- name: Install .NET 11 preview SDK locally
  run: |
    curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
    chmod +x dotnet-install.sh
    ./dotnet-install.sh --channel 11.0 --quality preview --install-dir .dotnet

- name: Build using local host
  run: ./.dotnet/dotnet build

- name: Test using local host
  run: ./.dotnet/dotnet test

這種方法完全繞過系統主機，且不需要 sdk.paths 解析——本地 dotnet 執行檔知道自己的 SDK 在哪裡。

局限性

此功能 sdk.paths 有幾個限制需要注意：

需要一個.NET 10 或更新版本的主機PATH。 dotnet讀取global.json的執行檔必須是版本 10.0 或更新版本。如果主機較舊，則完全忽略該 paths 屬性。
僅適用於 SDK 指令。 該 paths 屬性影響 SDK 對指令的解析，如 dotnet build、 dotnet run和 dotnet test。它不影響應用程式主機解析度或依賴框架的執行（例如， dotnet myapp.dll）。
路徑是相對於 global.json 位置的。 如果你移動檔案 global.json ，請相應更新路徑。絕對路徑也可行，但會降低跨機器的可攜性。

清除

移除本地預發布 SDK 需要兩個步驟：

刪除本地的 SDK 資料夾：
- macOS / Linux
- Windows （PowerShell）
```
rm -rf .dotnet/
```
```
Remove-Item -Recurse -Force .dotnet
```

移除 paths 屬性，或如果不再需要 global.json，就刪除檔案。你的專案會切換回使用系統全域的 SDK。

因為一切都是專案本地——包括你安裝的任何工作負載——所以沒有登錄檔、環境變數或系統檔案需要清理。只要移除資料夾並將 global.json 還原就可以。本地 SDK 上安裝的工作負載會一起刪除，包括 .dotnet/ 資料夾。

下一步

global.json 概述 — 所有 global.json 屬性的完整參考資料，包括 version、 rollForward、 allowPrerelease和。
dotnet-install 腳本參考 — 跨平台安裝腳本的完整參數列表。
.NET SDK 概述 — 了解 SDK 版本管理、轉期政策，以及主機如何解析 SDK。
如何選擇使用.NET版本 — 詳細說明.NET主機如何解析 SDK 與執行時版本。
.NET 11 有什麼新內容 — .NET 11 的新功能與改進概述。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-09