本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Lambda 環境變數
您可以使用環境變數來調整函數的行為，而無需更新程式碼。環境變數是存放在函數特定版本組態中的一對字串。Lambda 執行時間可讓程式碼使用環境變數，並設定其他環境變數，這些變數包含函數和調用請求的相關資訊。
**注意**
為了提高安全性，我們建議您使用 AWS Secrets Manager 而非環境變數來存放資料庫登入資料和其他敏感資訊，例如 API 金鑰或授權字符。如需詳細資訊，請參閱[在 Lambda 函式中使用 Secrets Manager 秘密](with-secrets-manager.md)。
在函數調用之前，不會評估環境變數。您定義的任何值都會視為文字字串，而且不會展開。在函數程式碼中執行變數評估。
## 建立 Lambda 環境變數
您可以使用 Lambda 主控台、 AWS Command Line Interface (AWS CLI)、 AWS Serverless Application Model (AWS SAM) 或使用 AWS SDK 在 Lambda 中設定環境變數。
------
#### [ Console ]
您可以在函數的未發佈版本上定義環境變數。發布版本時，該版本的環境變數與其他[版本特定組態設定](configuration-versions.md)會被鎖定。
您可以透過定義索引鍵和值，為函數建立環境變數。函數使用索引鍵的名稱來擷取環境變數的值。
**在 Lambda 主控台中設定環境變數**
1. 開啟 Lambda 主控台中的 [函數頁面](https://console.aws.amazon.com/lambda/home#/functions)。
1. 選擇一個函數。
1. 選擇**組態**索引標籤，然後選擇**環境變數**。
1. 在 **Environment variables** (環境變數) 下，選擇 **Edit** (編輯)。
1. 選擇 **Add environment variable** (新增環境變數)。
1. 輸入索引鍵和值。
**請求**
+ 索引鍵需以英文字母為開頭，且至少有兩個字元。
+ 索引鍵僅包含字母、數字和底線字元 (`_`)。
+ 索引鍵不是[由 Lambda 預留](#configuration-envvars-runtime)。
+ 所有環境變數的大小總計不超過 4 KB。
1. 選擇**儲存**。
**在主控台程式碼編輯器中產生環境變數清單**
可在 Lambda 程式碼編輯器中產生環境變數清單。這是在編碼時參考環境變數的快速方法。
1. 選擇 **程式碼** 標籤。
1. 向下捲動至程式碼編輯器的 **ENVIRONMENT VARIABLES** 區段。下面列出了現有環境變數：
1. 若要建立新的環境變數，請選擇加號 ()：
在主控台程式碼編輯器中列出環境變數時，會保持加密狀態。如果在傳輸過程中啟用加密輔助工具進行加密，則這些設定會維持不變。如需詳細資訊，請參閱[保護 Lambda 環境變數](configuration-envvars-encryption.md)。
環境變數清單為唯讀狀態，且只能在 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": "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}}
```
------
#### [ AWS SAM ]
可以使用 [AWS Serverless Application Model](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/serverless-getting-started.html ) 來設定函數的環境變數。更新 `template.yaml` 檔案中的[環境](https://docs.aws.amazon.com//serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-environment)和[變數](https://docs.aws.amazon.com//AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-environment.html#cfn-lambda-function-environment-variables)屬性，然後執行 [sam 部署](https://docs.aws.amazon.com//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...
```
------
#### [ AWS SDKs ]
若要使用 AWS SDK 管理環境變數，請使用下列 API 操作。
+ [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html)
+ [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html)
+ [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html)
若要進一步了解，請參閱您偏好的程式設計語言的 [AWS SDK 文件](https://aws.amazon.com/developer/tools/)。
------
## 環境變數的範例案例
您可以使用環境變數，自訂測試環境和生產環境中的函數行為。例如，您可以建立兩個具備相同程式碼，但不同組態的函數。一個函數連接到測試資料庫，另一個函數連接到生產資料庫。在此情況下，可以使用環境變數將資料庫的主機名稱和其他連線詳細資訊傳遞給函數。
以下範例顯示如何將資料庫主機和資料庫名稱定義為環境變數。
如果您希望測試環境產生比實際執行環境更多的偵錯資訊，您可以設定環境變數，以將測試環境設定為使用更詳細的記錄或更詳細的追蹤。
例如，在測試環境中，您可以使用 `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\# ]
```
string region = Environment.GetEnvironmentVariable("AWS_REGION");
```
------
#### [ PowerShell ]
```
$region = $env:AWS_REGION
```
------
Lambda 透過靜態加密環境變數來安全地存放它們。您可以[設定 Lambda 使用不同的加密金鑰](configuration-envvars-encryption.md)、在用戶端加密環境變數值，或在具有 的 CloudFormation 範本中設定環境變數 AWS Secrets Manager。
## 定義執行時間環境變數
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 函數的預設 AWS 區域 位置。
+ `AWS_REGION` – 執行 Lambda 函數 AWS 區域 的 。若已完成定義，此值便會覆寫 `AWS_DEFAULT_REGION`。
+ 如需搭配 AWS SDKs 使用 AWS 區域 環境變數的詳細資訊，請參閱 *AWS SDKs和工具參考指南*中的[AWS 區域](https://docs.aws.amazon.com/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`、`snap-start`、 `provisioned-concurrency`或 `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` – 格式的[中繼資料端點](configuration-metadata-endpoint.md)伺服器地址 `{ipv4_address}:{port}`（例如 `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 來同步系統時鐘。
顯示的範例值會反映最新的執行時間。特定變數或其值是否存在，可能會因先前的執行時間而有所不同。