从Django2.1升级到3后Admin后台File字段显示loading无法使用

云原生阿岚

2026-10-5

问题根因

Django 3.0对Admin后台的前端依赖、接口校验逻辑做了不兼容调整，你遇到的File字段持续loading的问题属于升级后的常见前端兼容性故障，可按照以下步骤逐一排查解决：

重新收集静态资源
版本升级后旧版Django的Admin静态资源会残留，和新版逻辑冲突。执行以下命令清理并重新收集静态资源：
```
python manage.py collectstatic --clear
```
这是升级后Admin前端异常的首要排查项，80%以上的同类问题都可以通过这个操作解决。
排查自定义Admin模板或第三方Admin插件兼容性
Django 3.0升级了内置jQuery版本，同时调整了Admin全局JS的API接口。如果你自定义了Admin基础模板、引入了额外JS资源，或是使用了django-suit这类第三方Admin皮肤插件，且插件还未适配Django 3.0，就会导致File字段的渲染脚本运行报错。
可临时注释自定义模板的额外JS引入、禁用第三方Admin插件后重试，确认问题来源后再做对应适配。
调整CSRF配置
Django 3.0开始默认将CSRF_COOKIE_SAMESITE设置为Lax，如果你的Admin后台是通过子域名、跨域路径访问，会导致File字段关联的异步请求CSRF校验失败。可先在settings.py中添加以下配置做测试：
```
CSRF_COOKIE_SAMESITE = None
CSRF_COOKIE_SECURE = True # 仅HTTPS部署场景需要添加
```
测试确认是CSRF配置问题后，再根据你的实际部署场景调整跨域规则，不要直接在生产环境长期使用上述测试配置。
适配自定义File Widget
如果你为FileField自定义了Widget，检查该Widget关联的渲染逻辑、JS代码是否使用了Django 2.1中已废弃的Admin JS API，按照Django 3.0的Admin Widget规范做对应适配即可。