使用 Azure 开发者 CLI 环境变量

Azure 开发人员 CLI （azd） 使用环境变量来存储和管理部署环境的配置设置。 这些变量控制如何在 Azure 中预配、部署和运行应用程序。 本文介绍环境变量在 azd 环境中的工作原理，并提供有效管理它们的指南。

了解环境变量

在 Azure 开发人员 CLI 的上下文中，环境变量是绑定到特定命名环境（如 开发、 测试或 prod）的键值对。每个 azd 环境都维护自己的一组环境变量，使你可以为不同的部署目标配置不同的设置。

环境变量 azd 存储在位于 .azure 文件夹中的 .env 文件中。 它们作为输入：

• 应用程序部署工作流
• Azure 服务和连接的配置
• 通过 Bicep 和 Terraform 进行基础结构预配

与传统在作系统级别存在的环境变量不同， azd 环境变量的范围限定为项目中的特定环境，从而在不同的部署目标之间提供隔离。

环境变量在使用azd时提供了几个关键优势：

• 环境隔离：使开发、测试和生产配置保持独立且不同。
• 配置一致性：确保所有团队成员对特定环境使用相同的设置。
• 基础结构即代码：通过变量而不是硬编码值定义基础结构参数化。
• 部署自动化：允许 CI/CD 管道使用相同的代码库但不同的配置部署到不同的环境。
• 简化的管理：从中心位置轻松更新环境中所有服务的设置。

每个 azd 环境都有自己的变量集，允许在使用相同的应用程序代码和基础结构模板时使用特定于环境的配置。

环境变量和 .env 文件

azd环境变量存储在项目中特定于环境的目录中的.env文件中。 使用 azd env new <name> 创建环境时，将创建目录结构：

.azure/
├── <environment-name>/
│   ├── .env                   # Environment variables for this environment

该文件 .env 使用标准格式，其中每行表示键值对：

KEY1=value1
KEY2=value2

当您运行命令如 azd up 时，azd 会自动从所选环境的 .env 文件中加载变量。

这些变量会影响：

• 基础设施配置：变量，例如 AZURE_LOCATION 和 AZURE_SUBSCRIPTION_ID，决定资源的创建位置和方式。
• 部署：服务终结点等变量控制应用程序如何连接到 Azure 服务。
• 应用程序配置：变量可以传递给应用程序配置来控制其行为。
• 资源命名：变量（如 AZURE_RESOURCE_GROUP 影响资源命名模式）。

文件 .env 还会在执行azd操作，如azd init、azd provision以及azd deploy时自动更新，捕获基础设施模板的输出，并将其存储以备将来使用。

设置环境变量。

可以使用不同的方法来设置 azd 环境变量，具体取决于方案。

使用 CLI 命令

设置环境变量的建议方法是使用 azd env set 命令，其中包括检查以确保有效值：

azd env set <key> <value>

例如，若要为应用程序设置配置值，请执行以下作：

azd env set API_TIMEOUT 5000

该命令在当前所选环境的文件中添加或更新变量 .env 。 还可以使用 --environment 标志以特定环境为目标：

azd env set API_TIMEOUT 5000 --environment prod

若要验证是否已正确设置环境变量，请执行以下作：

azd env get-value API_TIMEOUT

Bicep 的输出

其强大的功能 azd 是能够将 Bicep 基础结构模板中的输出参数自动捕获为环境变量。 例如，在文件中定义输出参数 main.bicep 时：

output API_ENDPOINT string = apiService.outputs.SERVICE_ENDPOINT_URL

运行 azd provision后，此输出会自动保存到环境 .env 的文件：

API_ENDPOINT=https://api-dev-123456.azurewebsites.net

此方法可确保应用程序始终有权访问最新的资源信息，例如：

• 服务终结点和 URL
• 资源名称和标识符

获取和使用环境变量

设置后，可以在多个上下文中访问环境变量。

CLI 命令

若要查看当前环境的所有环境变量，请执行以下作：

azd env get-values

查看特定变量的值：

azd env get-value API_ENDPOINT

对于计算机可读输出（在脚本中很有用）：

azd env get-values --output json

在基础结构文件中使用环境变量

可以使用环境变量自定义基础结构模板。 这对于基于当前环境命名、标记或配置资源非常有用。 azd 还使用标记在 Azure 中查找资源以执行部署和其他任务。

请考虑以下常见流：

1. 在此期间 azd init， azd 根据用户对提示的响应设置这些环境变量：

   AZURE_ENV_NAME=myapp-dev
   AZURE_LOCATION=eastus2
   

2. 在infra文件夹中引用这些变量main.parameters.json。 azd 在预配过程中替换值，并将解析的参数传递给 Bicep：

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "name": {
         "value": "${AZURE_ENV_NAME}"
       },
       "location": {
         "value": "${AZURE_LOCATION}"
       }
     }
   }
   

3. 在 Bicep 模板中定义匹配参数：

   @description('Name of the environment used to derive resource names and tags.')
   param name string
   
   @minLength(1)
   @description('Primary Azure region for all resources.')
   param location string
   

   azd 提供带有已替换值的 Bicep 参数，并在 main.parameters.json 中使用它们。

4. 使用资源命名的参数和标记，以便稍后确定资源所属的环境：

   var resourceToken = toLower(uniqueString(resourceGroup().id, name, location))
   
   resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
     name: 'st${resourceToken}'
     location: location
     sku: {
       name: 'Standard_LRS'
     }
     kind: 'StorageV2'
     tags: {
       Environment: name
       Project: 'myproject'
     }
   }
   

此模式使模板保持灵活，在不更改代码的情况下启用按环境自定义，并改进资源治理（命名、标记和发现）。

挂钩

azd环境变量会自动预加载，并在文件中定义的azure.yaml和自定义脚本中可用，可以使用以下语法访问环境变量：

# Use the variables in your script
echo "API endpoint: $API_ENDPOINT"
echo "Deploying to: $AZURE_LOCATION"

# Use the variables in your script
Write-Host "API endpoint: $API_ENDPOINT"
Write-Host "Deploying to: $AZURE_LOCATION"

可以在azure.yaml文件中定义挂钩，以在azd生命周期的特定点运行这些脚本：

hooks:
  postprovision:
    windows:
      shell: pwsh
      run: ./scripts/load-env-vars.ps1
      interactive: false
    posix:
      shell: sh
      run: ./scripts/load-env-vars.sh
      interactive: false

删除或更新变量

若要从环境中删除变量，请执行以下作：

azd env unset VARIABLE_NAME

若要更新现有变量，请执行以下作：

azd env set VARIABLE_NAME "new-value"

若要从 Azure 资源的当前状态刷新本地环境变量，请执行以下作：

azd env refresh

刷新环境在以下情况下非常有用：

• 你希望确保本地 .env 文件反映基础结构的最新输出（如连接字符串、终结点等）。
• 在团队成员更新环境后，需要同步环境变量。

AZD 与 OS 环境变量

azd 环境变量和作系统环境变量有不同的用途，以不同的方式工作：

azd 不会自动读取或写入 OS 环境变量。 但是，可以使用自定义脚本与这两种类型的变量进行交互。

读取 azd 环境变量和 OS 环境变量：

# Access OS environment variable
echo "OS variable: $PATH"

# Access azd environment variable
echo "AZD variable: $(azd env get-value MY_VARIABLE)"

# Access OS environment variable
Write-Host "OS variable: $env:PATH"

# Access azd environment variable
Write-Host "AZD variable: $(azd env get-value MY_VARIABLE)"

将环境变量写入 azd OS 或框架环境变量：

# Load all azd environment variables into the current shell session
while IFS='=' read -r key value; do
    value=$(echo "$value" | sed 's/^"//' | sed 's/"$//')
    export "$key=$value"
done <<EOF
$(azd env get-values)
EOF

# Load all azd environment variables into the current PowerShell session
foreach ($line in (& azd env get-values)) {
    if ($line -match "([^=]+)=(.*)") {
        $key = $matches[1]
        $value = $matches[2] -replace '^"|"$'
        $env:$key = $value
    }
}

标准环境变量

azd 设置和使用所有环境中的多个常见环境变量：

机密和敏感数据注意事项

虽然环境变量便于配置，但它们需要对敏感数据进行特殊处理：

避免在 .env 文件中存储机密

.env 文件通常以纯文本形式存储，并且可以轻松：

• 意外提交到版本控制系统
• 在没有适当的保护的情况下共享或复制
• 任何有权访问项目文件的人都可以查看
• 包含在日志或错误报告中

处理机密的替代方法

对于敏感数据，请考虑以下更安全的方法：

• Azure Key Vault 参考：将机密存储在 Azure Key Vault 中，然后在 .env 文件中引用它们。

  azd env set-secret <secret-value>
  

  此命令创建一个 Key Vault 机密，并将对它的引用存储在你的.env文件中，而不是存储实际的值。

• 托管标识：将 Azure 服务配置为使用托管标识，而不是连接字符串或访问密钥。

• 特定于环境的安全性：对生产环境应用比开发环境更严格的安全控制。

• 实时机密：在部署期间生成生存期较短的凭据，而不是存储持久性机密。

后续步骤