裝載及部署 ASP.NET Core Blazor WebAssembly

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

使用 Blazor WebAssembly 托管模型時：

• Blazor 應用程式、其相依性以及 .NET 執行階段會平行下載至瀏覽器中。
• 應用程式會直接在瀏覽器 UI 執行緒上執行。

本文與 Blazor 應用程式放在靜態裝載的網頁伺服器或服務上，且未使用 .NET 來提供 Blazor 應用程式的部署案例有關。 此策略涵蓋於獨立 部署 一節，以及此節點中 IIS、Azure 服務、Apache、Nginx 和 GitHub Pages 的其他文章。

子網域和 IIS 子應用程式裝載

子網域裝載不需要應用程式的特殊設定。 您不需要設定應用程式基礎路徑 (<base> 中的 wwwroot/index.html 標籤)，以在子網域裝載應用程式。

IIS 子應用程式裝載需要您設定應用程式基礎路徑。 如需有關 IIS 子應用程式裝載之進一步指導的詳細資訊和交叉連結，請參閱裝載和部署 ASP.NET CoreBlazor。

降低某些行動裝置瀏覽器的最大堆積內存大小

建置在用戶端 (Blazor 的 .Client 專案或獨立 Blazor Web App 應用程式) 上執行，並以行動裝置瀏覽器 (尤其是 iOS 上的 Safari) 為目標的 Blazor WebAssembly 應用程式時，可能需要使用 MSBuild 屬性 EmccMaximumHeapSize 來減少應用程式的最大記憶體。 預設值為 2,147,483,648 個位元組 (該值可能太大)，如果應用程式嘗試配置更多記憶體而瀏覽器無法授與它，則會導致應用程式損毀。 下列範例會在 Program 檔案中將該值設為 268,435,456 個位元組：

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

如需 Mono/WebAssembly MSBuild 屬性和目標的相關資訊，請參閱 WasmApp.Common.targets (dotnet/runtime GitHub 存放庫)。

.NET 組件的 Webcil 封裝格式

Webcil 是適用於 .NET 組件的網頁式封裝格式，其設計是為了讓您能在受限制的網路環境中使用 Blazor WebAssembly。 Webcil 檔案使用標準的 WebAssembly 包裝函式，組件會部署為使用標準 .wasm 副檔名的 WebAssembly 檔案。

當您發行 Blazor WebAssembly 應用程式時，Webcil 是預設的封裝格式。 若要停止使用 Webcil，請在應用程式的專案檔中設定下列 MSBuild 屬性：

<PropertyGroup>
  <WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>

自訂開機資源的載入方式

請使用 loadBootResource API 來自訂開機資源的載入方式。 如需詳細資訊，請參閱 ASP.NET Core Blazor 啟動。

壓縮

在發行 Blazor WebAssembly 應用程式時，系統會在發行期間以靜態方式壓縮輸出，以減少應用程式的大小，並去除執行階段的壓縮負荷。 系統會使用下列壓縮演算法：

• Brotli (最高階)
• Gzip

Blazor 依賴主機來提供適當壓縮的檔案。 在裝載 Blazor WebAssembly 獨立應用程式時，可能需要執行額外的工作以確保系統會提供以靜態方式壓縮的檔案：

• 若為 IIS web.config 壓縮設定，請參閱 IIS：Brotli 和 Gzip 壓縮 一節。
• 在不支援靜態壓縮檔案內容交涉的靜態裝載解決方案上進行裝載時，請考慮設定應用程式以擷取和解碼 Brotli 壓縮的檔案：

從 google/brotli GitHub 存放庫取得 JavaScript Brotli 解碼器。 縮小的解碼器檔案會命名為 decode.min.js，可於存放庫的 js 資料夾中找到。

備註

如果縮小的 decode.js 指令碼版本 (decode.min.js) 失敗，請嘗試改用未縮小的版本 (decode.js)。

更新應用程式以使用解碼器。

在 wwwroot/index.html 檔案中，將 autostart 的 false 標籤設置為 Blazor 以對應 <script>：

<script src="_framework/blazor.webassembly.js" autostart="false"></script>

在 Blazor 的 <script> 標籤後和結尾 </body> 標籤前，新增下列 JavaScript 程式碼 <script> 區塊。 下列函式會用 fetch 呼叫 cache: 'no-cache'，以保持瀏覽器的快取更新。

Blazor Web App：

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {
          return (async function () {
            const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
            if (!response.ok) {
              throw new Error(response.statusText);
            }
            const originalResponseBuffer = await response.arrayBuffer();
            const originalResponseArray = new Int8Array(originalResponseBuffer);
            const decompressedResponseArray = BrotliDecode(originalResponseArray);
            const contentType = type === 
              'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
            return new Response(decompressedResponseArray, 
              { headers: { 'content-type': contentType } });
          })();
        }
      }
    }
  });
</script>

獨立 Blazor WebAssembly：

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration') {
        return (async function () {
          const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
          if (!response.ok) {
            throw new Error(response.statusText);
          }
          const originalResponseBuffer = await response.arrayBuffer();
          const originalResponseArray = new Int8Array(originalResponseBuffer);
          const decompressedResponseArray = BrotliDecode(originalResponseArray);
          const contentType = type === 
            'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
          return new Response(decompressedResponseArray, 
            { headers: { 'content-type': contentType } });
        })();
      }
    }
  });
</script>

如需如何載入開機資源的詳細資訊，請參閱 ASP.NET Core Blazor 啟動。

若要停用壓縮，請將 CompressionEnabled MSBuild 屬性新增至應用程式的專案檔，並將值設定為 false：

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

您可以在命令殼層中使用下列語法將 CompressionEnabled 屬性傳遞至 dotnet publish 命令：

dotnet publish -p:CompressionEnabled=false

重寫 URL 以便正確地路由

在 Blazor WebAssembly 應用程式中的頁面元件路由要求不像 Blazor Server 應用程式中的路由要求那麼簡單。 請考慮具有兩個元件的 Blazor WebAssembly 應用程式：

• Main.razor：載入在應用程式的根目錄，並包含指向 About 元件 (href="About") 的連結。
• About.razor：About 元件。

使用瀏覽器的網址列要求應用程式預設文件時 (例如 https://www.contoso.com/)：

1. 瀏覽器提出要求。
2. 傳回預設頁面，這通常是 index.html。
3. index.html 啟動應用程式。
4. 會載入 Router 元件並轉譯 RazorMain 元件。

在主頁面中，選取 About 元件的連結在用戶端上會有作用，因為 Blazor 路由器會讓瀏覽器不再於網際網路上對 www.contoso.com 提出 About 的要求，並且會自行提供轉譯的 About 元件。 在Blazor WebAssembly 應用程式內的所有內部端點請求都以相同的方式運作：請求不會觸發瀏覽器對網路上伺服器資源的請求。 路由器會在內部處理要求。

如果使用瀏覽器之網址列提出對 www.contoso.com/About 的要求，則要求會失敗。 在應用程式的網際網路主機上沒有這類資源存在，因此會傳回「404 - 找不到」的回應。

因為瀏覽器會提出要求給以網際網路為基礎的主機以取得用戶端頁面，所以網頁伺服器和裝載服務必須針對實際上不在伺服器上的資源，將所有要求重新撰寫至 index.html 頁面。 傳回 index.html 時，應用程式的 Blazor 路由器會進行接管，並以正確的資源做出回應。

在部署至 IIS 伺服器時，您可以使用 URL Rewrite Module 搭配應用程式的已發行 web.config 檔案。 如需詳細資訊，請參閱使用 IIS 裝載和部署 ASP.NET CoreBlazor WebAssembly。

獨立部署

「獨立部署」會將應用程式以一組靜態檔案的形式提供，這些檔案可直接由用戶端要求。 所有靜態檔案伺服器都能提供 Blazor 應用程式。

獨立部署資產會發佈至 /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot 或 bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish 資料夾，其中 {TARGET FRAMEWORK} 佔位元是目標架構。

Azure App Service

Blazor WebAssembly 應用程式可以部署到 Windows 平台上的 Azure App Services，並在 IIS 上提供應用程式的託管。

目前不支援將獨立 Blazor WebAssembly 應用程式部署至適用於 Linux 的 Azure App Service。 我們建議使用 Blazor WebAssembly 來裝載獨立的 應用程式，因為它支援這個情境。

使用 Docker 的獨立運行

獨立的 Blazor WebAssembly 應用程式會以一組靜態檔案的形式發行，以便由靜態檔案伺服器裝載。

若要在 Docker 中裝載應用程式：

• 選擇具有 Web 伺服器支援的 Docker 容器，例如 Nginx 或 Apache。
• 將 publish 資料夾資產複製到網頁伺服器中所定義、用於提供靜態檔案的位置資料夾。
• 視需要套用其他組態以提供 Blazor WebAssembly 應用程式。

如需組態方面的指導，請參閱下列資源：

• Nginx 或 Apache 文章
• Docker 文件

主機組態值

在開發環境中，Blazor WebAssembly 應用程式可以在執行階段接受以下列主機組態值作為命令列引數。

內容根目錄

--contentroot 引數會設定包含應用程式內容檔案的目錄絕對路徑 (內容根目錄)。 在下列範例中，/content-root-path 是應用程式的內容根路徑。

• 在命令提示字元中，在本機環境執行應用程式時傳遞引數。 從應用程式目錄，執行：

  dotnet watch --contentroot=/content-root-path
  

• 在應用程式的 launchSettings.json 設定檔中，將一個項目新增到 檔案。 當搭配 Visual Studio 偵錯工具並以 dotnet watch (或 dotnet run) 從命令提示字元執行應用程式時，會使用此設定。

  "commandLineArgs": "--contentroot=/content-root-path"
  

• 在 Visual Studio 中，在 [屬性]>[偵錯]>[應用程式引數] 中指定引數。 在 Visual Studio 屬性頁中設定引數，會將引數新增至 launchSettings.json 檔案。

  --contentroot=/content-root-path
  

路徑基礎

--pathbase 引數會以非根相對 URL 路徑，為本機執行的應用程式設定應用程式基底路徑 (<base> 標籤 href 會設為非 / 的路徑以供預備和生產之用)。 在下列範例中，/relative-URL-path 是應用程式的路徑基底。 如需詳細資訊，請參閱 ASP.NET Core Blazor 應用程式基底路徑。

這很重要

不同於提供給 href 標籤 <base> 的路徑，在傳遞 / 引數值時請勿包含尾端的斜線 (--pathbase)。 如果應用程式基底路徑提供於 <base> 標籤作為 <base href="/CoolApp/"> (包括尾端的斜線)，請將命令列引數值傳遞為 --pathbase=/CoolApp (不含尾端的斜線)。

• 在命令提示字元中，在本機環境執行應用程式時傳遞引數。 從應用程式目錄，執行：

  dotnet watch --pathbase=/relative-URL-path
  

• 在應用程式的 launchSettings.json 設定檔中，將一個項目新增到 檔案。 當搭配 Visual Studio 偵錯工具並以 dotnet watch (或 dotnet run) 從命令提示字元執行應用程式時，會使用此設定。

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• 在 Visual Studio 中，在 [屬性]>[偵錯]>[應用程式引數] 中指定引數。 在 Visual Studio 屬性頁中設定引數，會將引數新增至 launchSettings.json 檔案。

  --pathbase=/relative-URL-path
  

如需詳細資訊，請參閱 ASP.NET Core Blazor 應用程式基底路徑。

URL

--urls 引數設定IP位址或主機位址，以及用於監聽請求的連接埠和通訊協定。

• 在命令提示字元中，在本機環境執行應用程式時傳遞引數。 從應用程式目錄，執行：

  dotnet watch --urls=http://127.0.0.1:0
  

• 在應用程式的 launchSettings.json 設定檔中，將一個項目新增到 檔案。 當搭配 Visual Studio 偵錯工具並以 dotnet watch (或 dotnet run) 從命令提示字元執行應用程式時，會使用此設定。

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• 在 Visual Studio 中，在 [屬性]>[偵錯]>[應用程式引數] 中指定引數。 在 Visual Studio 屬性頁中設定引數，會將引數新增至 launchSettings.json 檔案。

  --urls=http://127.0.0.1:0
  

設定修剪器

Blazor 會在每個發行組建上執行中繼語言 (IL) 修剪，以從輸出組件中移除不必要的 IL。 如需詳細資訊，請參閱設定 ASP.NET Core Blazor 的修剪器。

先前的部署損壞

一般來說，在部署時：

• 只會取代已變更的檔案，這通常會導致部署速度加快。
• 不屬於新部署的現有檔案會就地保留，以供新部署使用。

在極少數情況下，一直留在先前部署中的檔案可能會損毀新的部署。 徹底刪除現有部署 (或在部署前刪除本機發行的應用程式) 可能會解決部署損毀的問題。 刪除現有部署一次往往就足以解決問題，DevOps 的建置和部署管線也是如此。

如果您判斷在使用 DevOps 建置和部署管線時，一律需要清除先前的部署，則可以暫時在建置管線中新增步驟以刪除每個新部署的先前部署，直到您針對損毀的確切原因進行疑難排解為止。