# 使用 Lambda 环境变量 环境变量 您可以使用环境变量来调整函数的行为，而无需更新代码。环境变量是存储在函数的版本特定配置中的一对字符串。Lambda 运行时使环境变量可用于您的代码，并设置其他环境变量，这些变量包含有关函数和调用请求的信息。 **注意** 为了提高安全性，建议使用 Amazon Secrets Manager 而非环境变量来存储数据库凭证和其他敏感信息，例如 API 密钥或授权令牌。有关更多信息，请参阅 [在 Lambda 函数中使用 Secrets Manager 密钥](with-secrets-manager.md)。 环境变量不会在调用函数之前评估。您定义的任何值都将被视为文字字符串，且不会被展开。在函数代码中执行变量估算。 ## 创建 Lambda 环境变量 创建环境变量 您可以使用 Lambda 控制台、Amazon Command Line Interface（Amazon CLI）、Amazon Serverless Application Model（Amazon SAM）或使用 Amazon SDK 在 Lambda 中配置环境变量。 ------ #### [ Console ] 您可以在函数的未发布版本上定义环境变量。发布一个版本时，会锁定该版本的环境变量以及其他[特定于版本的配置设置](configuration-versions.md)。 您可以通过定义键和值为函数创建环境变量。您的函数使用键名来检索环境变量的值。 **在 Lambda 控制台中设置环境变量** 1. 打开 Lamba 控制台的 [Functions](https://console.amazonaws.cn/lambda/home#/functions)（函数）页面。 1. 选择函数。 1. 选择**配置**，然后选择**环境变量**。 1. 在 **Environment variables (环境变量)** 下，选择 **Edit (编辑)**。 1. 选择 **Add environment variable (添加环境变量)**。 1. 输入键和值。 **要求** + 密钥以字母开头，并且至少为两个字符。 + 键仅包含字母、数字和下划线字符 (`_`)。 + [Lambda 不会保留](#configuration-envvars-runtime)密钥。 + 所有环境变量的总大小不超过 4 KB。 1. 选择**保存**。 **在控制台代码编辑器中生成环境变量列表** 您可以在 Lambda 代码编辑器中生成环境变量列表。这是在编码时快速引用环境变量的方法。 1. 选择**节点**选项卡。 1. 向下滚动到代码编辑器的**环境变量**部分。下面列出了现有的环境变量： ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/env-var.png) 1. 要创建新的环境变量，请选择加号（![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/add-plus.png)）： ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/create-env-var.png) 在控制台代码编辑器中列出时，环境变量会保持加密状态。如果您为传输中的加密启用了加密帮助程序，这些设置则会保持不变。有关更多信息，请参阅 [保护 Lambda 环境变量](configuration-envvars-encryption.md)。 环境变量列表是只读的，仅在 Lambda 控制台上可用。当您下载函数的.zip 文件存档时，此文件并不包括在内；您也无法通过上传此文件来添加环境变量。 ------ #### [ Amazon 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": "nodejs24.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 ``` ------ #### [ Amazon SAM ] 您可以使用 [Amazon Serverless Application Model](https://docs.amazonaws.cn//serverless-application-model/latest/developerguide/serverless-getting-started.html ) 来为您的函数配置环境变量。更新 `template.yaml` 文件中的 [Environment](https://docs.amazonaws.cn//serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-environment) 和 [Variables](https://docs.amazonaws.cn//AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html#cfn-lambda-function-environment-variables) 属性，然后运行 [sam deploy](https://docs.amazonaws.cn//serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html)。 **Example 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: nodejs24.x Architectures: - x86_64 EphemeralStorage: Size: 10240 Environment: Variables: BUCKET: amzn-s3-demo-bucket KEY: file.txt # Other function properties... ``` ------ #### [ Amazon SDKs ] 要使用 Amazon SDK 管理环境变量，请使用以下 API 操作。 + [UpdateFunctionConfiguration](https://docs.amazonaws.cn/lambda/latest/api/API_UpdateFunctionConfiguration.html) + [GetFunctionConfiguration](https://docs.amazonaws.cn/lambda/latest/api/API_GetFunctionConfiguration.html) + [CreateFunction](https://docs.amazonaws.cn/lambda/latest/api/API_CreateFunction.html) 要了解更多信息，请参阅您首选编程语言的 [Amazon SDK 文档](https://www.amazonaws.cn/developer/tools/)。 ------ ## 环境变量的示例场景 您可以使用环境变量来自定义测试环境和生产环境中的函数行为。例如，您可以创建两个具有相同代码但不同配置的函数。一个函数连接到测试数据库，另一个函数连接到生产数据库。在这种情况下，您可以使用环境变量向函数传递数据库的主机名和其他连接详细信息。 以下示例说明如何将数据库主机和数据库名称定义为环境变量。 ![\[\]](http://docs.amazonaws.cn/lambda/latest/dg/images/console-env.png) 如果希望测试环境生成比生产环境更多的调试信息，可以设置环境变量来配置测试环境使用更详细的日志记录或跟踪。 例如，您可以在测试环境中设置一个环境变量，其键为 `LOG_LEVEL`，值表示调试或跟踪的日志级别。然后，在 Lambda 函数的代码中，您可以使用此环境变量来设置日志级别。 以下 Python 和 Node.js 代码示例说明如何实现这一目标。这些示例假设您的环境变量在 Python 中的值为 `DEBUG`，在 Node.js 中的值为 `debug`。 ------ #### [ Python ] **Example 设置日志级别的 Python 代码** ``` import os import logging # Initialize the logger logger = logging.getLogger() # Get the log level from the environment variable and default to INFO if not set log_level = os.environ.get('LOG_LEVEL', 'INFO') # Set the log level logger.setLevel(log_level) def lambda_handler(event, context): # Produce some example log outputs logger.debug('This is a log with detailed debug information - shown only in test environment') logger.info('This is a log with standard information - shown in production and test environments') ``` ------ #### [ Node.js (ES module format) ] **Example 设置日志级别的 Node.js 代码** 此示例使用 `winston` 日志记录库。使用 npm 将此库添加到函数的部署包中。有关更多信息，请参阅 [创建含依赖项的 .zip 部署包](nodejs-package.md#nodejs-package-create-dependencies)。 ``` import winston from 'winston'; // Initialize the logger using the log level from environment variables, defaulting to INFO if not set const logger = winston.createLogger({ level: process.env.LOG_LEVEL || 'info', format: winston.format.json(), transports: [new winston.transports.Console()] }); export const handler = async (event) => { // Produce some example log outputs logger.debug('This is a log with detailed debug information - shown only in test environment'); logger.info('This is a log with standard information - shown in production and test environment'); }; ``` ------ ## 检索 Lambda 环境变量 检索环境变量 要检索函数代码中的环境变量，请使用编程语言的标准方法。 ------ #### [ Node.js ] ``` let region = process.env.AWS_REGION ``` ------ #### [ Python ] ``` import os region = os.environ['AWS_REGION'] ``` **注意** 在某些情况下，您可能需要使用以下格式： ``` region = os.environ.get('AWS_REGION') ``` ------ #### [ Ruby ] ``` region = ENV["AWS_REGION"] ``` ------ #### [ Java ] ``` String region = System.getenv("AWS_REGION"); ``` ------ #### [ Go ] ``` var region = os.Getenv("AWS_REGION") ``` ------ #### [ C\$1 ] ``` string region = Environment.GetEnvironmentVariable("AWS_REGION"); ``` ------ #### [ PowerShell ] ``` $region = $env:AWS_REGION ``` ------ Lambda 通过静态加密来安全地存储环境变量。您可以[配置 Lambda 以使用不同的加密密钥](configuration-envvars-encryption.md)、在客户端加密环境变量值或使用 Amazon Secrets Manager 在 Amazon CloudFormation 模板中设置环境变量。 ## 定义运行时环境变量 Lambda [运行时](lambda-runtimes.md)会在初始化过程中设置多个环境变量。大多数环境变量提供有关函数或运行时的信息。这些环境变量的键是*预留* 的，无法在函数配置中设置。 **预留环境变量** + `_HANDLER` – 函数上配置的处理程序位置。 + `_X_AMZN_TRACE_ID` – [X-Ray 跟踪标头](services-xray.md)。此环境变量会随着每次调用发生变化。 + 此环境变量不是为仅限操作系统的运行时系统（`provided` 运行时系统系列）定义的。您可以使用来自 [下一个调用](runtimes-api.md#runtimes-api-next) 的 `Lambda-Runtime-Trace-Id` 响应标头设置用于自定义运行时的 `_X_AMZN_TRACE_ID`。 + 对于 Java 运行时系统版本 17 及更高版本，不使用此环境变量。相反，Lambda 将把跟踪信息存储在 `com.amazonaws.xray.traceHeader` 系统属性中。 + `AWS_DEFAULT_REGION` – 执行 Lambda 函数的默认 Amazon Web Services 区域。 + `AWS_REGION` – 执行 Lambda 函数的 Amazon Web Services 区域。如果定义了该值，该值将会覆盖 `AWS_DEFAULT_REGION`。 + 有关在 Amazon SDK 中使用 Amazon Web Services 区域 环境变量的更多信息，请参阅《Amazon SDK 和工具参考指南》**中的 [Amazon 区域](https://docs.amazonaws.cn/sdkref/latest/guide/feature-region.html#feature-region-sdk-compat)。 + `AWS_EXECUTION_ENV` – [运行时标识符](lambda-runtimes.md)，前缀为 `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-managed-instances`。有关信息，请参阅[配置预置并发](provisioned-concurrency.md)、[使用 Lambda SnapStart 提高启动性能](snapstart.md) 或 [Lambda 托管实例](lambda-managed-instances.md)。 + `AWS_LAMBDA_LOG_GROUP_NAME`、`AWS_LAMBDA_LOG_STREAM_NAME` – Amazon CloudWatch Logs 组和函数的流名称。`AWS_LAMBDA_LOG_GROUP_NAME` 和 `AWS_LAMBDA_LOG_STREAM_NAME` [环境变量](#configuration-envvars-runtime)在 Lambda SnapStart 函数中不可用。 + `AWS_ACCESS_KEY`、`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY``AWS_SESSION_TOKEN` – 从函数的[执行角色](lambda-intro-execution-role.md)中获取的访问密钥。 + `AWS_LAMBDA_RUNTIME_API` –（[自定义运行时](runtimes-custom.md)）[运行时 API](runtimes-api.md) 的主机和端口。 + `LAMBDA_TASK_ROOT` – Lambda 函数代码的路径。 + `LAMBDA_RUNTIME_DIR` – 运行时库的路径。 + `AWS_LAMBDA_MAX_CONCURRENCY`：（仅限 Lambda 托管实例）Lambda 将向一个执行环境发送的最大并发调用次数。 + `AWS_LAMBDA_METADATA_API`–格式为 `{ipv4_address}:{port}` 的[元数据端点](configuration-metadata-endpoint.md)服务器地址（例如，`169.254.100.1:9001`）。 + `AWS_LAMBDA_METADATA_TOKEN`–当前执行环境的唯一身份验证令牌，用于对[元数据端点](configuration-metadata-endpoint.md)的请求进行身份验证。Lambda 在初始化时会自动生成此令牌。 以下附加环境变量并非预留，可以在函数配置中扩展。 **非预留环境变量** + `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](lambda-nodejs.md)) Node.js 库路径 (`/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules`)。 + `NODE_OPTIONS` – ([Node.js](lambda-nodejs.md)) 对于 Node.js 运行时，可以使用 `NODE_OPTIONS` 来重新启用 Lambda 默认禁用的实验性功能。 + `PYTHONPATH` –（[Python](lambda-python.md)）Python 库路径（`$LAMBDA_RUNTIME_DIR`）。 + `GEM_PATH` –（[Ruby](lambda-ruby.md)）Ruby 库路径 (`$LAMBDA_TASK_ROOT/vendor/bundle/ruby/3.3.0:/opt/ruby/gems/3.3.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](lambda-csharp.md)）将此变量设置为启用或禁用 .NET 特定的运行时优化。值包括 `always`、`never` 和 `provisioned-concurrency`。有关更多信息，请参阅 [为函数配置预置并发](provisioned-concurrency.md)。 + `TZ` – 环境的时区 (`:UTC`)。执行环境使用 NTP 同步系统时钟。 显示的示例值反映了最新的运行时。特定变量或其值是否存在会因早先的运行时而异。 # 保护 Lambda 环境变量 保护环境变量 为了保护环境变量，您可以使用服务器端加密来保护静态数据，使用客户端加密来保护传输中数据。 **注意** 为了提高数据库的安全性，建议您使用 Amazon Secrets Manager 而不是环境变量来存储数据库凭证。有关更多信息，请参阅 [在 Lambda 函数中使用 Secrets Manager 密钥](with-secrets-manager.md)。 **静态安全** Lambda 始终使用 Amazon KMS key 提供服务器端静态加密。默认情况下，Lambda 使用 Amazon 托管式密钥。如果此默认行为适合您的工作流，您无需设置任何其他内容。Lambda 将在账户中创建 Amazon 托管式密钥，并为您管理权限。Amazon 不会向您收取使用此密钥的费用。 如果您愿意，可以提供 Amazon KMS 客户托管式密钥。这样做可能是为了控制 KMS 密钥的轮换，或者是为了满足组织管理 KMS 密钥的要求。当您使用客户托管式密钥时，只有您账户中有权访问 KMS 密钥的用户才能查看或管理函数上的环境变量。 客户托管式密钥产生标准 Amazon KMS 费用。有关更多信息，请参阅 [Amazon Key Management Service 定价](https://www.amazonaws.cn/kms/pricing/)。 **传输过程中的安全** 为了提高安全性，您可以为传输中加密启用帮助程序，这样可以确保环境变量在客户端加密，以便在传输过程中提供保护。 **为环境变量配置加密** 1. 使用 Amazon Key Management Service（Amazon KMS）创建任意客户托管式密钥，供 Lambda 用于服务器端和客户端加密。有关更多信息，请参阅 *Amazon Key Management Service 开发人员指南*中的[创建密钥](https://docs.amazonaws.cn/kms/latest/developerguide/create-keys.html)。 1. 使用 Lambda 控制台，导航到 **Edit environment variables (编辑环境变量)** 页面。 1. 打开 Lamba 控制台的 [Functions](https://console.amazonaws.cn/lambda/home#/functions)（函数）页面。 1. 选择函数。 1. 选择 **Configuration (配置)**，然后从左侧导航栏选择 **Environment variables (环境变量)**。 1. 在 **Environment variables (环境变量)** 部分中，选择 **Edit (编辑)**。 1. 展开 **Encryption configuration (加密配置)**。 1. （可选）启用控制台加密帮助程序，以使用客户端加密来保护传输中数据。 1. 在 **Encryption in transit (传输中加密)** 下，选择 **Enable helpers for encryption in transit (为传输中加密启用帮助程序)**。 1. 对于要为其启用控制台加密帮助程序的每个环境变量，选择环境变量旁的 **Encrypt**（加密）。 1. 在要传输中加密的 Amazon KMS key 下，选择在此过程开始时创建的客户托管式密钥。 1. 选择 **Execution role policy (执行角色策略)**并复制策略。此策略授予函数执行角色解密环境变量的权限。 保存此策略以便在此过程的最后一步中使用。 1. 将代码添加到解密环境变量的函数中。选择**解密密钥代码段**来查看示例。 1. （可选）为静态加密指定您的客户托管密钥。 1. 选择 **Use a customer master key (使用客户主密钥)**。 1. 选择在此过程开始时创建的客户托管式密钥。 1. 选择 **Save**（保存）。 1. 设置权限。 如果您使用带有服务器端加密的客户托管密钥，请将权限授予您希望能查看或管理函数上的环境变量的任何用户或角色。有关更多信息，请参阅 [管理服务器端加密 KMS 密钥的权限](#managing-permissions-to-your-server-side-encryption-key)。 如果您为传输中的安全性启用客户端加密，您的函数需要调用 `kms:Decrypt` API 操作的权限。将之前在此过程中保存的策略添加到函数的[执行角色](lambda-intro-execution-role.md)。 ## 管理服务器端加密 KMS 密钥的权限 您的用户或函数的执行角色不需要 Amazon KMS 权限，即可使用默认加密密钥。要使用客户托管式密钥，您需要具有使用密钥的权限。Lambda 使用您的权限在密钥上创建授权。Lambda 可将其用于加密。 + `kms:ListAliases` – 在 Lambda 控制台中查看密钥。 + `kms:CreateGrant`、`kms:Encrypt` – 在函数上配置客户托管式密钥。 + `kms:Decrypt` – 查看和管理使用客户托管式密钥加密的环境变量。 您可以从您的 Amazon Web Services 账户 或从密钥的基于资源的权限策略获取这些权限。`ListAliases` 由 [Lambda 的托管策略](access-control-identity-based.md)提供。密钥策略将剩余权限授予**密钥用户**组中的用户。 没有 `Decrypt` 权限的用户仍然可以管理函数，但无法在 Lambda 控制台中查看或管理环境变量。要防止用户查看环境变量，请向用户的权限添加一条语句，该语句拒绝访问默认密钥、客户托管式密钥或所有密钥。 **Example IAM policy – 按密钥 ARN 拒绝访问** **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Deny", "Action": [ "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-2:111122223333:key/3be10e2d-xmpl-4be4-bc9d-0405a71945cc" } ] } ``` 有关托管密钥权限的详细信息，请参阅《Amazon Key Management Service 开发人员指南》**中的[使用 Amazon KMS 的密钥策略](https://docs.amazonaws.cn/kms/latest/developerguide/key-policies.html)。