Django自定义用户模型迁移时出现fields.E304反向访问器冲突错误排查

报错核心原因 #

• 该报错本质是未通过Django标准配置替换默认内置用户模型，导致系统同时加载两套带权限关联字段的用户模型：默认auth.User和自定义UserBase都继承PermissionsMixin，自动生成的groups、user_permissions外键的反向访问器命名完全一致，触发字段冲突校验。
• 教程讲师环境可正常运行的前提是：在首次执行任何数据库迁移前，就完成了自定义用户模型的全局配置；你的环境是先执行过默认用户模型的初始化迁移、才定义的自定义用户模型，默认auth.User仍处于激活状态，因此触发冲突。
• 报错提示中“添加related_name参数”的方案属于临时绕开校验的权宜之计，不符合自定义用户模型的官方实现逻辑，长期使用会导致权限体系错乱。

标准修复步骤 #

• 第一步：全局配置自定义用户模型

  打开项目下的settings.py，在文件末尾添加配置（需替换为你实际的应用名、模型名）：

  AUTH_USER_MODEL = 'users.UserBase'
  

• 第二步：清空旧迁移痕迹
  1. 删除开发环境下的本地数据库文件（通常是项目根目录的db.sqlite3，如果使用其他数据库需清空对应业务表）
  2. 删除所有应用下migrations文件夹中，除__init__.py之外的所有.py迁移文件
• 第三步：修正代码中的语法与逻辑错误，避免后续触发其他报错
  • CustomAccountManager.create_user方法的两处拼写错误：
    原代码self.normalze_email(email) 修改为 self.normalize_email(email)
    原代码self.mode(email=email, ...) 修改为 self.model(email=email, ...)
  • 模型类的两处类变量配置错误：
    原代码REQUIRED_FIELD = ['email'] 修改为 REQUIRED_FIELDS = ['email']（Django要求该变量名为复数形式）
    原代码USERNAME_FIELD = ['last_name'] 修改为 USERNAME_FIELD = 'last_name'（Django要求该变量赋值为单个字段的字符串，不能为列表）
• 第四步：重新执行迁移流程
  先运行校验命令确认配置生效：

  python manage.py check
  

  校验通过后再执行迁移：

  python manage.py makemigrations
  python manage.py migrate
  

内容的提问来源于stack exchange，提问作者C-Bizz