設定 Azure 靜態 Web Apps 的本機開發

發行項
02/05/2024

發佈至雲端時，Azure Static Web Apps 網站會將許多服務連結在一起，就像是相同的應用程式一樣。這些服務包括：

靜態 Web 應用程式
Azure Functions API
驗證和授權服務
路由和設定服務

這些服務必須彼此通訊，Azure Static Web Apps 會為您在雲端中處理這項整合。

不過，當您在本機執行應用程式時，這些服務不會自動繫結在一起。

為了提供與您在 Azure 中取得的內容類似的體驗， Azure Static Web Apps CLI 提供下列服務：

本機靜態月臺伺服器
前端架構開發伺服器的 Proxy
API 端點的 Proxy - 可透過 Azure Functions Core Tools 取得
模擬驗證和授權伺服器
強制執行本機路由和組態設定

注意

使用前端架構建置的網站通常需要 Proxy 組態設定，才能正確處理路由下 api 的要求。使用 Azure Static Web Apps CLI 時，Proxy 位置值為 /api，而沒有 CLI，則值為 http://localhost:7071/api。

運作方式

下圖顯示如何在本機處理要求。

Diagram showing the Azure Static Web App CLI request and response flow.

重要

移至以 http://localhost:4280 存取 CLI 所提供的應用程式。

對埠4280提出的要求會根據要求類型轉送至適當的伺服器。
靜態內容 要求，例如 HTML 或 CSS，是由內部 CLI 靜態內容伺服器或前端架構伺服器處理以進行偵錯。
驗證和授權 要求是由模擬器處理，其會為您的應用程式提供假身分識別配置檔。
Functions Core Tools 運行時間¹ 會處理月臺 API 的要求。
所有服務的響應都會傳回至瀏覽器，就像是單一應用程式一樣。

一旦您獨立啟動UI和 Azure Functions API 應用程式，然後啟動 Static Web Apps CLI，並使用下列命令將它指向執行中的應用程式：

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

或者，如果您使用 swa init 命令，靜態 Web Apps CLI 會查看您的應用程式程式代碼，並建置 CLI 的swa-cli.config.json組態檔。當您使用 swa-cli.config.json 檔案時，您可以執行 swa start 以在本機啟動應用程式。

¹ 如果尚未在您的系統上，CLI 會自動安裝 Azure Functions Core Tools。

下列文章詳細說明執行節點型應用程式的步驟，但任何語言或環境的程式都相同。

必要條件

現有的 Azure Static Web Apps 網站：如果您沒有，請從 vanilla-api 入門應用程式開始。
使用 npm Node.js：執行包含 npm 存取權的 Node.js LTS 版本。
Visual Studio Code：用於對 API 應用程式進行偵錯，但 CLI 並非必要專案。

開始使用

開啟您現有 Azure Static Web Apps 網站的根資料夾終端機。

安裝 CLI。
```
npm install -D @azure/static-web-apps-cli
```
提示

如果您要全域安裝 SWA CLI，請使用 -g 取代 -D。不過，強烈建議您將SWA安裝為開發相依性。
如果您的應用程式需要，請建置您的應用程式。

執行 npm run build，或專案的對等命令。
初始化 CLI 的存放庫。
```
swa init
```
回答 CLI 提出的問題，以確認您的組態設定正確無誤。
啟動 CLI。
```
swa start
```
移至以 http://localhost:4280 在瀏覽器中檢視應用程式。

啟動 CLI 的其他方式

描述	Command	註解
提供特定資料夾	`swa start ./<OUTPUT_FOLDER_NAME>`	將取代 `<OUTPUT_FOLDER_NAME>` 為輸出資料夾的名稱。
使用執行中的架構開發伺服器	`swa start http://localhost:3000`	當您的應用程式實例在埠 `3000`下執行時，此命令會運作。如果您的設定不同，請更新埠號碼。
在資料夾中啟動 Functions 應用程式	`swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api`	將取代 `<OUTPUT_FOLDER_NAME>` 為輸出資料夾的名稱。此命令預期應用程式的 API 資料夾中會有檔案 `api` 。如果您的設定不同，請更新此值。
使用執行中的 Functions 應用程式	`swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071`	將取代 `<OUTPUT_FOLDER_NAME>` 為輸出資料夾的名稱。此命令預期您的 Azure Functions 應用程式可透過埠 `7071`取得。如果您的設定不同，請更新埠號碼。

授權和驗證模擬

Static Web Apps CLI 會模擬在 Azure 中實作的安全性流程。當使用者登入時，您可以定義傳回給應用程式的假身分識別配置檔。

例如，當您嘗試移至 /.auth/login/github時，會傳回可讓您定義身分識別配置檔的頁面。

注意

模擬器可搭配任何安全性提供者使用，而不只是 GitHub。

Local authentication and authorization emulator

模擬器提供頁面，可讓您提供下列客戶端主體值：

值	Description
使用者名稱	與安全性提供者相關聯的帳戶名稱。此值會顯示為 `userDetails` 客戶端主體中的屬性，如果您未提供值，則會自動產生此值。
使用者識別碼	CLI 自動產生的值。
角色	角色名稱的清單，其中每個名稱都位於新行上。
宣告	使用者宣告的清單，其中每個名稱都位於新行上。

登入後：

您可以使用 /.auth/me 端點或函式端點來擷取使用者的客戶端主體。
流覽以 /.auth/logout 清除客戶端主體並註銷模擬使用者。

偵錯

靜態 Web 應用程式中有兩個偵錯內容。第一個是靜態內容網站，第二個適用於 API 函式。允許靜態 Web Apps CLI 針對其中一或兩個內容使用開發伺服器，即可進行本機偵錯。

下列步驟說明針對這兩個偵錯內容使用開發伺服器的常見案例。

啟動靜態網站開發伺服器。此命令專屬於您使用的前端架構，但通常以、 npm start或 npm run dev之類的npm run build命令形式出現。
在 Visual Studio Code 中開啟 API 應用程式資料夾，然後啟動偵錯作業階段。
使用下列命令啟動靜態 Web Apps CLI。
```
swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
```
將取代 <DEV_SERVER_PORT_NUMBER> 為開發伺服器的埠號碼。

下列螢幕快照顯示典型偵錯案例的終端機：

靜態內容網站正透過 npm run dev執行。

Static site development server

Azure Functions API 應用程式正在 Visual Studio Code 中執行偵錯會話。

Visual Studio Code API debugging

靜態 Web Apps CLI 會使用這兩部開發伺服器啟動。

Azure Static Web Apps CLI terminal

現在，通過埠 4280 的要求會路由傳送至靜態內容開發伺服器或 API 偵錯會話。

如需不同偵錯案例的詳細資訊，以及如何自定義埠和伺服器位址的指引，請參閱 Azure Static Web Apps CLI 存放庫。

偵錯組態範例

Visual Studio Code 使用檔案在編輯器中啟用偵錯會話。如果 Visual Studio Code 未為您產生launch.json檔案，您可以在 .vscode/launch.json 中放置下列組態。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

下一步

設定您的應用程式

Share via