ASP.NET Core Blazor 靜態檔案

發行項
03/23/2025

注意

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

警告

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

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對於此處提供的資訊，不做任何明示或默示保證。

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

本文描述提供靜態檔案的 Blazor 應用程式設定。

在閱讀本文之前，請參閱在 ASP.NET Core 中對映靜態檔案，瞭解有關使用對映靜態資產路由端點慣例來提供靜態檔案的一般資訊。

伺服器端 Blazor 應用程式中的靜態資產傳遞

提供靜態資產是由路由端點慣例或下表所述的中間件所管理。

功能	應用程式介面 (API)	.NET 版本	描述
映射靜態資產路由端點的慣例	MapStaticAssets	.NET 9 或更新版本	優化靜態資產的傳遞至客戶端。
靜態檔案中間件	UseStaticFiles	所有 .NET 版本	提供靜態資產給用戶端，雖未使用"Map Static Assets"的優化，但在某些"Map Static Assets"無法管理的工作中非常有用。

在大部分情況下，地圖靜態資產都可以取代 UseStaticFiles 。不過，Map Static Assets 已針對在建構與發佈階段從應用程式中的已知位置傳遞資產進行優化。如果應用程式提供來自其他位置的資產 (例如磁碟或內嵌資源)，則應使用 UseStaticFiles。

對應靜態資產（MapStaticAssets）也會取代在提供 Blazor WebAssembly 架構檔案的應用程式中呼叫 UseBlazorFrameworkFiles，而且不需要在 Blazor Web App 中明確呼叫 UseBlazorFrameworkFiles，因為叫用 AddInteractiveWebAssemblyComponents時會自動呼叫 API。

啟用互動式 WebAssembly 或互動式自動轉譯模式時：

Blazor 會建立端點以將資源集合公開為 JS 模組。
當 WebAssembly 元件渲染到頁面時，URL 會發送到請求體中，作為已保存的元件狀態。
在 WebAssembly 開機期間，Blazor 會擷取 URL、匯入模組，以及呼叫函式來擷取資產集合，並在記憶體中重新建構它。 URL 專屬於內容並永遠快取，因此只有在更新應用程式之前，每位使用者才需支付一次此額外負荷成本。
資源集合也會在人類可讀取的 URL (_framework/resource-collection.js) 中公開，因此 JS 可以存取資源集合以增強瀏覽，或實作其他架構和協力廠商元件的功能。

靜態檔案中間件（UseStaticFiles）適用於下列無法處理 Map Static Assets （MapStaticAssets）的情況：

從不屬於組建或發布過程中的磁碟中提供檔案，例如，在部署期間或之後新增至應用程式資料夾的檔案。
將路徑前置詞套用至 Blazor WebAssembly 靜態資產檔案，這在「Blazor WebAssembly 資產的前置詞」章節中有詳細說明。
設定檔案副檔名與特定內容類型的對應，以及設定靜態檔案選項，這在「檔案對應和靜態檔案選項」章節中有詳細說明。

如需詳細資訊，請參閱 ASP.NET Core 中的靜態檔案。

透過映射靜態資產的路由端點慣例來交付資產

本節適用伺服器端 Blazor 應用程式。

資產會透過 ComponentBase.Assets 屬性傳遞，以解析指定資產的指紋URL。在下列範例中，Bootstrap、 Blazor 專案範本應用程式樣式表單（app.css），和 CSS 隔離樣式表單（根據應用程式的命名空間 BlazorSample）連結在根元件中，通常是 App 元件（Components/App.razor）：

<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />

匯入地圖

本節適用伺服器端 Blazor 應用程式。

匯入對照元件（ImportMap）代表匯入對照元素（<script type="importmap"></script>），用於定義模組腳本的匯入對照。匯入對應元件會放在根元件的<head>內容中，通常是App元件（Components/App.razor）。

<ImportMap />

如果未將自訂 ImportMapDefinition 指派給匯入對應映射元件，則會根據應用程式的資產產生匯入對應映射。

以下範例演示自訂的匯入對應定義及其所生成的匯入對應。

基本匯入映射

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

上述程式碼會產生下列匯入對應：

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

範疇匯入對應圖表

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

上述程式碼會產生下列匯入對應：

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

匯入具有完整性驗證的映射：

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    new Dictionary<string, string>
    {
        { "https://cdn.example.com/jquery.js", "sha384-abc123" },
    });

上述程式碼會產生下列匯入對應：

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

合併匯入映射定義 (ImportMapDefinition) 和 ImportMapDefinition.Combine。

匯入地圖是從 ResourceAssetCollection 建立的，用來將靜態資產映射到它們唯一的 URL。

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

上述程式碼會產生下列匯入對應：

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

透過在應用程式的要求處理管線中呼叫 UseStaticFiles，設定靜態檔案中介軟體以提供靜態資產給用戶端。如需詳細資訊，請參閱 ASP.NET Core 中的靜態檔案。

在 .NET 8 之前的版本中，會透過靜態檔案中介軟體提供 Blazor 指令碼這類 Blazor 架構靜態檔案。在 .NET 8 或更新版本中，會使用端點路由來對應 Blazor 架構靜態檔案，而且不再使用靜態檔案中介軟體。

靜態檔案 `<link>href` 格式的摘要

本章節適用於所有 .NET 版本和 Blazor 應用程式。

下表會摘要說明 .NET 版本的靜態檔案 <link>href 格式。

如需放置靜態檔案連結的 <head> 內容的位置，請參閱 ASP.NET Core Blazor 專案結構。靜態資產連結也可以使用個別 <HeadContent> 元件中的來提供。

如需放置靜態檔案連結的 <head> 內容的位置，請參閱 ASP.NET Core Blazor 專案結構。

.NET 9 或更新版本

應用程式類型	`href` 值	範例
Blazor Web App	`@Assets["{PATH}"]`	`<link rel="stylesheet" href="@Assets["app.css"]" />` `<link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />`
Blazor Server†	`@Assets["{PATH}"]`	`<link href="@Assets["css/site.css"]" rel="stylesheet" />` `<link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />`
獨立 Blazor WebAssembly	`{PATH}`	`<link rel="stylesheet" href="css/app.css" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`

.NET 8.x

應用程式類型	`href` 值	範例
Blazor Web App	`{PATH}`	`<link rel="stylesheet" href="app.css" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`
Blazor Server†	`{PATH}`	`<link href="css/site.css" rel="stylesheet" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`
獨立 Blazor WebAssembly	`{PATH}`	`<link rel="stylesheet" href="css/app.css" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`

.NET 7.x 或更早版本

應用程式類型	`href` 值	範例
Blazor Server†	`{PATH}`	`<link href="css/site.css" rel="stylesheet" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`
主辦的 Blazor WebAssembly‡	`{PATH}`	`<link href="css/app.css" rel="stylesheet" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`
Blazor WebAssembly	`{PATH}`	`<link href="css/app.css" rel="stylesheet" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`

.NET 8 或更新版本支援 †Blazor Server，但其在 .NET 7 之後不再是專案範本。
‡建議您在採用 .NET 8 或更新版本時，將託管的 Blazor WebAssembly 應用程式更新為 Blazor Web App。

靜態 Web 資產專案模式

本章節適用於 .Client的 Blazor Web App 專案。

<StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> 的 .Client 專案中所需的 Blazor Web App 設定會將 Blazor WebAssembly 靜態資產表現方式還原回預設值，讓專案作為託管專案的一部分運作。 Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) 會以特定方式設定靜態 Web 資產，以「獨立」模式運作，而伺服器只需取用程式庫的輸出即可。這不適用於 Blazor Web App，其中應用程式的 WebAssembly 部分是主機的邏輯部分，而且必須表現出更像程式庫的行為。例如，專案不會公開樣式組合 (例如 BlazorSample.Client.styles.css)，而是只向主機提供專案組合，讓主機可以將該組合包含在自己的樣式組合中。

不支援變更 Default 的值 (<StaticWebAssetProjectMode>) 或從 .Client 專案移除屬性。

非 `Development` 環境中的靜態檔案

本節適用於伺服器端靜態檔案。

在本機執行應用程式時，靜態 Web 資產只會在 Development 環境中啟用。若要在本機開發和測試期間為 Development 以外的環境啟用靜態檔案 (例如，Staging)，請在 UseStaticWebAssets 檔案中的 WebApplicationBuilder 上呼叫 Program。

警告

打電話給 UseStaticWebAssets 以獲得準確的環境，以防止在生產環境中啟用該功能，因為在生產環境中呼叫時，它會從磁碟上的不同位置提供檔案，而不是從專案中提供。本節中的範例會呼叫 Staging 來檢查 IsStaging 環境。

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Blazor WebAssembly 資產的字首

本章節適用於 Blazor Web App項。

使用 WebAssemblyComponentsEndpointOptions.PathPrefix 端點選項來設定用於指示 Blazor WebAssembly 資產的前綴的路徑字串。路徑必須對應至參考的 Blazor WebAssembly 應用程式專案。

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

在上述範例中，{PATH PREFIX} 預留位置是路徑前置詞，且開頭必須是正斜線 (/)。

在下列範例中，路徑前置詞會設定為 /path-prefix：

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

靜態 Web 資產基礎路徑

本節適用獨立 Blazor WebAssembly 應用程式。

發佈應用程式會將應用程式的靜態資產，包括 Blazor 架構檔案（_framework 資料夾資產），放在已發佈輸出中的根路徑 (/)。專案檔 (<StaticWebAssetBasePath>) 中指定的 .csproj 屬性會將基礎路徑設定為非根路徑：

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

在上述範例中，{PATH} 預留位置是路徑。

若未設定 <StaticWebAssetBasePath> 屬性，獨立應用程式會在 /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/ 發佈。

在上述範例中，{TFM} 佔位符是目標框架標記 (TFM)（例如，net6.0）。

如果獨立 <StaticWebAssetBasePath> 應用程式中的 Blazor WebAssembly 屬性將已發佈的靜態資產路徑設定為 app1，則已發佈輸出中應用程式的根路徑為 /app1。

在獨立 Blazor WebAssembly 應用程式的專案檔中 (.csproj)：

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

在發佈的輸出中，獨立 Blazor WebAssembly 應用程式的路徑為 /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/。

在上述範例中，{TFM} 佔位符是目標框架名稱 (TFM) (例如，net6.0)。

本節適用獨立 Blazor WebAssembly 應用程式和裝載的 Blazor WebAssembly 方案。

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

在上述範例中，{PATH} 預留位置是路徑。

若未設定 <StaticWebAssetBasePath> 屬性，裝載的方案或獨立應用程式的用戶端應用程式會在下列路徑發佈：

託管的 Server 解決方案中的 Blazor WebAssembly 專案：/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
在獨立 Blazor WebAssembly 應用程式中：/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

如果裝載的 <StaticWebAssetBasePath> 應用程式或獨立 Client 應用程式中 Blazor WebAssembly 專案的 Blazor WebAssembly 屬性將已發佈的靜態資產路徑設定為 app1，則已發佈輸出中應用程式的根路徑為 /app1。

在 Client 應用程式的專案檔 (.csproj) 或獨立 Blazor WebAssembly 應用程式的專案檔中 (.csproj)：

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

在已發佈的產出中：

在託管 Blazor WebAssembly 解決方案的 Server 專案中，客戶端應用程式的路徑為：/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
獨立 Blazor WebAssembly 應用程式的路徑：/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

<StaticWebAssetBasePath> 屬性最常用來控制單一裝載部署中多個 Blazor WebAssembly 應用程式已發佈的靜態資產的路徑。如需詳細資訊，請參閱多個裝載的 ASP.NET Core Blazor WebAssembly 應用程式。屬性在獨立 Blazor WebAssembly 應用程式中也有效。

在上述範例中，{TFM} 預留位置是目標架構標記 (TFM) (例如，net6.0)。

檔案對應和靜態檔案選項

本節適用於伺服器端靜態檔案。

若要使用 FileExtensionContentTypeProvider 或設定其他 StaticFileOptions 來建立其他檔案對應，請使用下列其中一種方法。在下列範例中，{EXTENSION} 預留位置是副檔名，而 {CONTENT TYPE} 預留位置是內容類型。下列 API 的命名空間為 Microsoft.AspNetCore.StaticFiles。

在 Program 檔案中，使用相依性注入 (DI) 透過 StaticFileOptions 設定選項：

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

app.UseStaticFiles();

將 StaticFileOptions 直接傳遞至 UseStaticFiles 檔案中的 Program：

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });

若要使用 FileExtensionContentTypeProvider 或設定其他 StaticFileOptions 來建立其他檔案對應，請使用下列其中一種方法。在下列範例中，{EXTENSION} 預留位置是副檔名，而 {CONTENT TYPE} 預留位置是內容類型。

通過相依性注入 (DI)，在Program檔案中使用StaticFileOptions配置選項：
```
using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});
```
此方法會設定用來提供 Blazor 指令碼的相同檔案提供者。請確定您的自訂設定不會干擾提供 Blazor 指令碼。例如，請勿使用 provider.Mappings.Remove(".js") 設定提供者來移除 JavaScript 檔案的對應。

在 UseStaticFiles 檔案中使用對 Program 的兩個呼叫：

使用 StaticFileOptions 在第一次呼叫中設定自訂檔案提供者。
第二個中介軟體會提供 Blazor 指令碼，其會使用 Blazor 架構提供的預設靜態檔案設定。

using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

您可以透過使用 _framework/blazor.server.js 來執行自訂的靜態檔案中介軟體，以避免影響 MapWhen 的服務：

app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

提供來自多個位置的檔案

本章節的指導僅適用於 Blazor Web App。

若要使用 CompositeFileProvider 提供來自多個位置的檔案：

將 Microsoft.Extensions.FileProviders 的命名空間新增至伺服器專案的 Program 檔案頂端。
在伺服器專案檔案
中，在呼叫
之前
：

以靜態資產的路徑建立 PhysicalFileProvider。

從 CompositeFileProvider 和 WebRootFileProvider 建立 PhysicalFileProvider。將複合檔案提供者重新設置到應用程式的 WebRootFileProvider。

範例：

在名為 AdditionalStaticAssets 的伺服器專案中建立新資料夾。將影像放入資料夾中。

將下列 using 陳述式新增至伺服器專案的 Program 檔案頂端：

using Microsoft.Extensions.FileProviders;

在伺服器專案的Program檔案中，在呼叫之前，新增下列程式碼：

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

在應用程式的 Home 元件 (Home.razor) 標記中，參考具有 <img> 標籤的影像：

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

在前述範例中:

{IMAGE FILE NAME} 預留位置是圖像檔案名稱。如果影像檔位於 AdditionalStaticAssets 資料夾的根目錄，則不需要提供路徑區段。
{ALT TEXT} 佔位符是影像替代文字。

執行應用程式。

共用方式為

ASP.NET Core Blazor 靜態檔案

伺服器端 Blazor 應用程式中的靜態資產傳遞

透過映射靜態資產的路由端點慣例來交付資產

匯入地圖

靜態檔案 `<link>href` 格式的摘要

.NET 9 或更新版本

.NET 8.x

.NET 7.x 或更早版本

靜態 Web 資產專案模式

非 `Development` 環境中的靜態檔案

Blazor WebAssembly 資產的字首

靜態 Web 資產基礎路徑

檔案對應和靜態檔案選項

提供來自多個位置的檔案

其他資源

其他資源

共用方式為

ASP.NET Core Blazor 靜態檔案

伺服器端 Blazor 應用程式中的靜態資產傳遞

透過映射靜態資產的路由端點慣例來交付資產

匯入地圖

靜態檔案 <link>href 格式的摘要

.NET 9 或更新版本

.NET 8.x

.NET 7.x 或更早版本

靜態 Web 資產專案模式

非 Development 環境中的靜態檔案

Blazor WebAssembly 資產的字首

靜態 Web 資產基礎路徑

檔案對應和靜態檔案選項

提供來自多個位置的檔案

其他資源

其他資源

靜態檔案 `<link>href` 格式的摘要

非 `Development` 環境中的靜態檔案