Django-常用插件

发表于 更新于 分类于 本文字数： 8.1k 阅读时长 ≈ 15 分钟

这篇讲什么

  • 老笔记这份清单是 2020 年抄的，里面一半的包到今天要么停更要么装不上。这一版按当前基线 Django 5.2.19 + Python 3.14.10 重装重测：能装的给出确切版本与配置，装不上的给出实测报错。
  • 另外单独标注了 Requires-Dist 里对 Django 版本有上限的包——这类包会在安装时静默把 Django 换成旧版。

怎么读这篇

  • 老笔记这份清单是 2020 年抄的，里面一半的包（Xadmin、djcelery、uwsgi、django-haystack 的老配置）到今天要么停更要么装不上。这一版按当前基线 Django 5.2.19 + Python 3.14.10 重装重测，能装的给出确切版本与配置，装不上的给出实测报错。
  • 复测也会把旧结论推翻：Simple UI（django-simpleui）原本记成「源码包缺 README.md 装不上」，2026-11-05 重装发现上游早改好了，现在能用，所以它不在「装不上」那张表里，只在下面的「后台皮肤」小节留了个链接。
  • 版本口径（本机 pip 实测）：一律以官方推荐为准，能装的全是当时可安装的最新版本；Requires-Dist 里对 Django 有上限的包单独标注，避免升级时踩静默降级（这条见记忆里的「pip 会静默降级核心库」）。

本机实测可用的包一览

包 版本 干什么用 关键配置
djangorestframework 3.18.3 REST API INSTALLED_APPS += ["rest_framework"]
django-filter 26.2 DRF/admin 的字段过滤 DEFAULT_FILTER_BACKENDS 里挂 DjangoFilterBackend
drf-spectacular 0.30.0 OpenAPI 3.0.3 文档 DEFAULT_SCHEMA_CLASS + SPECTACULAR_SETTINGS
django-debug-toolbar 8.0.0 请求级 SQL/模板面板 元数据要求 django>=5.2
whitenoise 6.12.0 让应用自己发静态文件 中间件放 SecurityMiddleware 之后
django-cors-headers 4.9.0 跨域 CORS_ALLOWED_ORIGINS
django-unfold 0.110.1 后台皮肤 配置项与实测见《Django-站点管理》的「后台主题：五种方案」
django-simpleui 2026.1.13 后台皮肤（Element UI 风格） 见下面「后台皮肤」小节，装法与配置在《Django-站点管理》
django-simple-captcha 0.7.0 验证码 见《Django-验证码》
django-tinymce 5.0.0 富文本 见《Django-富文本》
django-ratelimit 4.1.0 视图限流 模块名是 django_ratelimit
celery 5.6.3 异步任务 见《Django-Celery》
django-celery-beat 2.9.0 定时任务表 元数据 Django<6.1,>=2.2，6.x 上会拖降级
django-celery-results 2.6.0 结果入库 要求 Django>=3.2.25，无上限
redis 8.1.0 Redis 客户端（缓存/会话/broker） Django 4.0+ 内置 Redis 缓存后端
Pillow 13.0.0 ImageField 必需 无
mysqlclient 2.3.0 官方推荐的 MySQL 驱动 见《Django-基本入门》
psycopg[binary] 3.3.8 官方推荐的 PG 驱动 同上
sentry-sdk 2.73.0 错误监控 sentry_sdk.init(dsn=..., integrations=[DjangoIntegration()])
gunicorn 26.2.0 WSGI 服务器（Linux 上线） gunicorn proj.wsgi -w 4
uvicorn 0.54.0 ASGI 服务器 uvicorn proj.asgi:application

上面每一行的版本号都是 importlib.metadata.version(...) 现读的，24 个包 import 全部成功、pip check 输出 No broken requirements found.（明细见索引篇《Django 环境搭建与版本迁移》）。

django-debug-toolbar：调试面板

settings.py
1
2
3
4
5
6
7
8
9
INSTALLED_APPS = [..., "debug_toolbar"]

MIDDLEWARE = [
    "debug_toolbar.middleware.DebugToolbarMiddleware",   # 放在最前面一组之后即可
    ...,
]

INTERNAL_IPS = ["127.0.0.1"]
DEBUG_TOOLBAR_CONFIG = {"SHOW_TOOLBAR_CALLBACK": lambda request: True}
  • 面板只在 DEBUG=True 且来源 IP 命中 INTERNAL_IPS 时出现；本机实测用测试客户端从 127.0.0.1 访问 /admin/ 能拿到带 djDebug 的页面，换成 10.0.0.9 就没有。
  • 生产环境绝不要开：它会暴露 SQL、模板、请求头。真要在预发上看，就用 SHOW_TOOLBAR_CALLBACK 判内网 + 登录态，别写死 lambda request: True。
  • 它只影响 HTML 页面；接口调试建议直接看 drf-spectacular 的文档页。

drf-spectacular：OpenAPI 文档

settings.py
1
2
3
4
5
6
7
8
9
10
INSTALLED_APPS = [..., "drf_spectacular"]

REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

SPECTACULAR_SETTINGS = {
    "TITLE": "笔记 REST API",
    "VERSION": "1.0.0",
}
proj/urls.py
1
2
3
4
5
6
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
    path("api/docs/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"),
]

  • 实测：

    1
    2
    3
    4
    /api/schema/: 200 | Content-Type=application/vnd.oai.openapi; charset=utf-8
    openapi: 3.0.3
    Swagger UI: 200 | 含 swagger: True
    drf_spectacular.urls 可导入: False | No module named 'drf_spectacular.urls'
    • include("drf_spectacular.urls") 是错的写法（很多老教程这么写），它没有 urls 模块，要用 SpectacularAPIView / SpectacularSwaggerView 两个视图。

  • 命令行生成 schema 文件（实测）：

    1
    python manage.py spectacular --file schema.yml
    1
    2
    3
    Schema generation summary:
    Warnings: 4 (4 unique)
    Errors:   78 (6 unique)

    • 6 类错误全是同一个原因——APIView / @api_view 没声明 serializer_class，实测原文：

      1
      2
      3
      4
      school/views.py: Error [students_list]: unable to guess serializer. This is graceful
      fallback handling for APIViews. Consider using GenericAPIView as view base class, if view
      is under your control. Either way you may want to add a serializer_class (or method).
      Ignoring view for now.
      • 解决办法：给视图加 serializer_class，或用 @extend_schema(responses=...) 显式声明；generics / ViewSet 因为能自动推断，不会报这条。

    • 4 条 warning 是 operationId 冲突（格式后缀路由重名），实测原文：

      1
      2
      3
      Warning: operationId "fbv_students_formatted_retrieve" has collisions
      [('/api/fbv/students{format}', 'get'), ('/api/fbv/students/{id}{format}', 'get')].
      resolving with numeral suffixes.

      这是 format_suffix_patterns 的副产品；不想要就把 append_format_suffix 关掉：SPECTACULAR_SETTINGS = {"SCHEMA_COERCE_PATH_PK_SUFFIX": ...} 或干脆 DEFAULT_FORMAT_SUFFIX_PARAMETER 相关配置里排除。

WhiteNoise：不用 Nginx 也能发静态文件

settings.py
1
2
3
4
5
6
7
8
9
10
11
12
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",     # 紧跟 SecurityMiddleware
    ...,
]

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
STORAGES = {
    "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"},
}
  • 每次部署前跑 python manage.py collectstatic；ManifestStaticFilesStorage 会给文件名加 hash，模板里必须用 {% static %}，写死路径会 404。
  • 大流量站点仍然建议 Nginx 直接发 /static/，WhiteNoise 只当兜底（详见《Django-应用水平扩展》）。

django-cors-headers：跨域

settings.py
1
2
3
4
5
6
7
8
9
INSTALLED_APPS = [..., "corsheaders"]

MIDDLEWARE = [
    "corsheaders.middleware.CorsMiddleware",   # 要尽量靠前，且在 CommonMiddleware 之前
    ...,
]

CORS_ALLOWED_ORIGINS = ["https://front.example.com"]
CORS_ALLOW_CREDENTIALS = True                  # 带 cookie 时才需要
  • 别写 CORS_ALLOW_ALL_ORIGINS = True 又同时 CORS_ALLOW_CREDENTIALS = True，等于允许任意站点带着用户凭据打你的接口。
  • 前后端分离的登录态问题优先看 DRF 的 Token 认证（见《Django-RESTful-Api之认证和权限》），比放开 cookie 跨域干净。

django-ratelimit：视图限流

views.py
1
2
3
4
5
6
from django_ratelimit.decorators import ratelimit


@ratelimit(key="ip", rate="10/m", block=True)
def login_view(request):
    ...
  • 实测踩过的坑：包名是 django-ratelimit，模块名是 django_ratelimit；老笔记写的 from ratelimit.decorators import ... 命中的是另一个早已死掉的同名包。
  • block=True 直接返回 403；不 block 就自己判 request.limited。

后台皮肤

  • 后台皮肤的安装、配置项和实测全部写在《Django-站点管理》的「后台主题：五种方案」一节，这份清单只留索引和一句话简介：
    • django-unfold 0.110.1：Tailwind 风格，侧边导航、明暗切换、TABS 都有，配置项最多（31 个顶层键），本仓默认推荐；元数据要求 django>=5.2。
    • django-jazzmin 3.0.5：Bootstrap 那一套，26 个现成 Bootswatch 主题 + 现场 UI builder，改配色最省事。
    • django-simpleui 2026.1.13：Vue + Element UI 的「后台管理台」风格，首页卡片、图标、菜单折叠现成；只覆写模板，admin.site 仍是 Django 自己的 DefaultAdminSite。
    • django-admin-interface 0.32.0：不换模板，把配色存成后台里的一行 Theme 记录，不改代码的人也能调。
    • 官方自带：Django 4.1 起后台靠 CSS 变量上色，不装任何包就能换配色，页面也最轻。
  • 一句话选型：怕折腾用官方 CSS 变量，要现代 UI 上 unfold，本来就吃 Bootstrap 上 jazzmin，老项目想换层 Vue 皮用 simpleui，配色要能被运营同事改就 admin-interface。

装不上/别装的包（实测）

包 实测结果 替代方案
xadmin PyPI 上还留着 0.6.1，但本机（中文 Windows，默认 GBK）构建时 UnicodeDecodeError: 'gbk' codec can't decode byte 0xa4；用 PYTHONUTF8=1 绕过装上后 import xadmin 又炸 NameError: name 'reload' is not defined（Python 2 写法） 官方 admin 或 django-unfold
djcelery from versions: none（包已下架） django-celery-beat + django-celery-results
uwsgi Windows 上 setup.py 用 os.uname，直接 AttributeError: module 'os' has no attribute 'uname' Linux 上线用 gunicorn / uvicorn
django-redis-cache 后端 redis_cache.cache.RedisCache 导入即 ModuleNotFoundError: No module named 'redis_cache' Django 4.0+ 内置 redis.RedisCache
django-redis-sessions 第三方死包，SESSION_ENGINE = 'redis_sessions.session' 这套早不动了 SESSION_ENGINE='...backends.cache' + Redis 缓存配置
django-haystack（老配置） 文档里的 whoosh 路线还在，但配置项与 5.x 的模板上下文有出入 新项目直接上 django-pg-search / Meilisearch / OpenSearch

新手卡点清单

  • 都是实测踩过的：

    卡点 症状（实测原文） 正确做法
    include("drf_spectacular.urls") ModuleNotFoundError: No module named 'drf_spectacular.urls' 用 SpectacularAPIView / SpectacularSwaggerView
    没配 DEFAULT_SCHEMA_CLASS schema 生成时大量 unable to guess serializer 配上 drf_spectacular.openapi.AutoSchema
    APIView 不写 serializer_class Error [...]: unable to guess serializer 写 serializer_class 或 @extend_schema
    生产开着 debug toolbar SQL/模板/请求头全暴露 只在 DEBUG=True + INTERNAL_IPS 下开
    WhiteNoise 排错位置 静态文件仍 404 或安全头异常 放在 SecurityMiddleware 之后、其余之前
    ManifestStaticFilesStorage 但模板写死路径 收集后 hash 名对不上，404 一律 {% static %}，部署前 collectstatic
    from ratelimit.decorators import ... 装的是死包，导入失败 from django_ratelimit.decorators import ratelimit
    照 2020 年的清单装 xadmin / djcelery / uwsgi 上面那张表里的报错 按「替代方案」列换官方或在维护的包
    照旧笔记说「Simple UI 装不上」 2026-11-05 复测 django-simpleui 2026.1.13 能装、check rc=0、后台 200 想用就看「后台皮肤」小节；「装不上」这类结论要定期复测

参考