ASP.NET Core 环境配置

在 ASP.NET Core 中，环境（Environment） 是框架内置的核心概念，用于让应用根据运行场景（开发、测试、生产等）自动切换配置、行为和错误处理策略。

以下是关于 ASP.NET Core 环境设置的完整介绍：

1. 三种默认环境

ASP.NET Core 预定义了三个标准环境名称：

环境名	常量	典型用途
Development	`Environments.Development`	本地开发调试，显示详细错误页，启用热重载
Staging	`Environments.Staging`	上线前验证，模拟生产环境但可使用测试数据
Production	`Environments.Production`	正式线上环境，隐藏错误详情，启用缓存/压缩

⚠️ 环境名大小写不敏感 ，但建议统一使用首字母大写形式。你也可以自定义环境名（如 QA、UAT），框架同样支持。

2. 如何设置环境

按优先级从高到低排列：

① 命令行参数（最高优先级）

bash 复制代码

dotnet run --environment Production
# 或发布后
./MyApp --environment Staging

② 环境变量

bash 复制代码

# Linux / macOS
export ASPNETCORE_ENVIRONMENT=Production

# Windows CMD
set ASPNETCORE_ENVIRONMENT=Production

# Windows PowerShell
$env:ASPNETCORE_ENVIRONMENT = "Production"

💡 这是生产部署最推荐的方式（Docker、K8s、IIS 均通过环境变量注入）。

③ launchSettings.json（仅开发时生效）

json 复制代码

// Properties/launchSettings.json
{
  "profiles": {
    "MyApp": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

⚠️ 此文件不会被发布 ，仅在 dotnet run / Visual Studio 调试时有效。

④ 代码中硬编码（不推荐）

csharp 复制代码

builder.Environment.EnvironmentName = "CustomEnv"; // 极少使用

3. 在代码中使用环境

Program.cs 中判断

csharp 复制代码

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// ✅ 方式1：直接判断
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();  // 详细错误页
}
else
{
    app.UseExceptionHandler("/Error"); // 通用错误页
    app.UseHsts();
}

// ✅ 方式2：判断是否为生产
if (app.Environment.IsProduction())
{
    app.UseResponseCompression();
}

// ✅ 方式3：判断自定义环境
if (app.Environment.IsEnvironment("QA"))
{
    // QA 专属逻辑
}

// ✅ 方式4：枚举式判断
if (app.Environment.IsDevelopment() || app.Environment.IsStaging())
{
    app.UseSwagger();
}

在 Controller / Service 中注入

csharp 复制代码

public class HomeController : Controller
{
    private readonly IWebHostEnvironment _env;

    public HomeController(IWebHostEnvironment env)
    {
        _env = env;
    }

    public IActionResult Index()
    {
        ViewBag.Env = _env.EnvironmentName;       // "Development"
        ViewBag.ContentRoot = _env.ContentRootPath; // 项目根目录
        ViewBag.WebRoot = _env.WebRootPath;         // wwwroot 路径
        return View();
    }
}

在 Razor 视图中

html 复制代码

<environment include="Development">
    <link rel="stylesheet" href="~/css/site.css" />
    <script src="~/js/site.js"></script>
</environment>

<environment exclude="Development">
    <link rel="stylesheet" href="~/css/site.min.css" asp-append-version="true" />
    <script src="~/js/site.min.js" asp-append-version="true"></script>
</environment>

4. 环境专属配置文件

ASP.NET Core 会自动按顺序加载以下配置文件（后面的覆盖前面的）：

复制代码

appsettings.json              ← 所有环境共享
appsettings.{Environment}.json ← 当前环境专属（覆盖上面的值）

示例：

复制代码

appsettings.json                → 通用配置
appsettings.Development.json    → 开发环境覆盖
appsettings.Production.json     → 生产环境覆盖
appsettings.Staging.json        → 预发布环境覆盖

json 复制代码

// appsettings.json
{
  "ConnectionStrings": {
    "Default": "Server=prod-db;Database=MyDb;"
  },
  "Logging": {
    "LogLevel": { "Default": "Warning" }
  }
}

json 复制代码

// appsettings.Development.json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=MyDb_Dev;"  // ← 覆盖连接字符串
  },
  "Logging": {
    "LogLevel": { "Default": "Debug" }               // ← 覆盖日志级别
  }
}

💡 还可以通过 User Secrets（开发）和 Azure Key Vault / 环境变量（生产）进一步隔离敏感配置。

5. 各环境的典型差异对照

功能	Development	Staging	Production
异常页面	`UseDeveloperExceptionPage()`	自定义错误页	`UseExceptionHandler()` + HSTS
Swagger/OpenAPI	✅ 启用	✅ 可选	❌ 禁用
静态资源	未压缩原始文件	压缩文件	压缩 + CDN + 版本号
日志级别	Debug / Trace	Information	Warning / Error
数据库	本地 / SQLite	测试库	生产库（只读副本等）
缓存	MemoryCache / 禁用	Redis	Redis + 响应缓存
CORS	宽松（localhost）	限定测试域名	严格限定生产域名
HTTPS	可选	强制	强制 + HSTS

6. ⚠️ 常见陷阱与最佳实践

问题	说明
不要在生产环境用 `IsDevelopment()` 做安全判断	环境名可被篡改，安全策略应基于配置而非环境名
`launchSettings.json` 不会发布	部署时必须通过环境变量或命令行设置环境
自定义环境名要全链路一致	配置文件名、代码判断、CI/CD 变量必须完全匹配
不要在代码中硬编码环境名	用 `IsDevelopment()` 等方法或常量，避免拼写错误
敏感信息不要放在 appsettings 中	生产环境用 User Secrets / Key Vault / 环境变量
`WebApplication.CreateBuilder(args)` 已自动读取环境	不需要手动调用 `SetEnvironment()`，除非有特殊需求

📌 总结

ASP.NET Core 的环境机制是一个 "约定优于配置" 的设计：

设置一个环境变量 ASPNETCORE_ENVIRONMENT

框架自动加载对应配置文件、切换中间件管道、调整日志级别

你在代码中只需 IsDevelopment() / IsProduction() 即可分支处理

掌握这套机制，就能做到一套代码、多套配置、零改动部署。