你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

Azure Functions 的基于包的部署

本文介绍了如何创建一个现成的 .zip 部署包,将包部署到Azure,并配置函数应用直接从该包运行。 你可以使用Azure Functions Core Tools、Azure CLI或部署的REST API来部署。

基于包的部署是基于代码运行的函数应用的默认配置。 部署技术和包配置取决于托管计划。 请在本文顶部选择您的托管套餐。

Azure Functions 拥有 Azure 应用服务 提供的全方位持续部署和集成选项。 有关详细信息,请参阅 Azure Functions 的连续部署。

按托管计划部署包

下表总结了每个托管计划的部署过程和包配置:

托管计划 部署过程 软件包配置
灵活消费计划 托管包部署 默认情况下,它从已部署的软件包运行。 不要设置 WEBSITE_RUN_FROM_PACKAGE。
高级计划 ZIP 包部署 将 WEBSITE_RUN_FROM_PACKAGE 设置为 1,以从已部署的包中运行。
专用(应用服务)计划 ZIP 包部署 将 WEBSITE_RUN_FROM_PACKAGE 设置为 1 以从已部署的包运行。
Windows 上的消耗方案 ZIP 包部署 将WEBSITE_RUN_FROM_PACKAGE设置为1,以便从已部署的程序包运行。
Linux 上的用电计划 远程构建或外部软件包网址 为本地构建的包使用外部包网址。
Azure 容器应用 容器镜像部署 基于包的代码部署不适用。

注释

本文内容与当前选择的托管计划无关。 要选择其他套餐,请使用本文顶部的选择器。 有关所有托管计划的比较,请参见 Azure Functions 托管选项。

托管在Azure 容器应用上的函数应用是以容器镜像部署的,而不是 .zip 包。 要创建和部署基于镜像的函数应用,请参见“使用代码在 Azure 容器应用 创建函数应用”。

创建部署包

大多数情况下,你不需要自己创建部署包。 这些基于工具的部署方法将软件包作为发布过程的一部分创建:

对于 Azure Pipelines 部署,流水线构建步骤会创建 .zip 存档,并将其传递给 AzureFunctionApp 部署任务。

当你需要直接使用可直接运行的部署包时,使用 func pack 创建该部署包。 例如,部署时使用 外部包 URL 自行创建包。

你也可以手动创建 .zip 档案。 手动创建归档时,请遵循这些包结构要求。

部署包需求

部署的 zip 存档必须包含运行函数应用所需的所有文件。 可以使用内置 .zip 压缩功能或非Microsoft工具从 Functions 项目文件夹的内容手动创建 zip 存档。

存档必须在提取文件夹的根目录中包含 host.json 文件。 函数应用的所选语言堆栈会创建其他要求:

重要说明

对于生成用于部署的已编译输出的语言,请确保压缩你计划发布的输出文件夹(而不是整个项目文件夹)的内容。 当 Functions 提取 zip 存档的内容时,host.json 文件必须存在于包的根目录中。

Zip 部署过程会在 wwwroot 目录中提取 .zip 压缩包中的文件和文件夹。 如果你在创建归档时包含父目录,系统就找不到它期望看到的文件。wwwroot

部署程序包

Flex Consumption 使用 包部署 ,将一个现成的包存储在应用的部署存储容器中。 应用直接从这个包运行。 不要设置 WEBSITE_RUN_FROM_PACKAGE 应用设置。

通过使用 Core Tools、Visual Studio Code 或 Azure CLI 部署该软件包。 这些工具会自动为Flex Consumption App选择正确的包部署行为。

这些工具通过将包发送到应用的部署端点来执行推送部署。 对于Flex Consumption,这些客户端会将包裹发送到 /api/publish 应用 scm 主机上。 当部署端点只能通过私有端点访问时,执行部署的计算机、运行员或代理必须与私有部署端点具备网络连接和DNS解析。 部署服务将处理后的包存储在配置好的部署容器中;直接上传包到该容器并不会部署包。 若要在部署时不从发起客户端向部署终结点推送,请使用Bicep 或 ARM 模板部署,并提供部署服务可访问的包 URL。

使用 Azure CLI 进行部署

使用 az functionapp deployment source config-zip 命令部署包:

az functionapp deployment source config-zip --resource-group <RESOURCE_GROUP> \
  --name <APP_NAME> --src <ZIP_FILE_PATH>

当源项目需要远程构建时添加 --build-remote true 。 不要为已经由 func pack 构建为可直接运行状态的包发起远程构建,例如 Go 部署包。

如需配置部署存储或恢复早期部署,请参见 Flex Consumption plan中的创建和管理功能应用。

部署程序包

高级、专用和消费套餐应用都使用zip部署API。 部署服务执行以下操作:

  • 删除之前部署中剩余的文件。
  • 运行部署脚本和其他部署自定义。
  • 写部署日志。
  • 同步函数触发器。

重要说明

在压缩包部署中,之前部署的文件会被删除或更新,因为它们是该部署的一部分。 部署过程会保留函数应用中未包含在上一次部署中的其他文件和目录。 关于实现细节,请参见 zip 部署参考。

使用 Azure CLI 进行部署

使用 Azure CLI 来触发推送部署。 使用 az functionapp deployment source config-zip 命令将 .zip 文件推送部署到函数应用。 要使用此命令,必须使用 Azure CLI 版本 2.0.21 或更高版本。 若要查看正在使用的 Azure CLI 版本,请使用 az --version 该命令。

以下命令将 <zip_file_path> 占位符替换为 .zip 文件的位置路径。 此外,请将 <app_name> 替换为函数应用的唯一名称,并将 <resource_group> 替换为资源组的名称。

az functionapp deployment source config-zip -g <resource_group> -n \
<app_name> --src <zip_file_path>

这个命令会把项目文件从 .zip 文件部署到你的函数应用Azure然后重启应用。

在本地计算机上使用 Azure CLI 时,<zip_file_path> 是计算机中 .zip 文件的路径。 也可以在 Azure Cloud Shell 中运行 Azure CLI。 使用 Cloud Shell 时,首先必须将部署 .zip 文件上传到与 Cloud Shell 关联的 Azure 文件帐户。 在这种情况下,<zip_file_path> 是 Cloud Shell 帐户使用的存储位置。 有关详细信息,请参阅在 Azure Cloud Shell 中持久保存文件。

使用 REST API 部署 ZIP 文件

可以使用部署服务 REST API 将 .zip 文件部署到 Azure 中的应用。 若要部署,请将 POST 请求发送到 https://<app_name>.scm.azurewebsites.net/api/zipdeploy。 POST 请求必须在消息正文中包含此 .zip 文件。 应用的部署凭据是通过使用 HTTP BASIC 身份验证在请求中提供的。 有关详细信息,请参阅 .zip 推送部署参考。

对于 HTTP 基本身份验证,需使用应用服务部署凭据。 若要了解如何设置部署凭据,请参阅设置和重置用户级别凭据。

使用 cURL

以下示例使用 cURL 工具部署 .zip 文件。 替换占位符 <deployment_user>、<zip_file_path> 和 <app_name>。 出现 cURL 提示时,键入密码。

curl -X POST -u <deployment_user> --data-binary "@<zip_file_path>" https://<app_name>.scm.azurewebsites.net/api/zipdeploy

此请求从已上传的 .zip 文件触发推送部署。 可以使用 https://<app_name>.scm.azurewebsites.net/api/deployments 终结点查看当前和之前的部署,如以下 cURL 示例所示。 同样,使用应用的名称替换 <app_name>;使用部署凭据的用户名替换 <deployment_user>。

curl -u <deployment_user> https://<app_name>.scm.azurewebsites.net/api/deployments

异步 zip 部署

同步部署时,可能会收到与连接超时相关的错误。 将 ?isAsync=true 添加到 URL 能够以异步方式进行部署。 上传 zip 文件后,你会立即收到一条响应,其中的 Location 标头指向可轮询的部署状态 URL。 在轮询 Location 标头中提供的 URL 时,你会在该过程正在进行时收到 HTTP 202(已接受)响应,并在存档已扩展并且部署成功完成时收到 HTTP 200(正常)响应。

Microsoft Entra 身份验证

针对 zip 部署使用 HTTP 基本身份验证的替代方法是使用 Microsoft Entra 标识。 如果 SCM 站点禁用 HTTP BASIC 身份验证,则可能需要Microsoft Entra 标识。

需要为执行部署的用户或服务主体提供有效的Microsoft Entra 访问令牌。 可以使用 Azure CLI 的 az account get-access-token 命令检索访问令牌。 访问令牌在 HTTP POST 请求的身份验证标头中使用。

curl -X POST \
    --data-binary "@<zip_file_path>" \
    -H "Authorization: Bearer <access_token>" \
    "https://<app_name>.scm.azurewebsites.net/api/zipdeploy"

使用 PowerShell

下面的示例使用 Publish-AzWebapp 上传 .zip 文件。 替换占位符 <group-name>、<app-name> 和 <zip-file-path>。

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <zip-file-path>

此请求从已上传的 .zip 文件触发推送部署。

若要查看当前和之前的部署,请运行以下命令。 再次替换 <deployment-user>、<deployment-password> 和 <app-name> 占位符。

$username = "<deployment-user>"
$password = "<deployment-password>"
$apiUrl = "https://<app-name>.scm.azurewebsites.net/api/deployments"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password)))
$userAgent = "powershell/1.0"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -UserAgent $userAgent -Method GET

通过使用 Bicep 或 Azure 资源管理器 模板进行部署

你可以将包部署到 Flex Consumption 应用,作为 Bicep 或 Azure 资源管理器(ARM)模板部署的一部分。 定义一个使用 /onedeploy 扩展的 Microsoft.Web/sites/extensions 资源,并在 packageUri 属性中提供远程包 URL。

你必须将包文件命名为 released-package.zip。 Functions主机必须能够访问远程包的URL和部署存储容器。 直接将包上传到部署容器并不会部署包。

关于 Bicep 和 ARM 模板示例,请参见定义 Flex Consumption 部署包。

使用 Azure 资源管理器模板进行部署

你可以用Azure 资源管理器(ARM)模板的ZipDeploy扩展来推送你的 .zip 文件到函数应用。

示例 ZipDeploy ARM 模板

此模板包括生产槽和过渡槽,并部署到一个或另一个槽。 通常,你使用此模板将应用部署到预发布槽位,然后通过交换槽位,使新的 ZIP 包在生产槽位上运行。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServiceName": {
      "type": "string"
    },
    "deployToProduction": {
      "type": "bool",
      "defaultValue": false
    },
    "slot": {
      "type": "string",
      "defaultValue": "staging"
    },
    "packageUri": {
      "type": "secureString"
    }
  },
  "resources": [
    {
      "condition": "[parameters('deployToProduction')]",
      "type": "Microsoft.Web/sites/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/ZipDeploy', parameters('appServiceName'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    },
    {
      "condition": "[not(parameters('deployToProduction'))]",
      "type": "Microsoft.Web/sites/slots/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/{1}/ZipDeploy', parameters('appServiceName'), parameters('slot'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    }
  ]
}

首次部署时,你将直接部署到生产槽位。 有关详细信息,请参阅槽部署。

从部署包中运行函数

直接从部署包运行时,可以跳过将文件复制到目录中的 wwwroot 过程。 相反,Functions 运行时将该包挂载为只读的 wwwroot 目录。 此方法:

  • 减少文件复制锁的问题。
  • 验证在应用中运行的文件。
  • 提升 Azure 资源管理器 部署性能。
  • 可以减少冷启动时间,尤其是对于拥有大型 npm 包树的 JavaScript 应用。

Flex Consumption 套餐配置

Flex Consumption 应用默认是从一个包运行的。 不要添加 WEBSITE_RUN_FROM_PACKAGE 应用设置。 部署设置,包括存储容器及其认证方法,都是函数应用资源的属性。 有关更多信息,请参阅部署

高级和专用套餐配置

将 WEBSITE_RUN_FROM_PACKAGE 设置为 1,以直接从本地部署的包运行。 运行时在 Windows 上将该软件包存储在文件夹中,在 /home/data/SitePackages Linux 上则存储在c:\home\data\SitePackages文件夹中。

Consumption 包配置

支持 WEBSITE_RUN_FROM_PACKAGE 的值取决于操作系统:

操作系统 价值 Behavior
Windows 1 应用是从文件夹里 c:\home\data\SitePackages 的包运行的。
Linux <URL> 应用程序从指定 URL 的程序包中运行。 使用私有的 Azure Blob 存储 容器,通过管理身份访问。

重要说明

在 Linux 消费计划中运行且仍在使用已停用的 v3 运行时的函数应用,将于 2026 年 9 月 30 日后停止运行。 为了避免服务中断, 请将应用迁移到 v4 运行时。

在消耗计划中托管 Linux 上的函数应用的选项将于 2028 年 9 月 30 日停用。 Linux 消费计划未获取任何新功能或 语言版本。 消耗计划中Windows上运行的应用当前不受影响。 在停用日期之前,将应用迁移到 Flex Consumption 计划。

包部署注意事项

使用包部署和运行函数应用时,请牢记以下要求和限制:

  • 该软件包必须使用 .zip 格式。 不支持 TAR 和 GZIP 格式。
  • 最大包装容量为1GB。 部署在解压项目文件时会使用临时存储,因此应用也必须有足够的临时存储。 消耗计划为每个计划提供 500 MB 的临时存储空间。
  • 当你从包运行时,wwwroot 中的文件均为只读,包括在 Azure 门户中也是如此。
  • 你不能在从包里运行时使用本地缓存。
  • 请求远程构建时,不要设置 WEBSITE_RUN_FROM_PACKAGE。 而是设置 SCM_DO_BUILD_DURING_DEPLOYMENT=true。 在Linux上,同样设置为 ENABLE_ORYX_BUILD=true。
  • WEBSITE_RUN_FROM_PACKAGE 无法与 MSDeploy 配合使用。 改用压缩包部署。

添加 WEBSITE_RUN_FROM_PACKAGE 设置

可以通过以下几种方法添加、更新和删除函数应用设置:

如果更改函数应用设置,则需要重启函数应用。

从通过 ZIP 部署上传的包中运行

在部署该包之前,将 WEBSITE_RUN_FROM_PACKAGE 设置为 1。 ZIP 部署 API 会将包复制到 SitePackages 文件夹,而不是将其内容解压到 wwwroot。 部署还会创建一个 packagename.txt 文件,用于识别要挂载的包。 应用重启后,包会被挂载为只读 wwwroot 目录。 Linux Consumption 应用程序不支持此设置值,必须改为 从外部包 URL 运行。

当部署重启应用时,当前正在运行的函数执行会终止。 关于如何编写能够安全处理重启的函数,请参见 “写函数为无状态”。

从外部包URL运行

当您需要自行管理软件包存储时,请使用外部软件包 URL。 你需要这个选项才能在 Linux Consumption 应用上运行本地开发的包。 Flex Consumption 不支持此功能。

注释

你不能更改使用 WEBSITE_RUN_FROM_PACKAGE=1 从外部包 URL 运行的现有函数应用。 要使用外部包 URL,请创建一个新的函数应用,并将 WEBSITE_RUN_FROM_PACKAGE 设置为该包 URL。

使用私有的 Blob 存储 容器,并赋予函数应用对包的管理身份访问权。 使用托管身份,因为SAS令牌会过期并需要维护。 每当你发布更新包时,必须 手动同步触发器。 如果你直接更新该包而不更改其 URL,请先重启函数应用,再同步触发器。

手动上传一个包到 Azure Blob 存储

  1. 创建一个 .zip 部署包。

  2. 在 Azure 门户中,转到您的存储帐户。

  3. 在 数据存储中,选择 容器,然后创建或选择一个私有容器。

  4. 把包裹上传到集装箱。

  5. 选择上传的blob并复制其URL。 如果你不使用托管身份,可以生成一个 SAS URL。

  6. 在你的功能应用中,展开设置,选择环境变量,然后在应用设置标签页选择添加。

  7. 添加一个名为 WEBSITE_RUN_FROM_PACKAGE 的设置,并将包 URL 作为其值。

  8. 应用这些更改,重启应用,然后手动同步触发器。

使用托管标识从 Azure Blob 存储获取包

可以将 Azure Blob 存储 配置为使用 Microsoft Entra ID 授权请求。 此配置意味着可以依赖应用程序的托管标识,而不是生成会过期的 SAS 密钥。

默认情况下,将使用应用的系统分配的标识。 如果要指定用户分配的身份,可以将应用设置WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID设为该身份的资源ID。 该设置还可以接受 SystemAssigned 作为值,该值等效于将该设置省略。

要启用通过标识获取包的功能,请运行以下操作:

  1. 确保 Blob 已配置为私有访问。

  2. 向标识授予存储 Blob 数据读取器角色,其范围为包 blob。 有关创建角色分配的详细信息,请参阅 分配 Azure 角色以访问 Blob 数据。

  3. 将WEBSITE_RUN_FROM_PACKAGE的程序设置设为包的blob URL。 此 URL 通常采用 https://<storage-account-name>.blob.core.windows.net/<container-name>/<path-to-package> 或类似形式。

  4. 如果要指定用户分配的身份,可以将应用设置WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID设为该身份的资源ID。 此设置也可以接受 SystemAssigned 作为值,尽管这与完全省略设置相同。 资源 ID 是 Azure 中资源的标准表示形式。 对于用户分配的托管标识,这将是 /subscriptions/subid/resourcegroups/rg-name/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name。 可以在用户分配的托管标识的“设置”>>“属性”ID 中找到用户分配的托管标识的资源 ID。

部署自定义

部署过程假设推送的 .zip 文件包含随时可运行的应用。 默认情况下,不会运行自定义。 若要启用通过持续集成获取的同一生成进程,请将以下内容添加到应用程序设置:

SCM_DO_BUILD_DURING_DEPLOYMENT=true

使用 .zip 推送部署时,此设置默认为“false”。 持续集成部署的设置默认为“true”。 设置为“true”时,在部署期间将使用与部署相关的设置。 可以将这些设置配置为应用设置或在位于 .zip 文件根目录中的 .deployment 配置文件中进行配置。 有关详细信息,请参阅部署参考中的 Repository and deployment-related settings(存储库和与部署相关的设置)。

下载函数应用文件

如果你需要应用当前运行的完全相同的包,可以从为你的应用部署配置的 Blob 存储 容器下载:

  1. 在Azure门户的函数应用页面,展开设置,然后选择部署设置。

  2. 在 应用包位置下,注明用于部署的存储账户和容器。

  3. 进入该存储账户,展开 数据存储,然后选择 容器。

  4. 选择部署容器,选择当前包,然后选择 下载。

下载的包包含你部署的构建应用内容,可能与源项目不同。 每次部署都会覆盖当前包,部署容器不会提供部署历史。

对于通过CI/CD部署的应用,应将源项目保留在源代码管理中,并根据你的发布保留策略保留现成的构建工件。 使用保留的工件来重新部署特定的发布版本。 当你需要应用当前运行的完全相同的包,或者原始工件不再可用时,使用部署容器中的包。

下载函数应用文件

如果使用 Azure 门户中的编辑器创建了函数,则可以通过以下方式之一将现有函数应用项目下载为 .zip 文件:

  1. 登录 Azure 门户,并转到函数应用。

  2. 在“概述”选项卡中,选择“下载应用内容”。 选择下载选项,然后选择“下载”。

屏幕截图显示了用于下载函数应用项目的 Azure 门户页面。

所下载的 .zip 文件格式正确,可使用 .zip 推送部署将其重新发布到函数应用。 门户下载还可以添加在 Visual Studio 中直接打开函数应用所需的文件。

对于通过CI/CD部署的应用,应将源项目保留在源代码管理中,并根据你的发布保留策略保留现成的构建工件。 从仓库下载的源代码归档不是部署包。 使用你的部署工作流程来构建和部署项目。