使用 Git 在本機部署至 Azure App Service

2025-05-20

本文說明如何從本機電腦上的 Git 存放庫將應用程式部署至 Azure App Service 。

注意

此部署方法需要原始檔控制管理員（SCM）基本身份驗證，這比其他部署方法的安全性低。如果本機 Git 部署無法運作，您無法在應用程式部署中心中設定本機 Git 部署。

必要條件

若要完成本文中所述的步驟：

如果您沒有 Azure 帳戶，請在開始之前建立免費帳戶。
安裝 Git。
擁有可部署程式碼的本機 Git 存放庫。若要下載範例存放庫，請在本機終端機視窗中執行下列命令：
```
git clone https://github.com/Azure-Samples/nodejs-docs-hello-world.git
```

準備您的存放庫

若要從 App Service 組建伺服器取得自動化組建，請確定您的存放庫根目錄中有正確的檔案。

執行階段	根目錄檔案
ASP.NET (僅限 Windows)	`.sln`、`.csproj` 或 `default.aspx`。
ASP.NET Core	`.sln` 或 `.csproj`。
PHP	`index.php`。
Ruby (僅限 Linux)	`Gemfile`。
Node.js	`server.js`、`app.js` 或 `package.json` 搭配啟動指令碼。
Python（程式語言）	`*.py`、`requirements.txt` 或 `runtime.txt`。
HTML	`default.htm`、 `default.html`、 `default.asp`、 `index.htm`、 `index.html`、或 `iisstart.htm`。
WebJobs	`<job_name>/run.<extension>` 下的 `App_Data/jobs/continuous` 表示連續的 WebJobs，或 `App_Data/jobs/triggered` 表示觸發的 WebJobs。如需詳細資訊，請參閱 Kudu WebJobs 文件。
函式	請參閱 Azure Functions 的持續部署。

若要自定義您的部署，請在存放庫根目錄中包含檔案 .deployment 。如需詳細資訊，請參閱自訂部署和自訂部署指令碼。

提示

Visual Studio 可以為您建立存放庫。透過此方法，您的專案會立即準備好透過 Git 進行部署。

設定部署使用者

瞭解如何設定 Azure App Service 的部署認證。您可以使用使用者範圍登入資訊或應用程式範圍登入資訊。

建立已啟用 Git 的應用程式

如果您已經有 App Service 應用程式，並且想要為應用程式設定本機 Git 部署，請改為參閱設定現有的應用程式。

使用選項執行 --deployment-local-git。

例如：

az webapp create --resource-group <group-name> --plan <plan-name> --name <app-name> --runtime "<runtime-flag>" --deployment-local-git

輸出包含類似範例 https://<deployment-username>@<app-name>.scm.azurewebsites.net/<app-name>.git的 URL。使用此 URL，以在下一個步驟中部署您的應用程式。

從 Git 存放庫的根目錄中，執行 New-AzWebApp。

例如：

New-AzWebApp -Name <app-name>

當您從 Git 存放庫的目錄執行此 Cmdlet 時，會自動建立名為 azure App Service 應用程式的 Git 遠端。

設定現有的應用程式

如果您還沒有應用程式，請開始使用建立已啟用 Git 的應用程式。

執行 az webapp deployment source config-local-git。

例如：

az webapp deployment source config-local-git --name <app-name> --resource-group <group-name>

輸出包含類似範例 https://<deployment-username>@<app-name>.scm.azurewebsites.net/<app-name>.git的 URL。使用此 URL，以在下一個步驟中部署您的應用程式。

提示

此 URL 包含使用者範圍部署使用者名稱。您可以改用應用程式層級的登入資訊。

執行 scmType Cmdlet，以設定應用程式的。

$PropertiesObject = @{
    scmType = "LocalGit";
}

Set-AzResource -PropertyObject $PropertiesObject -ResourceGroupName <group-name> `
-ResourceType Microsoft.Web/sites/config -ResourceName <app-name>/web `
-ApiVersion 2015-08-01 -Force

部署 Web 應用程式

在本機終端機視窗中，將目錄變更為 Git 存放庫的根目錄。使用來自您應用程式的 URL 新增 Git 遠端。如果您使用的方法未提供URL，請搭配您的應用程式名稱使用 https://<app-name>.scm.azurewebsites.net/<app-name>.git 。
```
git remote add azure <url>
```
注意

如果您使用 New-AzWebApp 在 PowerShell 中建立已啟用 Git 的應用程式，則已經建立遠端。
執行 git push azure master來推送到 Azure 遠端分支。

如需詳細資訊，請參閱變更部署分支。
在 [Git 認證管理員] 對話框中，輸入您的使用者範圍或應用程式範圍登入資訊，而不是您的 Azure 登入資訊。

如果您的 Git 遠端 URL 已經包含您的使用者名稱和密碼，則系統不會提示您輸入它們。
檢閱輸出。您可能會看到運行時間特定的自動化，例如 MSBuild for ASP.NET、適用於 Node.js的 npm 安裝，或適用於 Python 的 pip 安裝。
在 Azure 入口網站中，移至您的應用程式，確認已部署內容。

變更部署分支

當您將認可推送至 App Service 存放庫時，App Service 預設會在 master 分支中部署檔案。由於許多 Git 存放庫都從 master 移至 main，因此請確定您以下列兩種方式之一推送至 App Service 存放庫中的正確分支：

執行如下列範例所示的命令，明確地部署至 master ：
```
git push azure main:master
```
更改部署分支，首先設定 DEPLOYMENT_BRANCH 應用程式設定，然後將多個提交推送至自定義分支。

若要使用 Azure CLI 來執行此動作：
```
az webapp config appsettings set --name <app-name> --resource-group <group-name> --settings DEPLOYMENT_BRANCH='main'
git push azure main
```
您也可以在 Azure 入口網站中變更 DEPLOYMENT_BRANCH 應用程式設定：
1. 在 [設定] 底下，選取 [ 環境變數]。
2. 新增具有名稱和 DEPLOYMENT_BRANCH 值 main的應用程式設定。

針對部署進行疑難排解

當您在 Azure 中使用 Git 發佈至 App Service 應用程式時，可能會看到下列常見錯誤訊息：

訊息	原因	解決方案
`Unable to access '[siteURL]': Failed to connect to [scmAddress]`	應用程式未執行。	在 Azure 入口網站中，啟動應用程式。 Web 應用程式停止時，無法使用 Git 部署。
`Couldn't resolve host 'hostname'`	`azure` 遠端的位址資訊不正確。	使用`git remote -v`命令來列出所有遠端及其關聯的URL。驗證 `azure` 遠端的 URL 是否正確。如有需要，請移除並然後使用正確的 URL 重新建立此遠端。
`No refs in common and none specified; doing nothing. Perhaps you should specify a branch such as 'main'.`	當您執行`git push`時，沒有指定分支，或者您尚未在`push.default`中設定`.gitconfig`值。	再次執行 `git push` ，並指定主要分支： `git push azure main`。
`Error - Changes committed to remote repository but deployment to website failed.`	您所推送的本機分支不符合 `azure` 上的應用程式部署分支。	確認最新分支為 `master`。若要變更預設分支，請使用 `DEPLOYMENT_BRANCH` 應用程式設定。如需詳細資訊，請參閱變更部署分支。
`src refspec [branchname] does not match any.`	您嘗試推送到`main`遠端上的非`azure`分支。	再次執行 `git push` ，並指定主要分支： `git push azure main`。
`RPC failed; result=22, HTTP code = 5xx.`	如果您嘗試透過 HTTPS 推送大型 Git 存放庫，可能會發生此錯誤。	變更本機計算機上的 git 組態，以設定 `postBuffer`較高的值。例如： `git config --global http.postBuffer 524288000` 。
`Error - Changes committed to remote repository but your web app not updated.`	您已部署 package.json 檔案指定其他必要模組的 Node.js 應用程式。	`npm ERR!`如需更多內容，請檢閱此錯誤之前出現的錯誤訊息。下列原因為此錯誤和對應的 `npm ERR!` 訊息的已知原因：格式錯誤的 package.json 檔案：`npm ERR! Couldn't read dependencies.` 原生模組沒有適用於 Windows 的二進位發佈： `npm ERR! \cmd "/c" "node-gyp rebuild"\ failed with 1` 或 `npm ERR! [modulename@version] preinstall: \make \\|\\| gmake\`

共用方式為