裝載及部署 ASP.NET Core Blazor

發行項
11/12/2024

注意

這不是這篇文章的最新版本。如需目前的版本，請參閱本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。如需目前的版本，請參閱本文的 .NET 9 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前的版本，請參閱本文的 .NET 9 版本。

本文說明如何裝載和部署 Blazor 應用程式。

發行應用程式

應用程式會在發行組態中發佈以供部署。

注意

從 Server 專案發佈裝載 Blazor WebAssembly 的解決方案。

Visual Studio
.NET CLI

從 [建置] 功能表選取 [發佈 {APPLICATION}] 命令，其中 {APPLICATION} 預留位置是應用程式的名稱。
選取「發佈目標」。若要在本機發佈，請選取 [資料夾]。
接受 [選擇資料夾] 欄位中的預設位置，或指定不同的位置。選取 Publish 按鈕。

使用 dotnet publish 命令，搭配發行組態來發佈應用程式：

dotnet publish -c Release

發佈應用程式會觸發專案相依性的還原並建置專案，然後才會建立資產以供部署。在建置程序中，會移除未使用的方法和組件，減少應用程式的下載大小和載入時間。

發佈位置：

Blazor Web App：應用程式會發佈至 /bin/Release/{TARGET FRAMEWORK}/publish 資料夾。將 publish 資料夾的內容部署至主機。
Blazor WebAssembly：應用程式會發佈至 bin\Release\net8.0\browser-wasm\publish\ 資料夾。若要將應用程式部署為靜態網站，請將 wwwroot 資料夾的內容複製到靜態網站主機。

Blazor Server：應用程式會發佈至 /bin/Release/{TARGET FRAMEWORK}/publish 資料夾。將 publish 資料夾的內容部署至主機。
Blazor WebAssembly
- 獨立：應用程式會發佈至 /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot 或 bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish 資料夾，視用來發佈應用程式的 SDK 版本而定。若要將應用程式部署為靜態網站，請將 wwwroot 資料夾的內容複製到靜態網站主機。
- 已裝載：用戶端 Blazor WebAssembly 應用程式會發佈至伺服器應用程式的 /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot 資料夾，以及用戶端應用程式的任何其他靜態 Web 資產。將 publish 資料夾的內容部署至主機。

上述路徑中的 {TARGET FRAMEWORK} 是目標架構 (例如，net8.0)。

IIS

若要在 IIS 中裝載 Blazor 應用程式，請參閱下列資源：

IIS 裝載
- 將 ASP.NET Core 應用程式發佈到 IIS
- 使用 IIS 在 Windows 上裝載 ASP.NET
裝載和部署 ASP.NET Core 伺服器端Blazor應用程式：在 IIS 上執行的伺服器應用程式，包括執行 Windows OS 和 Azure App Service 的 Azure 虛擬機器 (VM) 的 IIS。
裝載和部署 ASP.NET CoreBlazor WebAssembly：包含裝載於 IIS 上的 Blazor WebAssembly 應用程式的其他指引，包括靜態網站裝載、自訂 web.config 檔案、URL 重寫、子應用程式、壓縮和 Azure 儲存體靜態檔案裝載。
IIS 子應用程式裝載
- 在發佈應用程式之前，請遵循 Blazor 應用程式的＜應用程式基底路徑＞一節中的指引。這些範例使用 /CoolApp 的應用程式基底路徑，並且顯示如何從應用程式設定或其他設定提供者取得基底路徑。
- 遵循 [進階設定] 中的子應用程式組態指引。根網站底下的子應用程式資料夾路徑會成為子應用程式的虛擬路徑。針對 /CoolApp 的應用程式基底路徑，Blazor 應用程式會放在根網站下名為 CoolApp 的資料夾，而子應用程式會採用 /CoolApp 的虛擬路徑。

不支援在 ASP.NET Core 應用程式之間共用應用程式集區，包括 Blazor 的應用程式。使用 IIS 裝載時，針對每個應用程式使用一個應用程式集區，並避免使用 IIS 的虛擬目錄來裝載多個應用程式。

一個應用程式集區支援一或多個由 ASP.NET Core 應用程式裝載的 Blazor WebAssembly 應用程式，稱為裝載Blazor WebAssembly解決方案。不過，我們不建議或不支援將單一應用程式集區指派給多個裝載的 Blazor WebAssembly 解決方案，或在子應用程式裝載案例中進行。

如需關於解決方案的詳細資訊，請參閱ASP.NET Core Blazor 的工具。

應用程式基底路徑

應用程式基底路徑是應用程式的根 URL 路徑。 Blazor 應用程式中的成功路由需要任何不在預設應用程式基底路徑 / 之根 URL 路徑的架構組態。

請考慮下列 ASP.NET Core 應用程式和 Blazor 子應用程式：

ASP.NET Core 應用程式命名為 MyApp：
- 應用程式實際上位於 d:/MyApp。
- 會在 https://www.contoso.com/{MYAPP RESOURCE} 收到要求。
名為 CoolApp 的 Blazor 應用程式是 MyApp 的子應用程式：
- 子應用程式實際上位於 d:/MyApp/CoolApp。
- 會在 https://www.contoso.com/CoolApp/{COOLAPP RESOURCE} 收到要求。

若未為 CoolApp 指定其他設定，此案例中的子應用程式就不知道其位於伺服器上的位置。例如，應用程式必須得知其位於相對 URL 路徑 /CoolApp/，否則無法建構其資源的正確相對 URL。當應用程式未裝載於根 URL 路徑時，此案例也適用於各種裝載和反向 Proxy 案例。

背景

錨點標記的目的地 (href) 可以由兩個端點之一組成：

包含配置 (如果省略，則預設為頁面的配置)、主機、埠和路徑的絕對位置，或只是正斜線 (/)，後面接著路徑。

範例：https://example.com/a/b/c 或 /a/b/c
僅包含路徑的相對位置且不以正斜線開頭 (/)。這些是相對於目前的文件 URL 或 <base> 標記的值（如果指定）進行解析。

範例: a/b/c

在設定的應用程式基底路徑中，尾端斜線 (/) 的存在對於計算應用程式的 URL 基底路徑很重要。例如，https://example.com/a 的基底路徑為 https://example.com/，而具有尾端斜線的 https://example.com/a/ 的基底路徑為 https://example.com/a。

與 ASP.NET Core 應用程式中的 Blazor 相關的連結來源有以下三個：

Razor 元件 (.razor) 中的 URL 通常是相對的。
指令碼中的 URL，例如 Blazor 指令碼 (blazor.*.js)，相對於本文件。

以手動方式寫入 _Host.cshtml 檔案 (Blazor Server) 的 URL，如果您要在不同的文件中呈現，則一律為絕對 URL。
Razor 元件 (.razor) 中的 URL 通常是相對的。
指令碼中的 URL，例如 Blazor 指令碼 (blazor.*.js)，相對於本文件。

如果您要從不同的文件 (例如 /Admin/B/C/ 和 /Admin/D/E/) 呈現 Blazor 應用程式，您必須將應用程式基底路徑納入考慮，否則當應用程式在每份文件中呈現時，基底路徑會不同，而且會從錯誤的 URL 擷取資源。

有兩種方法可以應對正確解析相對連結的挑戰：

使用其呈現為根目錄的文件，動態對應資源。
設定文件的一致基底路徑，並對應該基底路徑底下的資源。

第一個選項比較複雜，而且不是最典型的方法，因為它會讓每個文件的瀏覽變得不同。請考慮下列範例來呈現頁面 /Something/Else：

在 /Admin/B/C/ 下呈現，頁面會以路徑 /Admin/B/C/Something/Else 呈現。
在 /Admin/D/E/ 下呈現，頁面呈現 ，與 /Admin/B/C/Something/Else 相同的路徑。

在第一種方法下，路由提供 IDynamicEndpointMetadata 和 MatcherPolicy，其結合可以是實作完全動態解決方案的基礎，以決定在執行階段判斷要求路由的方式。

針對第二個選項，這是採用的一般方法，應用程式會在文件中設定基底路徑，並將伺服器端點對應至基本下的路徑。下列指引採用此方法。

伺服器端 Blazor

透過將路徑傳遞到 Program 檔案中的 MapBlazorHub，以對應伺服器端 Blazor 應用程式的 SignalR 中樞：

app.MapBlazorHub("base/path");

使用 MapBlazorHub 的優點是您可以對應模式，例如 "{tenant}"，而不只是具體路徑。

當應用程式位於具有分支中介軟體管線的虛擬資料夾中時，您也可以對應 SignalR 中樞。在下列範例中，對 /base/path/ 的要求是由 Blazor 的 SignalR 中樞處理：

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

依照＜設定應用程式基底路徑＞一節中的指引設定 <base> 標記。

裝載的 Blazor WebAssembly

如果應用程式是裝載 Blazor WebAssembly 的應用程式：

在 Server 專案 (Program.cs) 中：
- 調整 UseBlazorFrameworkFiles 的路徑 (例如，app.UseBlazorFrameworkFiles("/base/path");)。
- 設定對 UseStaticFiles 的呼叫 (例如，app.UseStaticFiles("/base/path");)。
在 Client 專案中：
- 在專案檔案中設定 <StaticWebAssetBasePath>，以符合提供靜態 Web 資產的路徑 (例如，<StaticWebAssetBasePath>base/path</StaticWebAssetBasePath> )。
- 依照＜設定應用程式基底路徑＞一節中的指引設定 <base> 標記。

如需在裝載的 Blazor WebAssembly 解決方案中裝載多個 Blazor WebAssembly 應用程式的範例，請參閱＜多個裝載的 ASP.NET Core Blazor WebAssembly 應用程式＞，其中說明多個 Blazor WebAssembly 用戶端應用程式的網域/埠裝載和子路徑裝載的方法。

獨立 Blazor WebAssembly

在獨立 Blazor WebAssembly 應用程式中，根據＜設定應用程式基底路徑＞一節中的指引，只會設定 <base> 標記。

設定應用程式基底路徑

若要提供應用程式基底路徑的組態Blazor，請設定應用程式基底路徑 https://www.contoso.com/CoolApp/（<base>），這也稱為相對根路徑。

藉由設定應用程式基底路徑，不在根目錄中的元件即可建構相對於應用程式根路徑的 URL。不同目錄結構層級的元件可以建置連結，以連至應用程式內所有位置的其他資源。應用程式基底路徑也會用來攔截所選取的超連結，其中連結的 href 目標是在應用程式基底路徑 URI 空間。 Router 元件會處理內部導覽。

將標記放在<head>標記（內容的位置<head>）之前，任何具有URL屬性值的專案之前，例如href元素的屬性<link>。<base>

在許多裝載案例中，應用程式的相對 URL 路徑是應用程式的根目錄。在這些預設情況下，應用程式的相對 URL 基底路徑在 /<head> 內容中配置為 <base href="/" />。

在許多裝載案例中，應用程式的相對 URL 路徑是應用程式的根目錄。在這些預設情況下，應用程式的相對 URL 基底路徑在 <head> 內容中如下所示：

Blazor Server：~/ 設定為 <base href="~/" />。
Blazor WebAssembly：/ 設定為 <base href="/" />。

注意

在某些裝載案例中，例如 GitHub Pages 和 IIS 子應用程式，應用程式基底路徑必須設定為應用程式的伺服器相對 URL 路徑。

在伺服器端 Blazor 應用程式中，使用下列其中一種方法：
- 選項 1：使用 <base> 標記設定應用程式的基底路徑 (<head> 內容的位置)：
```
<base href="/CoolApp/">
```
  需要尾端斜線。
- 選項2：在建置WebApplicationBuilder (builder.Build()) 後立即呼叫應用程式的要求處理管線 (Program.cs) 中的UsePathBase 第一個，為與要求路徑互動的任何下列中介軟體設定基底路徑：
```
app.UsePathBase("/CoolApp");
```
  當您也想要在本機執行 Blazor Server 應用程式時，建議呼叫 UsePathBase。例如，在 Properties/launchSettings.json 中提供啟動 URL：
```
"launchUrl": "https://localhost:{PORT}/CoolApp",
```
  上述範例中的 {PORT} 預留位置是符合 applicationUrl 設定路徑中安全連接埠的連接埠。下列範例顯示連接埠 7279 中應用程式的完整啟動設定檔：
```
"BlazorSample": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7279;http://localhost:5279",
  "launchUrl": "https://localhost:7279/CoolApp",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
}
```
  如需 launchSettings.json 檔案的詳細資訊，請參閱在 ASP.NET Core 中使用多個環境。如需 Blazor 應用程式基底路徑和裝載的其他資訊，請參閱 <base href="/" /> 或 Blazor MVC 整合的基本標記替代方案 (dotnet/aspnetcore #43191)。
獨立 Blazor WebAssembly (wwwroot/index.html)：
```
<base href="/CoolApp/">
```
需要尾端斜線。

裝載的 Blazor WebAssembly (Client 專案，wwwroot/index.html)：
```
<base href="/CoolApp/">
```
需要尾端斜線。

在 Server 專案中，在建置 WebApplicationBuilder (builder.Build()) 後立即呼叫應用程式的要求處理管線 (Program.cs) 中的UsePathBase 第一個，為與要求路徑互動的任何下列中介軟體設定基底路徑：
```
app.UsePathBase("/CoolApp");
```

注意

使用 WebApplication (請參閱從 ASP.NET Core 5.0 移轉至 6.0) 時，必須在 UsePathBase 之後呼叫 app.UseRouting，路由中介軟體才能在比對路由之前觀察修改的路徑。否則，會在 UsePathBase 重寫路徑之前比對路由，如中介軟體排序和路由文章中所述。

請不要在應用程式的連結前面加上正斜線。請避免使用路徑區段分隔符號，或使用點斜線 (./) 相對路徑標記法：

不正確：<a href="/account">
正確：<a href="account">
正確：<a href="./account">

在Blazor WebAssembly 使用有 HttpClient 服務的Web API 要求中，確認 JSON 協助程式 (HttpClientJsonExtensions) 不會在網址前面加上斜線 (/)：

不正確：var rsp = await client.GetFromJsonAsync("/api/Account");
正確：var rsp = await client.GetFromJsonAsync("api/Account");

請不要在導覽管理員相對連結前面加上正斜線。請避免使用路徑線段分隔符號，或使用點斜線 (./) 相對路徑標記法 (Navigation 是插入的 NavigationManager)：

不正確：Navigation.NavigateTo("/other");
正確：Navigation.NavigateTo("other");
正確：Navigation.NavigateTo("./other");

在 Azure/IIS 裝載的一般設定中，通常不需要其他設定。在某些非 IIS 裝載和反向 Proxy 裝載案例中，可能需要額外的靜態檔案中介軟體設定：

正確提供靜態檔案 (例如，app.UseStaticFiles("/CoolApp");)。
提供 Blazor 指令碼 (_framework/blazor.*.js)。如需詳細資訊，請參閱 ASP.NET Core Blazor 靜態檔案。

對於非根目錄相對 URL 路徑的 Blazor WebAssembly 應用程式 (例如 <base href="/CoolApp/">)，應用程式「在本機執行時」無法找到其資源。若要在本機開發和測試期間解決這個問題，您可以提供「基底路徑」引數，讓它在執行時符合 <base> 標籤的 href 值。 請勿包含尾端斜線。 若要在本機執行應用程式期間傳遞路徑基底引數，請從應用程式的目錄執行 dotnet watch (或 dotnet run) 命令，同時設定 --pathbase 選項：

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

對於具有相對 URL 路徑 /CoolApp/ (<base href="/CoolApp/">) 的 Blazor WebAssembly 應用程式，此命令為：

dotnet watch --pathbase=/CoolApp

如果您想要設定應用程式的啟動設定檔來自動指定 pathbase，而不是使用 dotnet watch (或 dotnet run) 手動指定，請在 Properties/launchSettings.json 中設定 commandLineArgs 屬性。下列項目也會設定啟動 URL (launchUrl)：

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

使用 CoolApp 做為範例：

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

Blazor WebAssembly 應用程式會使用 dotnet watch (或 dotnet run) 搭配 --pathbase 選項或設定基底路徑的啟動設定檔設定，在 http://localhost:port/CoolApp 本機回應。

如需 launchSettings.json 檔案的詳細資訊，請參閱在 ASP.NET Core 中使用多個環境。如需 Blazor 應用程式基底路徑和裝載的其他資訊，請參閱 <base href="/" /> 或 Blazor MVC 整合的基本標記替代方案 (dotnet/aspnetcore #43191)。

從設定取得應用程式基底路徑

下列指導說明如何從不同環境的應用程式設定檔案中取得 <base> 標記的路徑。

將應用程式設定檔案新增至應用程式。下列範例適用於 Staging 環境 (appsettings.Staging.json)：

{
  "AppBasePath": "staging/"
}

在伺服器端 Blazor 應用程式中，從 <head> 內容中的設定載入基底路徑：

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

或者，伺服器端應用程式可以從 UsePathBase 的設定中取得值。緊接在建置 WebApplicationBuilder 之後 (builder.Build())，首先將下列程式碼放置在應用程式的要求處理管線 (Program.cs)。下列範例使用設定索引鍵 AppBasePath：

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

在用戶端 Blazor WebAssembly 應用程式中：

從 wwwroot/index.html 移除 <base> 標記：
```
- <base href="..." />
```

透過 App 元件中的 HeadContent 元件 (App.razor)，提供應用程式基底路徑：

@inject IConfiguration Config

...

<HeadContent>
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
</HeadContent>

如果沒有要載入的設定值，例如在非預備環境中，上述 href 會解析為根路徑 /。

本節中的範例著重於從應用程式設定提供應用程式基底路徑，但從 IConfiguration 讀取路徑的方法適用於任何設定提供者。如需詳細資訊，請參閱以下資源：

ASP.NET Core Blazor 設定 (部分機器翻譯)
ASP.NET Core 中的組態

Blazor Server`MapFallbackToPage` 設定

本節僅適用 Blazor Server 應用程式。 MapFallbackToPage 在 Blazor Web App 和 Blazor WebAssembly 應用程式中暫不支援這項服務。

在應用程式需要具有自訂資源和 Razor 元件的個別區域情況下：

在應用程式的 Pages 資料夾內建立資料夾來保存資源。例如，應用程式的系統管理員區段是在名為 Admin (Pages/Admin) 的新資料夾中建立。
為區域建立根頁面 (_Host.cshtml)。例如，從應用程式的主要根頁面 (Pages/_Host.cshtml) 建立 Pages/Admin/_Host.cshtml 檔案。請勿在管理員 _Host 頁面中提供 @page 指示詞。
例如，將版面配置新增至區域的資料夾 (例如 Pages/Admin/_Layout.razor)。在個別區域的版面配置中，將 <base> 標籤設定為 href 以符合區域的資料夾 (例如 <base href="/Admin/" />)。為了示範目的，請將 ~/ 新增至頁面中的靜態資源。例如：
- ~/css/bootstrap/bootstrap.min.css
- ~/css/site.css
- ~/BlazorSample.styles.css (範例應用程式的命名空間為 BlazorSample)
- ~/_framework/blazor.server.js (Blazor 指令碼)
如果區域應該有自己的靜態資產資料夾，請新增資料夾，並將其位置指定為 Program.cs 中的靜態檔案中介軟體 (例如 app.UseStaticFiles("/Admin/wwwroot"))。
Razor 元件會新增至區域的資料夾。至少，使用區域的正確 @page 指示詞，將 Index 元件新增至區域資料夾。例如，根據應用程式的預設 Pages/Index.razor 檔案新增 Pages/Admin/Index.razor 檔案。指示管理員區域做為檔案頂端的路由範本 (@page "/admin")。視需要新增其他元件。例如，具有 @page 指示詞的 Pages/Admin/Component1.razor 和路由範本 @page "/admin/component1。

在 Program.cs 中，緊接在 _Host 頁面的後援根頁面路徑之前，呼叫 MapFallbackToPage 以取得區域的要求路徑：

...
app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
app.MapFallbackToPage("/_Host");

app.Run();

裝載多個 Blazor WebAssembly 應用程式

如需在裝載 Blazor 解決方案中裝載多個 Blazor WebAssembly 應用程式的詳細資訊，請參閱多個裝載 ASP.NET Core Blazor WebAssembly 應用程式。

部署

如需部署指導方針，請參閱下列主題：

共用方式為