Django自定义用户模型报错：relation 'users_customuser'不存在，求排查

问题场景 #

用户创建了如下自定义用户模型：

from django.db import models
from django.contrib.auth.models import AbstractUser

class CustomUser(AbstractUser):
    email = models.EmailField(unique=True)
    USERNAME_FIELD="email"
    REQUIRED_FIELDS=["username"]
    
    def __str__(self) -> str:
        return self.email

并在settings.py中配置：

AUTH_USER_MODEL = "users.CustomUser"

执行migrate命令报错，尝试python manage.py migrate users --fake后问题仍存在，调用/api/register/接口时触发django.db.utils.ProgrammingError，提示relation "users_customuser" does not exist。

错误原因 #

核心问题是在项目完成初始迁移（如auth、admin等默认app的迁移）之后才设置AUTH_USER_MODEL，导致Django迁移系统逻辑混乱。migrate users --fake仅标记迁移已执行，并未在数据库中实际创建users_customuser表，因此接口调用时会提示表不存在。

解决方法 #

情况1：项目处于开发初期，可重置数据库 #

• 1. 删除项目根目录下的db.sqlite3文件（若使用SQLite），或清空对应数据库的所有表。
• 2. 删除所有app下migrations目录中除__init__.py外的所有迁移文件（包括users app的迁移文件）。
• 3. 重新生成users app的迁移文件：

  python manage.py makemigrations users
  

• 4. 执行全量迁移：

  python manage.py migrate
  

情况2：项目已有数据，无法重置数据库 #

需手动补建表并同步迁移状态：

• 1. 打开users app的初始迁移文件（如users/migrations/0001_initial.py），提取其中创建users_customuser表的SQL语句。
• 2. 直接在数据库中执行该CREATE TABLE语句（注意根据数据库类型调整语法，如PostgreSQL、MySQL存在细微差异）。
• 3. 标记users app的初始迁移已完成：

  python manage.py migrate users --fake-initial
  

• 4. 验证迁移状态：执行python manage.py showmigrations users，确认迁移条目后显示[X]。

注意事项 #

• 最佳实践：必须在项目创建后立即设置AUTH_USER_MODEL，再执行第一次migrate操作，避免后续迁移冲突。
• 所有引用用户模型的代码，需使用get_user_model()而非直接导入默认User类，例如：

  from django.contrib.auth import get_user_model
  
  User = get_user_model()
  

内容的提问来源于stack exchange，提问作者Gabriel Okemwa