django-ckeditor配置S3存储后上传图片仍保存到本地的问题

AI 小北

2026-8-29

问题根源

配置变量命名不符合规范：django-ckeditor 不会识别你自定义的S3_*开头的配置项，它默认跟随Django全局文件存储配置走，你没有替换默认的本地文件存储后端，上传文件自然会落到本地CKEDITOR_UPLOAD_PATH指定的文件夹。
前端表单缺少必要属性：你的form标签没加enctype="multipart/form-data"，就算存储配置正确，文件内容也无法被后端正常接收解析。
常见遗漏点：如果没在路由里注册ckeditor_uploader的上传接口，上传功能本身也会异常，是初次集成的高频踩坑点。

修复步骤

第一步：安装必要依赖
django-ckeditor的S3存储适配依赖django-storages和boto3，先执行安装：
pip install django-storages boto3
第二步：修正settings.py配置
首先把storages加入INSTALLED_APPS列表：

INSTALLED_APPS = [
    # 原有其他应用，比如django.contrib.auth、你的业务app
    'storages',
    'ckeditor',
    'ckeditor_uploader',
]

删掉你之前写的自定义S3_*开头的配置项，替换为Django生态通用的S3存储配置：

# S3存储标准配置（必须以AWS_开头，django-storages才会识别）
AWS_ACCESS_KEY_ID = '你的S3访问密钥ID'
AWS_SECRET_ACCESS_KEY = '你的S3访问密钥'
AWS_STORAGE_BUCKET_NAME = '你的存储桶名称'
AWS_S3_REGION_NAME = '存储桶所在地域'
# 如果使用非AWS官方的S3兼容存储（比如七牛、阿里云OSS的S3模式、MinIO等），才需要配置下面的端点地址
# AWS_S3_ENDPOINT_URL = '你的S3服务访问地址'
AWS_QUERYSTRING_AUTH = False
AWS_DEFAULT_ACL = 'public-read'

# 两种存储配置二选一：
# 方案1：全站所有上传文件都走S3（包括头像、普通附件、CKEditor图片）
DEFAULT_FILE_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'
# 方案2：仅CKEditor上传的文件走S3，其他文件仍存本地
# CKEDITOR_STORAGE_BACKEND = 'storages.backends.s3boto3.S3Boto3Storage'

# 保留你原有正确的CKEditor配置即可
CKEDITOR_CONFIGS = {
    "default": {
        'toolbar': 'full',
        'width': 'auto'
    }
}
CKEDITOR_IMAGE_BACKEND = "pillow"
CKEDITOR_UPLOAD_PATH = "uploads/"
CKEDITOR_RESTRICT_BY_USER = True
CKEDITOR_ALLOW_NONIMAGE_FILES = False

第三步：修复前端表单
给form标签添加enctype="multipart/form-data"属性，这是表单上传文件的必填属性：

<form method="POST" enctype="multipart/form-data">
    {{ form.media }}
    {{ form|crispy }}
    {% csrf_token %}
    <button type="submit" class="btn btn-primary my-3">Add</button>
</form>

第四步：注册上传路由
在项目根路由文件urls.py中添加ckeditor_uploader的路由，否则上传接口会返回404：

from django.urls import path, include

urlpatterns = [
    # 你原有的其他路由配置
    path('ckeditor/', include('ckeditor_uploader.urls')),
]

配置完成后重启Django服务、清空浏览器缓存后再测试上传即可。之前已经上传到本地的文件不会自动迁移到S3，需要手动搬运。

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