首选URL路径版本（如/api/v1/users），因其直观、易调试、兼容缓存与代理；请求头版本易受CORS、CDN、Swagger及前端限制，常见406错误和fetch失败。WebAPI 版本控制该用 URL 路径还是请求头URL 路径版本（如 /api/v1/users）是绝大多数团队的首选，不是因为它最"优雅"，而是它最直观、最易调试、最兼容缓存和代理。请求头（如 Accept: application/vnd.myapi.v1+json）看似规范，但实际会卡在 CORS、CDN 缓存、Swagger 文档生成、前端 Axios 默认行为等多个环节。常见错误现象：406 Not Acceptable 频繁出现，Postman 测试正常但前端 fetch 失败，Swagger UI 根本不显示 v2 接口。路径版本：直接路由匹配，MapControllers() 自动识别 Route("api/v{version:apiVersion}/\[controller")]请求头版本：需手动注册 Microsoft.AspNetCore.Mvc.Versioning 并配置 ApiVersionReader，且 Swagger 必须额外集成 Swashbuckle.AspNetCore.Filters混合使用（如路径 + 查询参数）会导致路由歧义，ASP.NET Core 6+ 会静默忽略部分版本声明如何在 C# 中启用 API 版本并声明多个版本核心是两步：注册服务 + 声明控制器版本。不注册服务的话，ApiVersion("1.0") 注解完全无效，运行时不会报错，但所有版本都 fallback 到默认（通常是 1.0），这是最常被忽略的坑。实操建议：在 Program.cs 中调用 services.AddApiVersioning(...)，至少要配 options.DefaultApiVersion = new ApiVersion(1, 0) 和 options.AssumeDefaultVersionWhenUnspecified = true控制器上必须同时标注 ApiVersion("1.0") 和 ApiVersion("2.0") 才能支持多版本共存；单个控制器不能只写一个版本还指望自动降级不同版本的同名控制器可共存，但需用命名空间或类名区分，例如 UsersControllerV1 和 UsersControllerV2，否则编译报错 Type 'UsersController' already defines a member called 'Get'...为什么 MapToApiVersion 有时不生效MapToApiVersion 的作用是把某个 Action 显式绑定到特定版本，但它只在控制器已声明对应版本的前提下才起效。如果控制器只标了 ApiVersion("1.0")，却给某个方法加 MapToApiVersion("2.0")，这个方法在 v2 下根本不可达------不是 404，而是路由系统压根不注册它。 RedClaw 百度推出的手机端万能AI Agent助手