使用 Lambda 环境变量配置代码中的值

您可以使用环境变量来调整函数的行为，而无需更新代码。环境变量是存储在函数的版本特定配置中的一对字符串。Lambda 运行时使环境变量可用于您的代码，并设置其他环境变量，这些变量包含有关函数和调用请求的信息。

注意

为了提高安全性，建议使用 AWS Secrets Manager 而非环境变量来存储数据库凭证和其他敏感信息，例如 API 密钥或授权令牌。有关更多信息，请参阅使用 AWS Secrets Manager 创建和管理密钥。

环境变量不会在调用函数之前评估。您定义的任何值都将被视为文字字符串，且不会被展开。在函数代码中执行变量估算。

您可以使用 Lambda 控制台、AWS Command Line Interface（AWS CLI）、AWS Serverless Application Model（AWS SAM）或使用 AWS SDK 在 Lambda 中配置环境变量。

Console

您可以在函数的未发布版本上定义环境变量。发布一个版本时，会锁定该版本的环境变量以及其他特定于版本的配置设置。

您可以通过定义键和值为函数创建环境变量。您的函数使用键名来检索环境变量的值。

在 Lambda 控制台中设置环境变量

1. 打开 Lamba 控制台的 Functions（函数）页面。

2. 选择函数。

3. 选择 Configuration（配置），然后选择 Environment variables（环境变量）。

4. 在 Environment variables（环境变量）下，选择 Edit（编辑）。

5. 选择 Add environment variable (添加环境变量)。

6. 输入密钥和值。

   要求

   • 密钥以字母开头，并且至少为两个字符。

   • 键仅包含字母、数字和下划线字符 (_)。

   • Lambda 不会保留密钥。

   • 所有环境变量的总大小不超过 4 KB。

7. 选择 Save（保存）。

在控制台代码编辑器中生成环境变量列表

您可以在 Lambda 代码编辑器中生成环境变量列表。这是在编码时快速引用环境变量的方法。

1. 选择节点选项卡。

2. 选择环境变量选项卡。

3. 依次选择工具、显示环境变量。

在控制台代码编辑器中列出时，环境变量会保持加密状态。如果您为传输中的加密启用了加密帮助程序，这些设置则会保持不变。有关更多信息，请参阅 保护 Lambda 环境变量。

环境变量列表是只读的，仅在 Lambda 控制台上可用。当您下载函数的.zip 文件存档时，此文件并不包括在内；您也无法通过上传此文件来添加环境变量。

AWS CLI

以下示例在名为 my-function 的函数上设置两个环境变量。

aws lambda update-function-configuration \
  --function-name my-function \
  --environment "Variables={BUCKET=amzn-s3-demo-bucket,KEY=file.txt}"

使用 update-function-configuration 命令应用环境变量时，会替换 Variables 结构的整个内容。要在添加新环境变量时保留现有环境变量，请在请求中包含所有现有值。

要获取当前配置，请使用 get-function-configuration 命令。

aws lambda get-function-configuration \
  --function-name my-function

您应看到以下输出：

{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:111122223333:function:my-function",
    "Runtime": "nodejs20.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "amzn-s3-demo-bucket",
            "KEY": "file.txt"
        }
    },
    "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
    ...
}

您可以将 get-function-configuration 输出中的修订版 ID 作为参数传递给 update-function-configuration。此举可确保这些值在您读取配置和更新配置之间不会发生变化。

要配置函数的加密密钥，请设置 KMSKeyARN 选项。

aws lambda update-function-configuration \
  --function-name my-function \
  --kms-key-arn arn:aws:kms:us-east-2:111122223333:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

AWS SAM

您可以使用 AWS Serverless Application Model 来为您的函数配置环境变量。更新 template.yaml 文件中的 Environment 和 Variables 属性，然后运行 sam deploy。

例 template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An AWS Serverless Application Model template describing your function.
Resources:
  my-function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Description: ''
      MemorySize: 128
      Timeout: 120
      Handler: index.handler
      Runtime: nodejs18.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          BUCKET: amzn-s3-demo-bucket
          KEY: file.txt
      # Other function properties...

AWS SDKs

要使用 AWS SDK 管理环境变量，请使用以下 API 操作。

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

要了解更多信息，请参阅您首选编程语言的 AWS SDK 文档。

定义运行时环境变量

Lambda 运行时会在初始化过程中设置多个环境变量。大多数环境变量提供有关函数或运行时的信息。这些环境变量的键是预留 的，无法在函数配置中设置。

预留环境变量

• _HANDLER – 函数上配置的处理程序位置。

• _X_AMZN_TRACE_ID – X-Ray 跟踪标头。此环境变量会随着每次调用发生变化。

  • 此环境变量不是为仅限操作系统的运行时系统（provided 运行时系统系列）定义的。您可以使用来自 下一个调用 的 Lambda-Runtime-Trace-Id 响应标头设置用于自定义运行时的 _X_AMZN_TRACE_ID。

  • 对于 Java 运行时系统版本 17 及更高版本，不使用此环境变量。相反，Lambda 将把跟踪信息存储在 com.amazonaws.xray.traceHeader 系统属性中。

• AWS_DEFAULT_REGION – 执行 Lambda 函数的默认 AWS 区域。

• AWS_REGION – 执行 Lambda 函数的 AWS 区域。如果定义了该值，该值将会覆盖 AWS_DEFAULT_REGION。

  • 有关在 AWS SDK 中使用 AWS 区域 环境变量的更多信息，请参阅《AWS SDK 和工具参考指南》中的 AWS 区域。

• AWS_EXECUTION_ENV – 运行时标识符，前缀为 AWS_Lambda_（例如 AWS_Lambda_java8）。此环境变量不是为仅限操作系统的运行时系统（provided 运行时系统系列）定义的。

• AWS_LAMBDA_FUNCTION_NAME – 函数的名称。

• AWS_LAMBDA_FUNCTION_MEMORY_SIZE – 对函数可用的内存量（以 MB 为单位）。

• AWS_LAMBDA_FUNCTION_VERSION – 要执行的函数的版本。

• AWS_LAMBDA_INITIALIZATION_TYPE – 函数的初始化类型，即 on-demand、provisioned-concurrency 或 snap-start。有关信息，请参阅配置预置并发或 使用 Lambda SnapStart 提高启动性能。

• AWS_LAMBDA_LOG_GROUP_NAME、AWS_LAMBDA_LOG_STREAM_NAME – Amazon CloudWatch Logs 组和函数的流名称。AWS_LAMBDA_LOG_GROUP_NAME 和 AWS_LAMBDA_LOG_STREAM_NAME 环境变量在 Lambda SnapStart 函数中不可用。

• AWS_ACCESS_KEY、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEYAWS_SESSION_TOKEN – 从函数的执行角色中获取的访问密钥。

• AWS_LAMBDA_RUNTIME_API –（自定义运行时）运行时 API 的主机和端口。

• LAMBDA_TASK_ROOT – Lambda 函数代码的路径。

• LAMBDA_RUNTIME_DIR – 运行时库的路径。

以下附加环境变量并非预留，可以在函数配置中扩展。

非预留环境变量

• LANG – 运行时的区域设置 (en_US.UTF-8)。

• PATH – 执行路径 (/usr/local/bin:/usr/bin/:/bin:/opt/bin)。

• LD_LIBRARY_PATH – 系统库路径 (/var/lang/lib:/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib)。

• NODE_PATH – (Node.js) Node.js 库路径 (/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules)。

• PYTHONPATH –（Python 2.7、3.6、3.8）Python 库路径 ($LAMBDA_RUNTIME_DIR)。

• GEM_PATH –（Ruby）Ruby 库路径 ($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0)。

• AWS_XRAY_CONTEXT_MISSING – 对于 X-Ray 跟踪，Lambda 会将其设置为 LOG_ERROR，以避免从 X-Ray 开发工具包引发运行时错误。

• AWS_XRAY_DAEMON_ADDRESS – 对于 X-Ray 跟踪，X-Ray 进程守护程序的 IP 地址和端口。

• AWS_LAMBDA_DOTNET_PREJIT：对于 .NET 6 和 NET 7 运行时系统，请将此变量设置为启用或禁用 .NET 特定的运行时系统优化。值包括 always、never 和 provisioned-concurrency。有关更多信息，请参阅 为函数配置预置并发。

• TZ – 环境的时区 (:UTC)。执行环境使用 NTP 同步系统时钟。

显示的示例值反映了最新的运行时。特定变量或其值是否存在会因早先的运行时而异。

环境变量的示例场景

您可以使用环境变量来自定义测试环境和生产环境中的函数行为。例如，您可以创建两个具有相同代码但不同配置的函数。一个函数连接到测试数据库，另一个函数连接到生产数据库。在这种情况下，您可以使用环境变量向函数传递数据库的主机名和其他连接详细信息。

以下示例说明如何将数据库主机和数据库名称定义为环境变量。

如果希望测试环境生成比生产环境更多的调试信息，可以设置环境变量来配置测试环境使用更详细的日志记录或跟踪。