必须使用.NET 6+，因MapGet等Minimal API特性仅在该版本及以上存在；需确认SDK安装、项目目标框架唯一且正确（如net8.0）、清理编译缓存，并严格遵循初始化顺序：builder创建→服务注册→app构建→中间件与路由注册（UseHttpsRedirection须在MapGet前）→Run。
必须用 .NET 6+，低于这个版本连 MapGet 都找不到——不是写法错，是根本没那个类型。
确认项目目标框架是否合规
新建项目时看似成功，但运行时报“找不到 MapGet”或“IEndpointRouteBuilder 未定义”，大概率是目标框架不匹配。Visual Studio 默认可能选中“.NET 5 Web API”模板，即使手动改了 .csproj 里的 <TargetFramework>net6.0</TargetFramework>，缓存也可能导致编译仍走旧路径。
- 执行
dotnet --list-sdks确认本地已安装6.0.x或更高版本 SDK - 检查
.csproj文件，确保只含一个<TargetFramework>（如net8.0），不要写成net6.0;net8.0多目标（绑定行为可能不一致） - 改完后务必运行
dotnet clean && dotnet build，清掉obj/和bin/下的残留
路由注册顺序不能错
app.MapGet 写在 app.Run() 后面，服务能启动，但所有接口一律 404；写在 builder.Build() 前，则直接编译失败，报“app 未声明”。Minimal API 对初始化链极其敏感，五步缺一不可且顺序固定：
var builder = WebApplication.CreateBuilder(args);- 服务注册（如
builder.Services.AddDbContext<AppDbContext>()） var app = builder.Build();- 中间件和路由注册（
app.UseHttpsRedirection()、app.MapGet(...)等） app.Run();
特别注意：app.UseHttpsRedirection() 必须放在 app.MapGet 之前，否则对 API 路由不生效。
参数绑定不靠特性，靠名字和类型
Minimal API 不识别 [FromQuery]、[FromBody] 这类特性。它根据参数名是否匹配路由段、类型是否为简单类型，自动决定数据来源：
-
app.MapGet("/user/{id}", (int id) => ...)→id是路径参数，名字必须完全一致（大小写敏感） -
app.MapGet("/search", (string q, int page = 1) => ...)→q来自查询字符串?q=abc，page有默认值则可省略 -
app.MapPost("/order", (Order req) => ...)→ 自动尝试 JSON 反序列化，请求头必须含Content-Type: application/json - 发
application/x-www-form-urlencoded却期望绑定到Order？直接返回 400，Minimal API 默认不解析表单
返回值必须用 Results.*() 或实现 IResult
不能直接 return new { ok = true }，否则要么编译失败，要么响应体为空。所有 HTTP 状态码和格式都要显式表达：
-
Results.Ok(new { Id = 123 })→ 200 + JSON -
Results.Created($"/api/users/{id}", user)→ 201 + Location header + body -
Results.BadRequest("Missing name")→ 400 + 纯文本 - 想返回 XML 或自定义二进制流？得自己实现
IResult，Results.*()工厂方法只覆盖常用场景
最易忽略的是：Minimal API 没有 ModelState 自动聚合机制，验证失败需手动检查并调用 Results.ValidationProblem()，否则 400 错误不会带详细字段信息。
