环境变量与配置注入
更新: 2026-10-16 15:20:09 字数: 0 字 时长: 0 分钟
当您在 AppHost 中用 WithReference 连接资源时，Aspire 会自动向消费方注入环境变量，这个过程称为配置注入。
理解这些命名约定，对以下场景尤为重要：
- 用非 .NET 语言（Node.js、Python、Go…）编写的服务需要直接读取环境变量。
- 排查「为什么连接字符串是空的」这类问题。
命名约定
Aspire 会根据被引用资源的类型生成不同格式的环境变量。
连接字符串
当引用的资源提供连接字符串（数据库、缓存、消息等）时，Aspire 会以资源名（或显式的 connectionName）作为逻辑连接名，原始的变量使用 ConnectionStrings__ 前缀：
ConnectionStrings__{资源名}var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis("my-cache");
var db = builder.AddPostgres("postgres").AddDatabase("my-db");
var api = builder.AddProject<Projects.Api>("api")
.WithReference(cache)
.WithReference(db);
builder.Build().Run();对 api 资源而言，会得到：
| 原始环境变量 | 可移植环境变量 | 说明 |
|---|---|---|
ConnectionStrings__my-cache | ConnectionStrings__my_cache | Redis 缓存的连接字符串。 |
ConnectionStrings__my-db | ConnectionStrings__my_db | PostgreSQL 数据库连接串。 |
可移植连接名编码
部分部署目标（Azure App Service、Kubernetes 系列发布器、Foundry Hosted Agents）不允许环境变量名中出现连字符，因此 Aspire 会额外生成一个可移植别名：
编码规则：
- 保留大小写。
- 把 ASCII 字母、数字、下划线之外的字符替换为
_。 - 若以数字开头，在前面补一个
_。 - 把连续下划线折叠为单个下划线。
| 逻辑连接名 | 可移植环境变量 |
|---|---|
mydb | ConnectionStrings__mydb |
my-db | ConnectionStrings__my_db |
my--db | ConnectionStrings__my_db |
my__db | ConnectionStrings__my_db |
MyDb | ConnectionStrings__MyDb |
1db | ConnectionStrings___1db |
别名冲突会直接报错
别名冲突检查不区分大小写。如果两个引用映射到同一个物理名（例如逻辑名 my-db 与 my_db），Aspire 会在环境解析阶段报错，而不是静默覆盖。此时请为其中一个引用指定不同的 connectionName。
服务端点
服务端点使用 services__ 前缀，格式为：
services__{服务名}__{端点名}__{索引}| 环境变量 | 含义 |
|---|---|
services__basket__https__0 | basket 的 https 端点。 |
services__basket__dashboard__0 | basket 的 dashboard 端点。 |
详见服务发现。
参数
通过 AddParameter 创建、再经 WithEnvironment 传入的参数，使用您显式指定的变量名：
var insertionRows = builder.AddParameter("insertionRows");
builder.AddProject<Projects.Api>("api")
.WithEnvironment("InsertionRows", insertionRows);此时应用读取的是 InsertionRows，而不是 Parameters__insertionRows。
参数本身的值可以从配置读取，也可以在部署时由环境变量提供：
Parameters__registry_endpoint
Parameters__registry_repository双下划线是 .NET 配置约定
配置路径中的冒号（:）在环境变量中写为双下划线（__）。因此 Parameters:registry-endpoint 对应环境变量 Parameters__registry_endpoint。
在应用中读取
.NET
// 连接字符串
var conn = builder.Configuration.GetConnectionString("my-db");
// 普通配置
int rows = builder.Configuration.GetValue<int>("InsertionRows", 1);连字符不会自动翻译
IConfiguration.GetConnectionString 不会自动把连字符翻译成下划线。对于 my-cache 这样的逻辑名：
- 优先按逻辑名读取：
GetConnectionString("my-cache")。 - 若为
null，再回退到可移植键：GetConnectionString("my_cache")。
static string? GetPortableConnectionString(IConfiguration config, string logicalName)
{
return config.GetConnectionString(logicalName)
?? config.GetConnectionString(logicalName.Replace('-', '_'));
}其他语言
// Node.js
const conn = process.env.ConnectionStrings__my_cache# Python
import os
conn = os.getenv("ConnectionStrings__my_cache")自定义物理变量名
集成可以通过 IResourceWithConnectionString.ConnectionStringEnvironmentVariable 覆盖物理变量名。此时 Aspire 只发出这一个确切名称，不做任何规范化，connectionName 也不会重命名它。
迁移建议
- 更新 AppHost 包时同步更新客户端集成包：新版客户端会先按逻辑名查找，找不到再回退到可移植键。
- 如果需要保留旧版客户端集成，请把引用的
connectionName设为可移植名（如my_db），并在应用的客户端注册或配置查询中使用同一名称。只改引用不改消费方是不够的。 - 自定义发布器/集成请检查环境变量字典中的
ConnectionStringReference值，而不是资源注解——EnvironmentVariableNames属性才是权威来源。
