ASP.NET Core Blazor 應用程式基底路徑

備註

這不是本文的最新版本。關於目前版本，請參閱本文的 .NET 10 版本。

警告

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

本文說明 ASP.NET Core 應用程式中Blazor，包括設定指引。

應用程式基底路徑是應用程式的根 URL 路徑。在 Blazor 應用程式中，為了成功的路由，必須為不在預設應用程式基底路徑 / 的任何根 URL 路徑進行框架設置。

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

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

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

背景

錨點標記的目的地 (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)，相對於本文件。

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

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

使用呈現它們的文件作為根動態映射資源。
設定文件的一致基底路徑，並對應該基底路徑底下的資源。

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

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

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

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

伺服器端 Blazor

將伺服器端 SignalR 應用程式的Blazor 中樞對應，方法是將路徑傳遞到 MapBlazorHub 的Program 檔案中。

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 元件會處理內部導覽。

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

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

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

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

備註

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

在伺服器端 Blazor 應用程式中，使用下列其中一種方法：
- 選項 1：使用 <base> 標記設定應用程式的基底路徑 (<head> 內容的位置)：
```
<base href="/CoolApp/">
```
  尾端的斜線是必需的。
- 選項2：在應用程式的要求處理管線 (UsePathBase) 中，在建置 () 後立即呼叫Program.cs，以配置與要求路徑互動的任何後續中介軟體的基本路徑：
```
app.UsePathBase("/CoolApp");
```
  當您也想要在本機執行 UsePathBase 應用程式時，建議呼叫 Blazor Server。例如，在 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 專案中，應用程式的要求處理管線 (UsePathBase) 應在建置 () 後立即呼叫 Program.csUsePathBase，以設定與要求路徑互動的任何後續中介軟體的基底路徑：
```
app.UsePathBase("/CoolApp");
```

備註

使用 WebApplication 時（請參閱從 .NET 5 中的 ASP.NET Core 移轉至 .NET 6），必須在之後app.UseRouting呼叫，UsePathBase路由中間件才能觀察修改的路徑，再比對路由。否則，會在 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/">)，應用程式「在本機執行時」無法找到其資源。若要在本機開發和測試期間解決這個問題，您可以提供「基底路徑」引數，讓它在執行時符合 href 標籤的 <base> 值。 請勿包含尾端斜線。 若要在本機執行應用程式期間傳遞路徑基底引數，請從應用程式的目錄執行 dotnet watch (或 dotnet run) 命令，同時設定 --pathbase 選項：

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

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

dotnet watch --pathbase=/CoolApp

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

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

使用 CoolApp 做為範例：

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

dotnet watch 應用程式會使用 dotnet run (或 --pathbase) 搭配 Blazor WebAssembly 選項或設定基底路徑的啟動設定檔設定，在 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 的設定中取得值。將下列程式碼first放置在應用程式的要求處理管線Program.cs中，緊接在建置WebApplicationBuilder(builder.Build())之後。下列範例使用設定索引鍵 AppBasePath：

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

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

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

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

@inject IConfiguration Config

...

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

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

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

ASP.NET Core Blazor 組態
ASP.NET Core 中的組態

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-11