将 .zip 文件归档用于 Python Lambda 函数 - Amazon Lambda
Python 中的运行时系统依赖项创建不含依赖项的 .zip 部署包创建含依赖项的 .zip 部署包依赖项搜索路径和包含运行时系统的库使用 __pycache__ 文件夹使用原生库创建 .zip 部署包使用 .zip 文件创建和更新 Python Lambda 函数
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

将 .zip 文件归档用于 Python Lambda 函数

Amazon Lambda 函数的代码包含一个 .py 文件，其中包含函数的处理程序代码，以及代码所依赖的任何其他包和模块。要将此函数部署到 Lambda，您可以使用部署包。此包可以是 .zip 文件归档或容器映像。有关在 Python 中使用容器映像的更多信息，请参阅使用容器映像部署 Python Lambda 函数。

要创建 .zip 文件归档格式的部署包，可以使用命令行工具内置的 .zip 文件归档实用工具或任何其他 .zip 文件实用工具（例如 7zip）。以下各部分中显示的示例假设您在 Linux 或 macOS 环境中使用命令行 zip 工具。要在 Windows 中使用相同命令，您可以安装 Windows Subsystem for Linux，以获取 Windows 集成版本的 Ubuntu 和 Bash。

请注意，Lambda 使用 POSIX 文件权限，因此在创建 .zip 文件归档之前，您可能需要为部署包文件夹设置权限。

Python 中的运行时系统依赖项

对于使用 Python 运行时系统的 Lambda 函数，依赖项可以是任何 Python 程序包或模块。使用 .zip 存档部署函数时，可以使用函数代码或使用 Lambda 层将这些依赖项添加到 .zip 文件中。层是可以包含其他代码或其他内容的单独的 .zip 文件。要了解在 Python 中使用 Lambda 层的更多信息，请参阅使用 Python Lambda 函数的层。

Lambda Python 运行时系统包含 适用于 Python (Boto3) 的 Amazon SDK 及其依赖项。Lambda 会在运行时系统中为您无法添加自定义依赖项的部署场景提供开发工具包。这些场景包括使用内置代码编辑器在控制台中创建函数，或者使用 Amazon Serverless Application Model（Amazon SAM）或 Amazon CloudFormation 模板中的内联函数。

Lambda 会定期更新 Python 运行时系统中的库，以包含最新更新和安全补丁。如果函数使用运行时系统中包含的 Boto3 SDK 版本，但部署包包含开发工具包依赖项，可能会导致版本不一致问题。例如，部署包可能包含开发工具包依赖项 urllib3。当 Lambda 在运行时系统中更新开发工具包时，运行时系统的新版本与部署包中的 urllib3 版本之间的兼容性问题可能会导致您的函数失败。

重要

为了保持对依赖项的完全控制并避免可能的版本不一致问题，我们建议您将所有函数的依赖项添加到部署包中，即使它们的版本已包含在 Lambda 运行时系统中也是如此。这包括 Boto3 SDK。

要查找正在使用的运行时系统中包含哪个版本的 SDK for Python（Boto3），请参阅 包含运行时的 SDK 版本。

在 Amazon 责任共担模式下，您负责管理函数部署包中的所有依赖项。这包括应用更新和安全补丁。要更新函数部署包中的依赖项，请先创建一个新的 .zip 文件，然后将其上传到 Lambda 中。有关更多信息，请参阅 创建含依赖项的 .zip 部署包 和 使用 .zip 文件创建和更新 Python Lambda 函数。

创建不含依赖项的 .zip 部署包

如果您的函数代码没有依赖项，则 .zip 文件仅包含带有函数处理程序代码的 .py 文件。使用您的首选 zip 实用工具创建一个 .zip 文件，并将 .py 文件置于根目录中。如果 .py 文件不在 .zip 文件的根目录下，Lambda 将无法运行代码。

要了解如何部署 .zip 文件以创建新的 Lambda 函数或更新现有函数，请参阅 使用 .zip 文件创建和更新 Python Lambda 函数。

创建含依赖项的 .zip 部署包

如果函数代码依赖其他包或模块，可以使用函数代码或使用 Lambda 层将这些依赖项添加到 .zip 文件中。本部分中的说明向您展示了如何将依赖项包含在 .zip 部署包中。要让 Lambda 运行代码，必须将包含处理程序代码和所有函数依赖项的.py 文件安装在.zip 文件的根目录下。

假设函数代码保存在名为 lambda_function.py 的文件中。以下示例 CLI 命令将创建名为 my_deployment_package.zip 的 .zip 文件，其中包含函数代码及其依赖项。您可以将依赖项直接安装到项目目录中的文件夹，也可以使用 Python 虚拟环境。

要创建部署包（项目目录）

  1. 导航到包含 lambda_function.py 源代码文件的项目目录。在此示例中，该目录名为 my_function。

    cd my_function

  2. 创建将在其中安装依赖项的名为 package 的新目录。

    mkdir package

    请注意，对于 .zip 部署包，Lambda 期望源代码及其依赖项全部位于 .zip 文件的根目录中。但是，直接在项目目录中安装依赖项可能会引入大量新文件和文件夹，使在 IDE 中导航变得困难。您可以在此目录中创建一个单独的 package 目录，以将依赖项与源代码分开。

  3. 在 package 目录中安装依赖项。以下示例将使用 pip 从 Python 程序包索引中安装 Boto3 SDK。如果函数代码使用您自己创建的 Python 程序包，请将这类程序包保存在 package 目录中。

    pip install --target ./package boto3

  4. 创建包含已安装库在根目录中的 .zip 文件。

    cd package
zip -r ../my_deployment_package.zip .

    这样会在您的项目目录中生成一个 my_deployment_package.zip 文件。

  5. 将 lambda_function.py 文件添加到 .zip 文件的根目录中。

    cd ..
zip my_deployment_package.zip lambda_function.py

    .zip 文件应采用扁平目录结构，将函数的处理程序代码和所有依赖项文件夹安装在根目录中，如下所示。

    my_deployment_package.zip
|- bin
|  |-jp.py
|- boto3
|  |-compat.py
|  |-data
|  |-docs
...
|- lambda_function.py

    如果包含函数的处理程序代码的 .py 文件不在 .zip 文件的根目录中，Lambda 将无法运行代码。

要创建部署包（虚拟环境）

  1. 在项目目录中创建和激活虚拟环境。在此示例中，项目目录名为 my_function。

    ~$ cd my_function
~/my_function$ python3.13 -m venv my_virtual_env
~/my_function$ source ./my_virtual_env/bin/activate

  2. 使用 pip 安装所需的库。下面的示例将安装 Boto3 SDK

    (my_virtual_env) ~/my_function$ pip install boto3

  3. 使用 pip show 在虚拟环境中查找 pip 安装依赖项的位置。

    (my_virtual_env) ~/my_function$ pip show <package_name>

    pip 在其中安装库的文件夹可能名为 site-packages 或 dist-packages。此文件夹可能位于 lib/python3.x 或 lib64/python3.x 目录中（其中 python3.x 代表正在使用的 Python 版本）。

  4. 停用虚拟环境

    (my_virtual_env) ~/my_function$ deactivate

  5. 导航到包含使用 pip 安装了依赖项的目录，并在项目目录中创建一个 .zip 文件，将已安装的依赖项置于其根目录。在此示例中，pip 已在 my_virtual_env/lib/python3.13/site-packages 目录中安装了所需依赖项。

    ~/my_function$ cd my_virtual_env/lib/python3.13/site-packages
~/my_function/my_virtual_env/lib/python3.13/site-packages$ zip -r ../../../../my_deployment_package.zip .

  6. 导航到包含处理程序代码的 .py 文件所在的项目目录的根目录，然后将该文件添加到 .zip 程序包的根目录中。在此示例中，您的函数代码文件名为 lambda_function.py。

    ~/my_function/my_virtual_env/lib/python3.13/site-packages$ cd ../../../../
~/my_function$ zip my_deployment_package.zip lambda_function.py

依赖项搜索路径和包含运行时系统的库

在代码中使用 import 语句时，Python 运行时系统会搜索其搜索路径中的目录，直到找到相应模块或包。默认情况下，运行时系统搜索的第一个位置是解压缩并安装 .zip 部署包的目录 (/var/task)。如果部署包含有包含运行时系统的库的某个版本，则此版本将优先于运行时系统中包含的版本。部署包中的依赖项也优先于层中的依赖项。

当您向层添加依赖项时，Lambda 会将其提取到 /opt/python/lib/python3.x/site-packages（其中 python3.x 表示正在使用的运行时系统版本）或 /opt/python 中。在搜索路径中，这些目录优先于含有包含运行时系统的库和安装了 pip 的库的目录（/var/runtime 和 /var/lang/lib/python3.x/site-packages）。因此，函数层中的库优先于运行时系统中包含的版本。

注意

在 Python 3.11 托管式运行时系统和基本映像中，Amazon SDK 及其依赖项安装在 /var/lang/lib/python3.11/site-packages 目录中。

通过添加以下代码段，您可以查看 Lambda 函数的完整搜索路径。

import sys
      
search_path = sys.path
print(search_path)
注意

由于部署包或层中的依赖项优先于包含运行时系统的库，因此如果您在包中包含 urllib3 等开发工具包依赖项而不包含开发工具包，可能会导致版本不一致问题。如果您要部署自己的 Boto3 依赖项版本，则还必须将 Boto3 作为依赖项部署到部署包中。我们建议您打包函数的所有依赖项，即使运行时系统中包含各种版本也是如此。

您还可以在 .zip 程序包内的单独文件夹中添加依赖项。例如，您可以将某个 Boto3 SDK 版本添加到 .zip 程序包中名为 common 的文件夹中。解压缩并安装 .zip 程序包后，此文件夹将放置在 /var/task 目录中。要在代码中使用 .zip 部署包中某个文件夹中的依赖项，请使用 import from 语句。例如，要使用 .zip 程序包中名为 common 的文件夹中的 Boto3 版本，请使用以下语句。

from common import boto3

使用 __pycache__ 文件夹

我们建议您不要在函数部署包中包含 __pycache__ 文件夹。在具有不同架构或操作系统的生成计算机上编译的 Python 字节码可能与 Lambda 执行环境不兼容。

使用原生库创建 .zip 部署包

如果您的函数仅使用纯 Python 程序包和模块，则可以使用 pip install 命令在任何本地生成计算机上安装依赖项并创建 .zip 文件。许多流行的 Python 库（包括 NumPy 和 Pandas）都不是纯 Python 的，包含用 C 或 C++ 编写的代码。将包含 C/C++ 代码的库添加到部署包时，必须正确构建包以确保它与 Lambda 执行环境兼容。

Python 程序包索引（PyPI）上提供的大多数包都以“wheel”（.whl 文件）的形式提供。.whl 文件是一种 zip 文件，它包含已构建的分发，其中包含针对特定操作系统和指令集架构的预编译二进制文件。要使部署包与 Lambda 兼容，您需要为 Linux 操作系统和函数的指令集架构安装轮子。

有些包可能只能作为源分发提供。对于这些包，您需要自己编译和构建 C/C++ 组件。

要查看哪些分发可用于所需的包，请执行以下操作：

  1. 在 Python 程序包索引主页上搜索程序包名称。

  2. 选择要使用的包的版本。

  3. 选择下载文件。

使用已构建分发（wheel）

要下载与 Lambda 兼容的 wheel，请使用 pip --platform 选项。

如果 Lambda 函数使用 x86_64 指令集架构，请运行以下 pip install 命令以在 package 目录中安装兼容的 wheel。将 --python 3.x 替换为正在使用的 Python 运行时系统版本。

pip install \
--platform manylinux2014_x86_64 \
--target=package \
--implementation cp \
--python-version 3.x \
--only-binary=:all: --upgrade \
<package_name>

如果函数使用的是 arm64 指令集架构，请运行以下命令。将 --python 3.x 替换为正在使用的 Python 运行时系统版本。

pip install \
--platform manylinux2014_aarch64 \
--target=package \
--implementation cp \
--python-version 3.x \
--only-binary=:all: --upgrade \
<package_name>

使用源分发

如果包仅作为源分发提供，则需要自己构建 C/C++ 库。要使包与 Lambda 执行环境兼容，您需要在使用相同的 Amazon Linux 2 操作系统的环境中构建包。您可以通过在 Amazon EC2 Linux 实例中构建包来实现此目的。

要了解如何启动并连接到 Amazon EC2 Linux 实例，请参阅《适用于 Linux 实例的 Amazon EC2 用户指南》中的教程：Amazon EC2 Linux 实例入门。

使用 .zip 文件创建和更新 Python Lambda 函数

创建 .zip 部署包后，您可以用其创建新的 Lambda 函数或更新现有的 Lambda 函数。您可以使用 Lambda 控制台、Amazon Command Line Interface 和 Lambda API 部署 .zip 程序包。您也可以使用 Amazon Serverless Application Model（Amazon SAM）和 Amazon CloudFormation 创建和更新 Lambda 函数。

Lambda 的 .zip 部署包的最大大小为 250MB（已解压缩）。请注意，此限制适用于您上传的所有文件（包括任何 Lambda 层）的组合大小。

Lambda 运行时需要权限才能读取部署包中的文件。在 Linux 权限八进制表示法中，Lambda 对于不可执行文件（rw-r--r--）需要 644 个权限，对于目录和可执行文件需要 755 个权限（rwxr-xr-x）。

在 Linux 和 MacOS 中，使用 chmod 命令更改部署包中文件和目录的文件权限。例如，要为不可执行文件提供正确的权限，请运行以下命令。

chmod 644 <filepath>

要在 Windows 中更改文件权限，请参阅 Microsoft Windows 文档中的 Set, View, Change, or Remove Permissions on an Object。

注意

如果您不向 Lambda 授予访问部署包中目录所需的权限，Lambda 会将这些目录的权限设置为 755（rwxr-xr-x）。

使用控制台通过 .zip 文件创建和更新函数

要创建新函数，必须先在控制台中创建该函数，然后上传您的 .zip 归档。要更新现有函数，请打开函数页面，然后按照相同的步骤添加更新的 .zip 文件。

如果您的 .zip 文件小于 50MB，则可以通过直接从本地计算机上传该文件来创建或更新函数。对于大于 50MB 的 .zip 文件，必须首先将您的程序包上传到 Amazon S3 存储桶。有关如何使用 Amazon Web Services Management Console 将文件上传到 Amazon S3 存储桶的说明，请参阅 Amazon S3 入门。要使用 Amazon CLI 上传文件，请参阅《Amazon CLI 用户指南》中的移动对象。

注意

您无法更改现有函数的部署包类型（.zip 或容器映像）。例如，您无法将容器映像函数转换为使用 .zip 文件归档。您必须创建新函数。

创建新函数（控制台）

  1. 打开 Lambda 控制台的“函数”页面，然后选择创建函数。

  2. 选择从头开始创作。

  3. 在基本信息中，执行以下操作：

    1. 对于函数名称，输入函数的名称。

    2. 对于运行时系统，选择要使用的运行时系统。

    3. （可选）对于架构，选择要用于函数的指令集架构。默认架构为 x86_64。确保您的函数的 .zip 部署包与您选择的指令集架构兼容。

  4. （可选）在 Permissions（权限）下，展开 Change default execution role（更改默认执行角色）。您可以创建新的执行角色，也可以使用现有角色。

  5. 选择 Create function (创建函数)。Lambda 使用您选择的运行时系统创建基本“Hello world”函数。

从本地计算机上传 .zip 归档（控制台）

  1. 在 Lambda 控制台的“函数”页面中，选择要为其上传 .zip 文件的函数。

  2. 选择代码选项卡。

  3. 在代码源窗格中，选择上传自。

  4. 选择 .zip 文件。

  5. 要上传 .zip 文件，请执行以下操作：

    1. 选择上传，然后在文件选择器中选择您的 .zip 文件。

    2. 选择打开。

    3. 选择保存。

从 Amazon S3 存储桶上传 .zip 归档（控制台）

  1. 在 Lambda 控制台的“函数”页面中，选择要为其上传新 .zip 文件的函数。

  2. 选择代码选项卡。

  3. 在代码源窗格中，选择上传自。

  4. 选择 Amazon S3 位置。

  5. 粘贴 .zip 文件的 Amazon S3 链接 URL，然后选择保存。

使用控制台代码编辑器更新 .zip 文件函数

对于某些带有 .zip 部署包的函数，您可以使用 Lambda 控制台的内置代码编辑器直接更新函数代码。要使用此功能，函数必须满足以下条件：

  • 函数必须使用一种解释性语言运行时系统（Python、Node.js 或 Ruby）

  • 函数的部署包必须小于 50 MB（未压缩状态）。

带有容器映像部署包的函数的代码不能直接在控制台中编辑。

要使用控制台代码编辑器更新函数代码。

  1. 打开 Lambda 控制台的“函数”页面，然后选择函数。

  2. 选择代码选项卡。

  3. 在代码源窗格中，选择源代码文件并在集成的代码编辑器中对其进行编辑。

  4. 在部署部分，选择部署以更新函数的代码：

    Lambda 控制台代码编辑器中的“部署”按钮

使用 Amazon CLI 通过 .zip 文件创建和更新函数

您可以使用 Amazon CLI 创建新函数或使用 .zip 文件更新现有函数。使用 create-function 和 update-function-code 命令部署 .zip 程序包。如果您的 .zip 文件小于 50MB，则可以从本地生成计算机上的文件位置上传 .zip 程序包。对于较大的文件，必须从 Amazon S3 存储桶上传 .zip 程序包。有关如何使用 Amazon CLI 将文件上传到 Amazon S3 存储桶的说明，请参阅《Amazon CLI 用户指南》中的移动对象。

注意

如果您使用 Amazon CLI 从 Amazon S3 存储桶上传 .zip 文件，则该存储桶必须与您的函数位于同一个 Amazon Web Services 区域 中。

要通过 Amazon CLI 使用 .zip 文件创建新函数，则必须指定以下内容：

  • 函数的名称 (--function-name)

  • 函数的运行时系统 (--runtime)

  • 函数的执行角色 (--role) 的 Amazon 资源名称（ARN）

  • 函数代码 (--handler) 中处理程序方法的名称

还必须指定 .zip 文件的位置。如果 .zip 文件位于本地生成计算机上的文件夹中，请使用 --zip-file 选项指定文件路径，如以下示例命令所示。

aws lambda create-function --function-name myFunction \
--runtime python3.13 --handler lambda_function.lambda_handler \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--zip-file fileb://myFunction.zip

要指定 .zip 文件在 Amazon S3 存储桶中的位置，请使用 --code 选项，如以下示例命令所示。您只需对版本控制对象使用 S3ObjectVersion 参数。

aws lambda create-function --function-name myFunction \
--runtime python3.13 --handler lambda_function.lambda_handler \
--role arn:aws:iam::111122223333:role/service-role/my-lambda-role \
--code S3Bucket=amzn-s3-demo-bucket,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion

要使用 CLI 更新现有函数，请使用 --function-name 参数指定函数的名称。您还必须指定要用于更新函数代码的 .zip 文件的位置。如果 .zip 文件位于本地生成计算机上的文件夹中，请使用 --zip-file 选项指定文件路径，如以下示例命令所示。

aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip

要指定 .zip 文件在 Amazon S3 存储桶中的位置，请使用 --s3-bucket 和 --s3-key 选项，如以下示例命令所示。您只需对版本控制对象使用 --s3-object-version 参数。

aws lambda update-function-code --function-name myFunction \
--s3-bucket amzn-s3-demo-bucket --s3-key myFileName.zip --s3-object-version myObject Version

使用 Lambda API 通过 .zip 文件创建和更新函数

要使用 .zip 文件归档创建和更新函数，请使用以下 API 操作：

使用 Amazon SAM 通过 .zip 文件创建和更新函数

Amazon Serverless Application Model（Amazon SAM）是一个工具包，可帮助简化在 Amazon 上构建和运行无服务器应用程序的过程。您可以在 YAML 或 JSON 模板中为应用程序定义资源，并使用 Amazon SAM 命令行界面（Amazon SAM CLI）构建、打包和部署应用程序。当您通过 Amazon SAM 模板构建 Lambda 函数时，Amazon SAM 会使用您的函数代码和您指定的任何依赖项自动创建 .zip 部署包或容器映像。要了解有关使用 Amazon SAM 构建和部署 Lambda 函数的更多信息，请参阅《Amazon Serverless Application Model 开发人员指南》中的 Amazon SAM 入门。

您可以使用 Amazon SAM 创建使用现有 .zip 文件归档的 Lambda 函数。要使用 Amazon SAM 创建 Lambda 函数，您可以将 .zip 文件保存在 Amazon S3 存储桶或生成计算机上的本地文件夹中。有关如何使用 Amazon CLI 将文件上传到 Amazon S3 存储桶的说明，请参阅《Amazon CLI 用户指南》中的移动对象。

在 Amazon SAM 模板中，AWS::Serverless::Function 资源将指定 Lambda 函数。在此资源中，设置以下属性以创建使用 .zip 文件归档的函数：

  • PackageType – 设置为 Zip

  • CodeUri – 设置为函数代码的 Amazon S3 URI、本地文件夹的路径或 FunctionCode 对象

  • Runtime – 设置为您选择的运行时系统

使用 Amazon SAM，如果 .zip 文件大于 50MB，则不需要先将其上传到 Amazon S3 存储桶。Amazon SAM 可以从本地生成计算机上的某个位置上传最大允许大小为 250MB（已解压缩）的 .zip 程序包。

要了解有关在 Amazon SAM 中使用 .zip 文件部署函数的更多信息，请参阅《Amazon SAM 开发人员指南》中的 AWS::Serverless::Function。

使用 Amazon CloudFormation 通过 .zip 文件创建和更新函数

您可以使用 Amazon CloudFormation 创建使用 .zip 文件归档的 Lambda 函数。要从 .zip 文件创建 Lambda 函数，必须先将您的文件上传到 Amazon S3 存储桶。有关如何使用 Amazon CLI 将文件上传到 Amazon S3 存储桶的说明，请参阅《Amazon CLI 用户指南》中的移动对象。

对于 Node.js 和 Python 运行时系统，您还可以在 Amazon CloudFormation 模板中提供内联源代码。然后 Amazon CloudFormation 会在您构建函数时创建包含代码的 .zip 文件。

使用现有 .zip 文件

在 Amazon CloudFormation 模板中，AWS::Lambda::Function 资源将指定 Lambda 函数。在此资源中，设置以下属性以创建使用 .zip 文件归档的函数：

  • PackageType – 设置为 Zip

  • Code – 在 S3Bucket 和 S3Key 字段中输入 Amazon S3 存储桶名称和 .zip 文件名。

  • Runtime – 设置为您选择的运行时系统

从内联代码创建 .zip 文件

您可以在 Amazon CloudFormation 模板中声明使用 Python 或 Node.js 内联编写的简单函数。由于代码嵌入在 YAML 或 JSON 中，因此您无法向部署包添加任何外部依赖关系。这意味着您的函数必须使用运行时系统中包含的 Amazon SDK 版本。模板的要求（例如必须转义某些字符）也让使用 IDE 的语法检查和代码完成功能变得更加困难。这意味着模板可能需要额外的测试。由于这些限制，内联声明函数最适合用于不经常更改的非常简单的代码。

要从 Node.js 和 Python 运行时系统的内联代码创建 .zip 文件，请在模板的 AWS::Lambda::Function 资源中设置以下属性：

  • PackageType – 设置为 Zip

  • Code – 在 ZipFile 字段中输入函数代码

  • Runtime – 设置为您选择的运行时系统

Amazon CloudFormation 生成的 .zip 文件不能超过 4MB。要了解有关在 Amazon CloudFormation 中使用 .zip 文件部署函数的更多信息，请参阅《Amazon CloudFormation 用户指南》中的 AWS::Lambda::Function。