Mapster可直接替代AutoMapper且迁移成本低，只需安装Mapster与Mapster.DependencyInjection、调用AddMapster()注册，统一使用IMapper.Map<T>()而非Adapt<T>()，注意IQueryable映射、Source Generator启用及调试技巧。
Mapster 能直接替代 AutoMapper，且无需重写大部分调用逻辑——Adapt<T>() 和 IMapper 接口基本兼容，迁移成本极低。关键不是“能不能换”，而是“换完要不要改调用方式”和“哪些地方容易崩”。下面直奔实操。
安装与基础注册：别漏掉 Mapster.DependencyInjection
只装 Mapster 包是不够的。如果你用 ASP.NET Core 的 DI 容器（绝大多数项目都用），必须额外安装 Mapster.DependencyInjection，否则 IMapper 注入会失败，报错 InvalidOperationException: No service for type 'IMapper' has been registered。
正确步骤：
- 运行
dotnet add package Mapster - 运行
dotnet add package Mapster.DependencyInjection - 在
Program.cs中调用builder.Services.AddMapster();（无参数即可启用默认行为） - 控制器或服务中通过构造函数注入
IMapper，不用手动 new 或静态访问
不推荐用静态 TypeAdapterConfig.GlobalSettings 全局配置——它在多租户或并行配置场景下可能被覆盖，DI 方式更安全、可测试。
Adapt<T>() 与 IMapper.Map<T>() 的行为差异
两者功能一致，但底层机制不同：Adapt<T>() 是扩展方法，走的是静态映射缓存；IMapper.Map<T>() 走 DI 容器解析的实例，支持生命周期管理（如 Scoped 配置）。实际项目中建议统一用后者，避免混用导致配置不生效。
常见陷阱：
- 对
IQueryable<T>使用Adapt<T>()会触发 ToList() 强制执行，丢失延迟执行优势；必须用mapper.ProjectTo<T>()（需引用Mapster.EFCore） -
Adapt<T>()不识别TypeAdapterConfig的局部配置（比如config.ForType<A,B>()），除非显式传入 config 实例 - 泛型类型映射（如
List<User>→List<UserDto>）默认支持，但若 DTO 里有DateTime?映射到string，必须提前配转换器，否则抛NotSupportedException
性能关键：什么时候该开 Source Generator？
Mapster 默认运行时编译表达式树，快但仍有 JIT 开销。如果你的映射逻辑稳定、不常变动（比如 DTO ↔ Entity 层），强烈建议启用 Mapster.Tool + Source Generator 模式——它在编译期生成纯 C# 映射代码，性能提升约 2–3 倍，且完全规避运行时反射异常。
启用条件：
- 安装
Mapster.Tool包（注意：.NET 6+ 才支持 Source Generator） - 在项目文件中添加
<EnableDefaultCompileItems>false</EnableDefaultCompileItems>并显式包含生成文件 - 定义一个实现
IRegister的配置类，放在会被扫描的程序集（如主 Web 项目） - 生成的代码在
obj/Mapster/下，不可手动修改
副作用：编译变慢几秒，且每次改映射规则都要重新生成；调试时堆栈指向生成代码而非源配置，需习惯。
调试映射失败：看 MapsterConfig 日志和 GetExpression
映射出错时，Mapster 默认只抛 MappingException，错误信息模糊（例如 “Unable to map…”）。要定位具体哪一属性挂了，得打开调试日志：
在注册时加一句：
builder.Services.AddMapster(config =>
{
config.Default.Settings.AllowImplicitDestinationInheritance = true;
config.Default.NameMatchingStrategy = NameMatchingStrategy.Flexible;
});然后用 TypeAdapterConfig.GlobalSettings.GetExpression<Src, Dst>() 获取生成的 lambda 表达式，贴进 LINQPad 或调试器里单步——这是最准的排查手段。别依赖 IDE 插件或文档里的“自动匹配”说法，字段名大小写、空格、下划线差异都会让默认匹配静默失败。
最后提醒一句：Mapster 对 record 类支持良好，但若目标类型含 init-only 属性且源无对应 setter，必须显式配 .Map(dest => dest.Prop, src => src.Prop)，否则映射为空。
