在本地使用 Git 部署到 Azure 应用服务

2025-05-20

本文介绍如何从本地计算机上的 Git 存储库将应用部署到 Azure 应用服务。

注意

此部署方法需要源代码管理器（SCM）基本身份验证，这比其他部署方法安全性较低。如果本地 Git 部署不起作用，则无法在应用部署中心配置本地 Git 部署。

先决条件

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

如果没有 Azure 帐户，请在开始前创建一个免费帐户。
安装 Git。
拥有一个包含要部署代码的本地 Git 存储库。若要下载示例存储库，请在本地终端窗口运行以下命令：
```
git clone https://github.com/Azure-Samples/nodejs-docs-hello-world.git
```

准备存储库

若要从应用服务生成服务器获取自动构建，请确保项目的存储库根目录中有正确的文件。

运行时	根目录文件
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.htmldefault.asp`、`index.htm`、或`index.htmliisstart.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 应用服务配置部署凭据。可以使用用户范围登录信息或应用程序范围登录信息。

创建已启用 Git 的应用

如果您已经有一个应用服务，并且想要为其配置本地 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 的 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>
```
注意

如果您在 PowerShell 中使用 New-AzWebApp 创建了启用了 Git 的应用，那么远程已创建。
通过运行 git push azure master 推送到 Azure 远程库分支。

有关详细信息，请参阅 “更改部署分支”。
在 “Git 凭据管理器 ”对话框中，输入用户范围或应用程序范围的登录信息，而不是 Azure 登录信息。

如果 Git 远程 URL 已包含用户名和密码，则不会提示输入它们。
查看输出。你可能会看到特定于运行时的自动化，例如 MSBuild for ASP.NET、适用于 Node.js的 npm 安装或适用于 Python 的 pip 安装。
在 Azure 门户中，转到应用以验证是否已部署内容。

更改部署分支

将提交推送到应用服务存储库时，应用服务默认在 master 分支中部署文件。由于许多 Git 存储库正在从 master 迁移到 main，因此，请确保通过以下两种方式之一将更改推送到应用服务存储库中的正确分支：

显式部署到 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 的应用设置。

排查部署问题

使用 Git 发布到 Azure 中的应用服务应用时，可能会看到以下常见错误消息：

消息	原因	解决方法
`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\`

通过