在 Django 自定义 User 模型中，若将 username 设为 primary_key，直接赋值修改后调用 save() 会导致数据库误判为插入新记录，从而触发唯一约束冲突（如 email 重复）。根本解法是分离主键与业务字段，并采用安全的更新方式。
在 django 自定义 user 模型中，若将 `username` 设为 `primary_key`，直接赋值修改后调用 `save()` 会导致数据库误判为插入新记录，从而触发唯一约束冲突（如 email 重复）。根本解法是分离主键与业务字段，并采用安全的更新方式。
问题根源：主键不可变性
Django 的 ORM 在检测到模型实例的主键（pk）发生变更时，默认执行 INSERT 而非 UPDATE。这是因为 Django 将主键变更视为“新对象创建”，即使该实例已存在于数据库中。在您的代码中：
userobj = User.objects.get(username="username1") userobj.username = "new_username" # ⚠️ username 同时是 primary_key userobj.save() # → 触发 INSERT，导致 email UNIQUE 冲突
由于 username 被设为 primary_key=True，Django 认为修改 username 即等同于更换主键，进而尝试插入一条新记录——而原 email 值已被占用，故抛出 IntegrityError。
正确实践一：使用独立主键（推荐）
应始终为自定义 User 模型显式定义一个与业务无关的、不可变的主键（如 AutoField 或 UUIDField），让 username 回归其语义本质：一个带唯一约束的普通字段。
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager
from django.db import models
class UserManager(BaseUserManager):
def create_user(self, username, email, password=None, **extra_fields):
if not email:
raise ValueError('Email is required')
email = self.normalize_email(email)
user = self.model(username=username, email=email, **extra_fields)
user.set_password(password)
user.save(using=self._db)
return user
class User(AbstractBaseUser):
# ✅ 独立主键：稳定、自增、无业务含义
id = models.AutoField(primary_key=True)
# ✅ username 是业务字段，仅需 unique=True
username = models.CharField(max_length=30, unique=True)
# ✅ email 保持唯一约束（符合认证逻辑）
email = models.EmailField(max_length=255, unique=True)
full_name = models.CharField(max_length=65, null=True, blank=True)
# 必须字段（Django auth 要求）
is_active = models.BooleanField(default=True)
is_staff = models.BooleanField(default=False)
objects = UserManager()
USERNAME_FIELD = 'username'
REQUIRED_FIELDS = ['email']
def __str__(self):
return self.username✅ 迁移提示：若已有生产数据，需通过 makemigrations --empty 编写迁移脚本，添加 id 字段并设为 primary_key，同时移除 username 的 primary_key=True —— 注意备份数据并测试回滚路径。
正确实践二：安全更新 username（无需 reload 实例）
即使主键已分离，仍不建议通过 instance.username = ...; instance.save() 更新 username，因为：
- 可能引发竞态条件（如并发修改）；
- 绕过模型层校验（如 clean() 方法）；
- 未利用数据库原子性保障。
推荐使用 QuerySet.update() —— 它直接生成 SQL UPDATE 语句，在数据库层面原子执行，高效且安全：
# ✅ 推荐：原子性更新，不触发 model save() 流程
updated = User.objects.filter(username="old_username").update(username="new_username")
if updated == 0:
raise ValueError("No user found with username 'old_username'")⚠️ 注意：update() 不会调用 save()、clean() 或发送 pre_save/post_save 信号，因此需确保业务逻辑不依赖这些钩子。若需完整生命周期控制，请改用：
# ✅ 替代方案：显式 reload + save（适合需校验/信号场景） user = User.objects.get(username="old_username") user.username = "new_username" user.full_clean() # 触发模型验证 user.save() # 触发信号与自定义逻辑
总结与最佳实践清单
- ✅ 永远为自定义 User 模型分配独立主键（如 models.AutoField(primary_key=True)），禁用 username 或 email 的 primary_key=True；
- ✅ 修改 username 优先使用 QuerySet.update()，兼顾性能与安全性；
- ✅ 若需模型验证或信号支持，务必先 get() 再 full_clean() + save()；
- ❌ 避免在 save() 前修改主键字段，这是 Django ORM 的底层行为限制，非 Bug；
- ? 数据库迁移时，对主键变更务必谨慎操作，建议在开发环境充分验证完整性约束与关联外键。
遵循以上原则，即可彻底规避因主键设计不当导致的更新异常，构建健壮、可维护的 Django 用户系统。
