如何通过GitHub Actions将Python版Azure Function部署至Azure门户？

function.json 的必要性与核心作用 #

• 结论：是否必须手动配置function.json，完全取决于当前使用的Azure Function Python编程模型：
  • v1 传统编程模型：必须为每个独立函数手动编写符合结构规范的function.json，省略会导致函数无法被平台识别
  • v2 最新编程模型（官方默认推荐）：通过Python装饰器定义函数的触发器、绑定规则，不需要手动创建、编辑function.json，构建流程会自动生成符合规范的文件
• function.json的核心作用：
  • 为平台定义单个函数的触发入口类型（HTTP触发、定时触发、队列触发等）及触发规则
  • 配置函数的输入、输出绑定规则（比如对接存储队列、Blob存储的连接参数、数据序列化格式）
  • 声明函数的专属运行时配置（重试策略、权限范围等）
• 常见操作误区：不要手动修改构建阶段自动生成的function.json，这类文件每次部署都会被流程覆盖，手动修改的内容会丢失，极易引发配置不匹配的运行错误

GitHub Actions 场景下的部署方案选型 #

• 选型结论：优先选择ZIP Deploy方案，其余两类方案不匹配新手部署Python Function的场景
• 各方案适配性对比：
  • ZIP Deploy：官方原生适配GitHub Actions部署流程，部署完成后运行文件为只读属性，无文件权限不一致、路径错位的问题，和Python运行时兼容性最高，是新手场景的标准推荐方案
  • Azure存储部署：需要额外配置Blob存储访问权限、网络连通性，操作复杂度高，一般仅用于离线、私有网络的大规模部署场景，普通新手无需选择
  • Serverless部署：依赖第三方Serverless Framework工具，需要额外配置工具鉴权、项目结构映射规则，自定义配置项多，和官方GitHub Actions流水线的适配成本高，问题排查路径长，不推荐新手使用
• 配套配置要求：使用ZIP Deploy时必须开启RUN_FROM_PACKAGE环境变量，可大幅降低大依赖场景下的部署超时、启动慢问题

可落地的部署排错与操作指引（覆盖90%常见失败场景） #

• 部署前必查前置项
  • 本地项目结构匹配编程模型规范：
    • v1模型规则：每个独立函数存放在单独子目录，目录下包含function.json、__init__.py，项目根目录放置requirements.txt、host.json
    • v2模型规则：项目根目录下的function_app.py通过装饰器声明所有函数，根目录放置requirements.txt、host.json
  • 目标Function App的运行时配置和本地完全匹配：Python版本、操作系统类型（Windows/Linux）、运行时主版本必须和本地开发环境一致，哪怕小版本不匹配都可能触发部署后启动失败
• GitHub Actions 流水线必查配置
  • 直接使用官方提供的Python Function部署Action，不要自行拼凑零散的部署步骤
  • 发布根目录明确指定为项目根目录，避免错把子目录作为发布路径
  • Workflow的授权范围要确保拥有目标Function App的Contributor级别权限，避免部署时返回403权限错误
• 常见失败问题排查路径
  • 部署后函数列表为空：检查是否将函数文件放到了错误的发布子目录，或function.json的触发器配置格式不合法
  • 部署后访问返回502错误：检查requirements.txt中的依赖是否和当前Python运行时版本兼容，是否混入了跨平台的二进制依赖（比如Windows平台编译的whl包部署到Linux运行时）
  • 部署流程超时：检查是否开启了RUN_FROM_PACKAGE配置，默认的解压式部署在大依赖场景下极易触发超时

内容的提问来源于stack exchange，提问作者Palmé