疑難排解應用程式啟動失敗問題

本文說明應用程式啟動失敗的一些常見原因和可能的解決方案。 它與 框架相依的應用程式相關，這些應用程式依賴於您機器上的 .NET 安裝。

如果您已經知道需要哪個 .NET 版本，您可以從 .NET 下載下載。

找不到 .NET 安裝

如果找不到 .NET 安裝，應用程式將無法啟動，並顯示類似以下內容的訊息：

You must install .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Host version: 7.0.0
.NET location: Not found

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

這可能是由於 包裹混淆造成的。

全域安裝皆註冊於 /etc/dotnet/install_location。 在某些系統中，也包含架構特定的檔案，例如 /etc/dotnet/install_location_arm64。

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

全域安裝皆註冊於 /etc/dotnet/install_location。 在某些系統中，也包含架構特定的檔案，例如 /etc/dotnet/install_location_arm64。

錯誤訊息包含下載 .NET 的連結。 您可以點擊該鏈接進入相應的下載頁面。 您也可以從 .NET 下載 中選擇由 Host version 指定的 .NET 版本。

在所需 .NET 版本的 下載頁面 上，尋找符合錯誤訊息中所列架構的 .NET 執行階段 下載。 然後，您可以通過下載並運行 安裝程序來安裝它。

.NET 可透過各種 Linux 套件管理員取得。 如需詳細資訊，請參閱 在 Linux 上安裝 .NET。 （.NET 的預覽版通常無法透過套件管理員取得。

您必須安裝適當版本的 .NET Runtime 套件，例如 dotnet-runtime-10.0。

或者，在所需 .NET 版本的 下載頁面 上，您可以下載指定架構的 二進位檔 。

找不到必要的架構

如果找不到必要的架構或相容版本，應用程式將無法啟動，並顯示類似以下訊息：

You must install or update .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: C:\Program Files\dotnet\

The following frameworks were found:
  6.0.2 at [c:\Program Files\dotnet\shared\Microsoft.NETCore.App]

You must install or update .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]

You must install or update .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/local/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

錯誤會指出遺失架構的名稱、版本和架構，以及預期安裝的位置。 若要執行應用程式，您可以在指定的「.NET 位置」安裝 相容的執行階段 。 如果應用程式的目標版本低於您已安裝的版本，而您想要在較高版本上執行它，您也可以設定應用程式的 前滾行為 。

安裝相容的執行階段

錯誤訊息包含下載遺失架構的連結。 您可以點擊此連結進入適當的下載頁面。

或者，您也可以從 .NET 下載 頁面下載執行階段。 有多個可供下載的 .NET 執行階段。

下表顯示每個執行階段所包含的架構。

執行階段下載 包含的框架
ASP.NET 核心執行階段 Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET 桌面執行階段 Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
.NET 運行時間 Microsoft.NETCore.App
執行階段下載 包含的框架
ASP.NET 核心執行階段 Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET 運行時間 Microsoft.NETCore.App

選取包含遺漏架構的執行階段下載，然後安裝它。

在所需 .NET 版本的 下載頁面 上，尋找符合錯誤訊息中所列架構的執行階段下載。 您可能想要下載 安裝程式。

.NET 可透過各種 Linux 套件管理員取得。 如需詳細資訊，請參閱 在 Linux 上安裝 .NET 。 （.NET 的預覽版通常無法透過套件管理員取得。

您必須安裝適當版本的 .NET 執行階段套件，例如 dotnet-runtime-10.0 或 aspnetcore-runtime-10.0。

或者，在所需 .NET 版本的 下載頁面 上，您可以下載指定架構的 二進位檔 。

在大部分情況下，當無法啟動的應用程式使用這類安裝時，錯誤訊息中的「.NET 位置」會指向：

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

檢查DOTNET_ROOT環境變數

DOTNET_ROOT環境變數告訴應用程式在哪裡可以找到dotnet驅動程式以及所需的框架。 如果這個變數設定錯誤，或指向沒有有效安裝 .NET 的位置，應用程式即使安裝在機器其他地方，.NET 也無法啟動。

需留意的常見問題：

  • 變數指向錯誤位置——DOTNET_ROOT可能設定為先前 .NET 安裝、CI 環境或已不再反映當前安裝位置的腳本路徑。
  • 變數在不應設定時卻被設定 — 如果環境中已設定 DOTNET_ROOT，.NET 就會完全略過預設的安裝位置。 如果 .NET 移動了，請移除或更新變數。
  • 架構不匹配 — 在 64 位元機器上執行 32 位元應用程式時，請使用架構專用變體。 例如，設定 DOTNET_ROOT_X86 指向 32 位元安裝。 欲了解更多資訊，請參閱 DOTNET_ROOT 環境變數。

診斷時，列印變數目前值並確認它指向一個包含有效 .NET 安裝的目錄：

echo $env:DOTNET_ROOT

echo $DOTNET_ROOT

如果變數已設定，請確認路徑是否存在且包含預期的 .NET 版本。 如果變數沒有設定，.NET 會退回到你平台的預設安裝位置。

請檢查安裝地點

在 Windows 上，.NET 只會搜尋一個位置——也就是第一個發現 .NET 安裝的位置。 如果框架查詢失敗，請確認 .NET 已安裝在預期位置。

當你透過 dotnet 執行應用程式時，系統會在相對於 dotnet 的子目錄中搜尋框架。 當你透過執行檔apphost執行應用程式時，.NET 會依序搜尋以下位置，並使用第一個安裝位置：

  1. 相對於 DOTNET_ROOT 環境變數（若設定）的子目錄。
  2. HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation 中的全域註冊安裝位置（如果已設定）。
  3. 預設安裝位置：%ProgramFiles%\dotnet（或在 64 位元 Windows 上供 32 位元程序使用的 %ProgramFiles(x86)%\dotnet）。

如果 .NET 安裝在非預設位置，請確保DOTNET_ROOT指向該位置，讓應用程式能找到正確的安裝位置。

執行 dotnet-install 腳本

當你需要快速且非管理員的安裝時，例如在 CI 情境或臨時環境中，使用 dotnet-install 腳本。

腳本會把 .NET 安裝到你選擇的資料夾裡。 它的行為不像標準作業系統安裝程式，會建立一個私有安裝程式。

若要從該私有安裝執行應用程式，當您透過可執行檔啟動時（稱為 apphost），請設定 DOTNET_ROOT（或架構特定的變體） 環境變數；或者從相同的安裝位置透過相符的 dotnet 主機啟動。

關於 Windows 上的安裝步驟，請參見使用 PowerShell 安裝。

關於 Linux 上的安裝步驟，請參見「用腳本安裝 .NET」。

如需 macOS 的安裝步驟，請參閱 使用指令碼安裝 .NET。

關於腳本選項與行為細節，請參見 dotnet-install 腳本參考。

下載二進位檔

您可以從 下載頁面下載 .NET 的二進位封存。 從執行階段下載的 [二進位檔 ] 資料行中，下載符合所需架構的二進位檔版本。 將下載的存檔解壓縮到錯誤訊息中指定的「.NET 位置」。

如需手動安裝的詳細資訊，請參閱 在 Windows 上安裝 .NET

如需手動安裝的詳細資訊，請參閱 在 Linux 上安裝 .NET

如需手動安裝的詳細資訊，請參閱 在 macOS 上安裝 .NET

設定向前復原行為

如果您已安裝所需架構的較高版本，您可以配置應用程式的前滾行為，讓應用程式在該較高版本上執行。

在執行應用程式時，可以指定 --roll-forward 命令列選項 或設定 DOTNET_ROLL_FORWARD 環境變數。 根據預設，應用程式需要符合應用程式目標相同主要版本的架構，但可以使用更高的次要或修補程式版本。 不過，應用程式開發人員可能已指定不同的行為。 如需更多資訊，請參閱 Framework 相依應用程式向前輪替。

備註

由於使用此選項可讓應用程式在與其設計的架構版本不同的架構版本上執行，因此可能會因為架構版本之間的變更而導致非預期的行為。

另請參閱

  • 上次更新時間：