在嵌套目录（如 api/v1/users）中定义自定义用户模型时，AUTH_USER_MODEL 必须使用 Django 应用注册名（即 INSTALLED_APPS 中的标签名）加模型名的格式，而非文件路径；常见错误是误用模块路径。
在嵌套目录（如 `api/v1/users`）中定义自定义用户模型时，`auth_user_model` 必须使用 django 应用注册名（即 `installed_apps` 中的标签名）加模型名的格式，而非文件路径；常见错误是误用模块路径。
Django 的 AUTH_USER_MODEL 设置不依赖 Python 模块路径，而是基于 Django 应用的“应用标签”（app label） 和模型类名组成的字符串，格式为 "app_label.ModelName"。该 app_label 必须与 INSTALLED_APPS 中注册的应用标识完全一致——且默认就是应用包的最后一级目录名，而非完整模块路径。
在你的项目结构中：
/api
/api
/v1
/users ← 这个目录是一个 Django app
__init__.py
models.py
你已在 INSTALLED_APPS 中注册了 "api.v1.users"，但 Django 在解析应用标签时，会自动提取其最后一级名称 users 作为 app_label（前提是 users/apps.py 中未显式重写 AppConfig.label）。因此，无论该 app 物理路径多深，只要它被正确注册，其标准 app_label 就是 users。
✅ 正确配置应为：
# settings.py AUTH_USER_MODEL = "users.User"
⚠️ 注意事项：
必须在首次迁移前设置：AUTH_USER_MODEL 一旦项目已有 auth_user 相关迁移（如 0001_initial.py），再修改将导致不可逆错误。若已迁移，请先清空数据库并删除所有迁移文件（除 __init__.py 外），再执行 python manage.py makemigrations users 和 python manage.py migrate。
-
确保 users app 含有正确的 apps.py 和 __init__.py：推荐显式定义 apps.py 以增强可维护性：
# api/v1/users/apps.py from django.apps import AppConfig class UsersConfig(AppConfig): default_auto_field = "django.db.models.BigAutoField" name = "api.v1.users" # 完整模块路径 label = "users" # 显式指定 app_label（可选，但推荐）并在 api/v1/users/__init__.py 中声明：
default_app_config = "api.v1.users.apps.UsersConfig"
（注：Django 4.0+ 已弃用 default_app_config，推荐直接在 INSTALLED_APPS 中使用类路径："api.v1.users.apps.UsersConfig"）
模型需继承 AbstractUser 或 AbstractBaseUser：你当前的 class User(AbstractUser): pass 是合法起点，但建议至少添加 USERNAME_FIELD = "email"（若改用邮箱登录）或明确 REQUIRED_FIELDS。
✅ 验证是否生效： 运行 python manage.py showmigrations，确认 users 下有 0001_initial 迁移；再执行 python manage.py migrate，观察是否创建 users_user 表而非默认 auth_user。
总结：AUTH_USER_MODEL 的左半部分永远是 app_label（由 AppConfig.label 决定，默认为包名），不是导入路径；保持 INSTALLED_APPS 注册清晰、app_label 明确、迁移时机正确，即可顺利启用自定义用户模型。
