AutoMapper 应配置一次全局复用，MapperConfiguration 和 IMapper 均推荐单例注入；常见错误包括配置未加载、嵌套映射未声明、只读属性被静默跳过。
AutoMapper 配置一次就复用，别在每次映射时 new Mapper
反复创建 Mapper 实例是性能杀手，尤其在 Web 请求中。AutoMapper 的设计前提就是「配置一次、全局复用」，MapperConfiguration 是线程安全的，但 IMapper 实例也推荐作为单例注入，而不是每次 new。
- ❌ 错误写法：
var mapper = new Mapper(new MapperConfiguration(cfg => cfg.CreateMap<a b>()));</a>—— 每次都重建配置，开销极大 - ✅ 正确做法：在
Program.cs（.NET 6+）或Startup.ConfigureServices中注册为单例：services.AddAutoMapper(typeof(YourProfile)); - 配置类（如
YourProfile）应继承Profile，并在构造里写CreateMap<source dest>()</source>，避免散落在各处 - 注意：
MapperConfiguration构建耗时，若配置逻辑里有反射扫描或动态类型生成，首次启动会明显变慢
Map 时出现“Missing type map configuration”错误
这是最常搜到的报错，根本原因是：配置没生效，或者类型对不上。不是代码写错了，而是 AutoMapper 根本没看到你的 CreateMap 声明。
- 检查 Profile 是否被正确加载：传入
AddAutoMapper(...)的程序集必须包含已定义的Profile子类；如果 Profile 在独立类库，要显式传入该程序集，比如AddAutoMapper(typeof(MyProfile).Assembly) - 确认泛型参数顺序：
CreateMap<userdto userentity>()</userdto>表示「从 Dto 映射到 Entity」，反着写不会报错但逻辑颠倒 - 注意隐式转换干扰：如果两个类型有自定义隐式操作符，AutoMapper 可能跳过映射直接调用它，导致字段没赋值却无报错
- .NET 6+ 使用源生成器（
AutoMapper.SourceGenerator）可彻底规避运行时反射和此错误，但需手动启用并生成Mapper.g.cs
复杂嵌套对象映射失败，但简单属性正常
AutoMapper 默认只做浅拷贝，嵌套对象（如 User.Profile.Address）不会自动递归映射，除非你明确告诉它怎么走。
- 默认行为：若
AddressDto和AddressEntity有同名属性，且已配过CreateMap<addressdto addressentity>()</addressdto>，则CreateMap<userdto userentity>().ForMember(x => x.Address, opt => opt.MapFrom(y => y.Profile.Address))</userdto>才能连通 - 别依赖「自动展开」：即使
Profile.Address是 public 属性，AutoMapper 也不会自己钻进去找AddressDto对应关系 - 使用
IncludeMembers可简化扁平化场景：CreateMap<userdto userentity>().IncludeMembers(x => x.Profile)</userdto>，前提是Profile类型本身也有对应映射规则 - 循环引用（如 A→B→A）默认抛异常，需显式配置
cfg.AllowNullCollections = true或用PreserveReferences()
DTO 转 Entity 时忽略只读属性或私有 set
实体常带私有 setter 或计算属性，而 DTO 是纯数据载体。AutoMapper 默认不写入只读成员，但可以改。
- 对私有 set：确保目标属性有
set（哪怕 private），AutoMapper 默认能访问；若用init（C# 9+），需启用cfg.ShouldUseInternalAccessModifier = true - 忽略只读字段（
readonly或get-only）：它压根不碰，也不报错——这是静默失败点，建议单元测试覆盖关键字段 - 用
ForMember强制指定值：ForMember(x => x.Id, opt => opt.Ignore())或opt.UseValue(0)，比靠约定更可靠 - 注意 EF Core 场景：若映射后直接
context.Users.Update(entity)，未映射的导航属性可能被清空，得用Entry(entity).Property(x => x.Name).IsModified = true精确控制
真正卡住人的往往不是语法，而是配置没加载、嵌套没声明、只读属性被跳过却没察觉。AutoMapper 的「约定优于配置」在简单场景很省事，但一到多层映射或混合领域模型，就得把每条链路都亲手串起来——漏一个 CreateMap，就少一层信任。
