Django JSONField无法正确存储4字节表情符号的解决方案咨询

问题背景 #

在Django 4.0.8 + MySQL 8.0.31环境下，使用JSONField存储含4字节表情符号的用户评论时，表情符号被替换为?，但用TextField配合json.dumps()/json.loads()可正常存储。数据库默认编码为utf8mb4、排序规则utf8mb4_general_ci，且JSONField受环境支持。

模型定义 #

class TestJSONField(models.Model):
    data = models.JSONField()

测试代码与结果 #

测试代码：

comment=b'smiley : \xf0\x9f\x98\x8a'.decode()
t=TestJSONField(pk=1, data={'comment':comment})
t.save()
r=TestJSONField.objects.get(pk=1)
print('BEFORE :', comment)
print('AFTER :', r.data['comment'], '(str)')
print('AFTER :', r.data['comment'].encode(), '(utf-8 encoded bytes)')

输出结果：

BEFORE : smiley : 😊
AFTER : smiley : ? (str)
AFTER : b'smiley : ?' (utf-8 encoded bytes)

解决方案 #

1. 强制数据库连接使用utf8mb4字符集 #

虽然数据库默认编码是utf8mb4，但Django的数据库连接可能未明确指定该字符集，导致JSON字段存储时4字节字符被截断替换。在settings.py的数据库配置中添加OPTIONS参数：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': '你的数据库名',
        'USER': '数据库用户名',
        'PASSWORD': '数据库密码',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
            'use_unicode': True,
        },
    }
}

这是最常见的解决方式，确保数据库连接全程使用支持4字节字符的utf8mb4编码。

2. 自定义JSON编码器（可选） #

若上述配置后仍有问题，可自定义JSON编码器，确保表情符号被正确序列化：

import json
from django.db import models

class UTF8MB4JSONEncoder(json.JSONEncoder):
    def encode(self, obj):
        encoded_str = super().encode(obj)
        return encoded_str.encode('utf-8').decode('utf-8')

class TestJSONField(models.Model):
    data = models.JSONField(encoder=UTF8MB4JSONEncoder)

3. 验证MySQL配置（辅助） #

确认MySQL的max_allowed_packet参数设置足够大（建议至少16M），避免JSON数据过大导致存储异常，可在MySQL配置文件中修改：

[mysqld]
max_allowed_packet = 16M

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