AutoMapper 配置错误会导致运行时静默失败或崩溃，根本原因是未正确获取 IMapper 实例、映射顺序颠倒、嵌套/集合映射未显式配置、Profile 未被扫描或空值处理不当。
AutoMapper 不是“配完就能跑”的工具，配置错一次，运行时就静默失败或直接崩——尤其在嵌套、集合、空值场景下。
为什么 Map 调用抛 NullReferenceException？
新版 AutoMapper（v10+）已移除静态 Mapper 类，Mapper.Map<T>() 会直接报空引用。根本原因是你没拿到有效的 IMapper 实例。
- ❌ 错误写法：
var mapper = new Mapper(new MapperConfiguration(...))—— 每次都重建配置，开销极大 - ✅ 正确做法：在
Program.cs中注册单例：services.AddAutoMapper(typeof(YourProfile)) - ⚠️ 若
YourProfile在独立类库（如Core.dll），必须显式传入程序集：services.AddAutoMapper(typeof(YourProfile).Assembly) - ? 启动时加一句
mapperConfig.AssertConfigurationIsValid()，能提前暴露未覆盖的类型组合
CreateMap 泛型顺序写反了，但不报错？
CreateMap<Source, Destination>() 定义的是「从 Source 映射到 Destination」。顺序写反（比如写成 CreateMap<UserDto, UserEntity>() 却想用它把 Entity 转成 Dto）不会编译报错，但运行时字段全为空或映射逻辑彻底颠倒。
- 检查你调用
_mapper.Map<UserEntity>(dto)时，是否真有CreateMap<UserDto, UserEntity>()配置 - 确认 Profile 是否被扫描到：只传
typeof(Program)，而 Profile 在另一个程序集 → 配置完全失效 - 避免隐式转换干扰：如果
UserDto和UserEntity之间有implicit operator，AutoMapper 可能跳过字段映射，直接调用它，导致部分字段静默丢失
嵌套对象映射失败，但同名字段能映射？
AutoMapper 默认只做浅拷贝。哪怕 UserDto.Profile.Address.Street 和 UserEntity.Profile.Address.Street 字段名、类型都一致，也不会自动递归映射——它连 Profile 这一级都不会进。
- 必须单独配
CreateMap<AddressDto, AddressEntity>() - 再在
CreateMap<UserDto, UserEntity>()中指定路径：.ForMember(x => x.Address, opt => opt.MapFrom(y => y.Profile.Address)) - 若只是扁平化（如把
UserDto.Profile.Name映射到UserEntity.ProfileName），可用IncludeMembers(x => x.Profile)简化 - ⚠️
ForMember的 lambda 必须防 null：opt.MapFrom(src => src.User?.Id)，而不是src.User.Id（否则src.User为 null 时直接崩）
集合映射返回空列表或报 AutoMapperMappingException？
AutoMapper 不会自动推导集合规则。它只基于你已声明的 CreateMap<UserEntity, UserDto>() 来展开泛型。
- ✅ 正确顺序：先配单类型映射
CreateMap<UserEntity, UserDto>()，再调_mapper.Map<List<UserDto>>(users) - ❌ 错误假设：“我配了单个类型，集合就该自动支持” → 没配单类型映射，集合映射会静默返回空列表或抛异常
- 注意
IEnumerable<T>和List<T>行为不同；若目标是IReadOnlyCollection<T>，需确认泛型约束是否兼容 - EF 查询中别用
Map，改用ProjectTo<UserDto>(context.Users)，避免先把全部实体加载进内存
最常被忽略的点：Profile 构造函数外写的 CreateMap 全部无效；AssertConfigurationIsValid() 不是可选项，是上线前必跑的校验；空值安全不是靠 ?? 补救，而是从 MapFrom 的 lambda 路径开始兜底。
