1. 这个报错到底在说什么从模块导入链路拆起先把结论摆在前面No module named kombu.transport.django这个报错本质上不是 Django 的问题也不是你代码写错了而是kombu 这个库在某个版本之后把 Django 传输后端整个移除了而你或者你依赖的某个包的配置里还写着用 Django 的 ORM 当消息队列的存储后端。Python 在 import 阶段找不到对应模块直接抛ModuleNotFoundErrorDjango 项目启动或执行migrate、runserver、celery worker时就会当场挂掉。我见过太多人第一反应是是不是 Django 版本不兼容然后开始降级 Django、重装 kombu、清 pip 缓存折腾一下午还是报同样的错。实际上这条报错信息已经把答案写得很清楚了——它说的是kombu.transport.django这个子模块路径不存在而不是kombu不存在。这两者的区别很关键前者说明 kombu 装上了但里面没有这个传输实现后者才是没装包。搞清楚这一点排查方向立刻收窄。这个报错通常出现在三类场景里。第一类是老的 Django 项目迁移到新环境settings.py里还留着BROKER_URL django://这种配置第二类是某个第三方包常见于老版本的任务队列封装库在内部硬编码了django://作为默认 broker第三类是你照着几年前的教程抄配置教程里的 kombu 还是 3.x 时代的东西。这三种情况的修复思路不完全一样后面会分别讲。适合谁看这篇手上有个跑不起来的 Django 项目、看到这条报错不知道从哪下手的人以及想搞清楚 Celery、kombu、broker 三者关系、避免以后再踩同类坑的人。不需要你对消息队列有多深的理解但至少要能看懂settings.py和requirements.txt。2. kombu 与 Django 传输后端的前世今生2.1 为什么曾经存在django://这个 broker要理解这个报错得先知道django://是干嘛的。kombu 是 Celery 底层的消息抽象层它负责把发消息、收消息这件事统一成一套接口底下可以接 RabbitMQ、Redis、Amazon SQS 等各种 broker。在很早的版本里kombu 提供了一个djangotransport用 Django 的数据库表来存消息——相当于把消息队列塞进关系型数据库里通过 ORM 读写。这个设计在当年是有现实意义的小项目不想额外部署 RabbitMQ 或 Redis手上只有一个数据库那就用数据库当队列省事。配置就一行BROKER_URL django://kombu 会自动建几张表存消息。对于日活很低、任务量很小的内部系统这套方案确实能跑。但它的缺陷也很明显。消息队列的核心诉求是高吞吐、低延迟、支持多消费者竞争消费而关系型数据库在这些方面天生不擅长。每条消息的入队出队都是一次数据库事务任务一多数据库直接被打爆多个 worker 抢消息时的锁竞争、消息确认机制、可见性超时这些语义用 ORM 模拟出来既复杂又低效。所以这个 transport 从一开始就是个能用但不推荐的过渡方案。2.2 移除的时间线与影响面kombu 在 4.0 版本大约 2016 年前后正式把djangotransport 从主包里剥离出去后续版本彻底不再维护。也就是说只要你装的 kombu 是 4.x 及以上现在 pip 默认装的基本都是 5.xkombu.transport.django这个路径就必然不存在。这不是 bug是官方主动砍掉的功能。这里有个容易混淆的点报错可能不是在你直接 import kombu 时出现的而是在 Celery 初始化、或者某个库调用kombu.utils.importlib.symbol_by_name(kombu.transport.django)时触发的。所以你在自己代码里全局搜kombu.transport.django可能一无所获但报错照样出现——因为它是被配置字符串django://间接引出来的。kombu 在解析 broker URL 的 scheme 时会按约定去 importkombu.transport.schemedjango://就对应kombu.transport.django找不到就抛错。我整理了一张对照表把版本和这个 transport 的状态理清楚方便你判断自己处在什么情况kombu 版本区间django://transport 状态典型表现3.x 及更早内置可直接用配置django://正常启动4.x已从主包移除报No module named kombu.transport.django5.x当前主流彻底不维护同上且无官方替代任意版本 独立 transport 包需手动安装第三方包视包质量而定不推荐2.3 为什么降级 kombu 不是好主意看到报错后很多人的第一反应是那我装回 kombu 3.x 不就行了。技术上确实能让报错消失但我强烈不建议。原因有三一是 kombu 3.x 依赖的 Python 版本很老在 Python 3.8 上装都装不干净更别说 3.10、3.11二是它会把你整个 Celery 生态拖回几年前安全补丁、bug 修复全都没有三是你为了一个本就该淘汰的 transport把整个依赖树锁死后续任何库升级都会打架。正确的思路是把 broker 从django://换成真正为消息队列设计的后端而不是把 kombu 降级去迁就一个废弃配置。下面几节就讲怎么换、换成什么、换的过程中要注意什么。3. 定位问题源头三步锁定是谁在引用django://在动手改之前先确认这个django://到底是从哪冒出来的。盲目全局替换配置字符串很可能改错地方或者漏改。我一般按下面三步走基本能一次定位。3.1 第一步搜配置文件里的 broker 字符串最直接的一步在项目根目录全局搜django://grep -rn django:// . --include*.py --include*.env --include*.ini --include*.cfg --include*.yaml --include*.yml重点看settings.py、celery.py、.env、docker-compose.yml这几类文件。常见写法有BROKER_URL django://、CELERY_BROKER_URL django://、环境变量BROKER_URLdjango://。如果搜到了恭喜问题源头明确直接进第 4 节改配置。如果搜不到说明这个字符串不是明文写死的可能是拼接出来的或者来自第三方库的默认值。继续往下走。3.2 第二步看完整 traceback 的调用栈报错时的完整堆栈信息是金矿别只看最后一行。往上翻找到第一个属于你自己项目代码的栈帧那里就是触发点。典型的有两种栈顶出现在celery/app/__init__.py或kombu/connection.py说明是 Celery 初始化时解析 broker URL 触发的源头在 Celery 配置。栈顶出现在某个第三方包的__init__.py或defaults.py说明是这个包内部硬编码了django://。把那个第三方包的名字记下来去它的源码里搜django://或者查它的文档看有没有配置项能覆盖默认 broker。很多老包会提供类似MYLIB_BROKER_URL的设置覆盖掉就行不用改包本身。3.3 第三步确认 kombu 实际版本与安装状态有时候报错还夹杂着装了两个版本的 kombu这种脏环境问题。跑一下python -c import kombu; print(kombu.__version__); print(kombu.__file__) pip show kombu如果kombu.__file__指向的路径和你pip show显示的 location 对不上说明环境里有多个 Python 解释器或虚拟环境串了先把这个理清楚否则后面改配置也是白改。我遇到过在系统 Python 里装了旧版、虚拟环境里是新版结果python命令和pip命令指向不同解释器的情况排查了半天才发现是环境问题。提示确认你执行 Django 命令时用的解释器和pip show kombu查的是同一个。用python -m pip show kombu比直接pip show更保险能保证两者一致。三步走完源头基本就清楚了。接下来是修复方案按场景分。4. 换掉django://三种 broker 方案的取舍与落地核心动作就一个把 broker 从django://换成真正的消息中间件。选哪个取决于你的部署条件我把三种主流方案摆出来对比你按自己的情况挑。4.1 方案对比Redis、RabbitMQ、以及干脆不用队列方案部署成本吞吐能力消息可靠性适用场景Redis低一个进程搞定高中等需配置持久化中小项目、任务量中等、已有 RedisRabbitMQ中需独立服务高高支持确认、持久化任务重要、不能丢、需要复杂路由数据库轮询自研低低取决于实现任务极少、能接受延迟Redis 是最省事的选择尤其你项目里如果已经在用 Redis 做缓存直接复用同一个实例、换个 db 编号就行。RabbitMQ 更正统消息确认机制完善适合任务不能丢的场景但要多维护一个服务。至于干脆不用队列如果你的任务量真的小到用数据库轮询都能扛那也可以考虑把 Celery 整个拿掉用 Django 的定时任务或简单的后台线程替代——不过这属于架构层面的取舍不在本文重点提一句让你知道有这条路。下面以 Redis 为例给完整配置RabbitMQ 的差异我会在 4.3 单独说。4.2 Redis 方案的完整配置改动假设你决定用 Redis改动集中在三处依赖、配置、以及可能残留的旧表清理。先装依赖。Celery 用 Redis 当 broker 需要redis这个 Python 客户端pip install celery[redis]celery[redis]这个 extras 写法会自动带上匹配版本的redis包比单独pip install redis更稳避免版本不匹配。然后改配置。老项目里可能叫BROKER_URL新版本 Celery 推荐CELERY_BROKER_URL两个都认但建议统一用新的# settings.py CELERY_BROKER_URL redis://127.0.0.1:6379/0 CELERY_RESULT_BACKEND redis://127.0.0.1:6379/1注意 broker 和 result backend 用了不同的 db 编号/0和/1这是刻意分开的。broker 里存的是待消费的消息result backend 存的是任务执行结果混在一个 db 里排查问题时容易互相干扰分开更清爽。生产环境记得把127.0.0.1换成实际地址有密码的话写成redis://:密码host:6379/0。如果你用的是老式celery.py初始化方式还要确认app.config_from_object(django.conf:settings, namespaceCELERY)这行在它负责把CELERY_前缀的配置喂给 Celery。少了这行你改了CELERY_BROKER_URL也不会生效报错照旧。最后清理旧 transport 留下的数据库表。用django://时 kombu 会在数据库里建django_kombu_message之类的表换掉之后这些表没用了可以删。先确认没有代码在读它们然后python manage.py dbshell # 在数据库 shell 里执行表名以实际为准 DROP TABLE IF EXISTS django_kombu_message;不确定表名的话用python manage.py inspectdb或者直接看数据库的表列表找带kombu字样的。删表前务必备份这是不可逆操作。4.3 换成 RabbitMQ 时的差异点如果你选 RabbitMQ配置改成CELERY_BROKER_URL amqp://用户名:密码127.0.0.1:5672//末尾那两个斜杠有讲究第一个是 URL 分隔符第二个表示 vhost 为空默认 vhost 是/写成//表示根 vhost。这个细节坑过不少人写成单斜杠会连到默认 vhost多斜杠又可能解析出错按amqp://user:passhost:5672//这个格式来最稳。RabbitMQ 还需要额外装amqp客户端pip install celery[amqp]会带上。另外它的消息确认机制比 Redis 严格任务执行失败后的重试行为、acks_late配置的效果都和 Redis 下不太一样切换后建议拿一个会抛异常的任务实测一下重试逻辑别想当然。4.4 改完之后怎么验证真的通了配置改完别急着跑业务先做最小验证。开两个终端一个起 workercelery -A 你的项目名 worker -l info另一个在 Django shell 里发一个测试任务from 你的项目名.tasks import 某个任务 result 某个任务.delay(参数) print(result.get(timeout10))worker 终端能看到任务被接收、执行、返回结果的日志result.get()能拿到返回值才算真的通了。如果 worker 起来了但任务一直PENDING八成是 broker URL 两边不一致比如 worker 读的环境变量和 Django 读的不是同一份回去对一遍配置来源。5. 那些搜不到django://的疑难情况前面说的是明文配置的情况但实际排查中有一类问题特别磨人全局搜不到django://报错却实实在在。这一节专门讲这类隐蔽源头都是我实际遇到过的。5.1 第三方库硬编码默认 broker有些封装 Celery 的第三方库会在自己的defaults.py或conf.py里写死broker_url django://作为默认值然后通过app.conf.update()覆盖你的配置。这种情况下你搜自己项目搜不到得去 site-packages 里搜grep -rn django:// $(python -c import site; print(site.getsitepackages()[0]))找到之后看这个库有没有提供覆盖入口。多数库会读一个特定前缀的配置比如XXX_BROKER_URL你在settings.py里设上就能盖掉默认值。如果它完全不给覆盖入口那要么换库要么在初始化 Celery app 之后手动app.conf.broker_url redis://...强制覆盖——后者属于 hack能救急但不优雅记得在代码里写注释说明原因免得后人踩坑。5.2 环境变量与配置文件不一致还有一种情况配置文件里明明改成了 Redis报错却还是django://。这通常是环境变量在作祟。很多项目用django-environ或python-decouple读环境变量优先级高于代码里的默认值。你改了settings.py的默认值但服务器上的.env或容器环境变量里还留着BROKER_URLdjango://实际生效的是环境变量。排查方法在 Django shell 里打印实际生效的值from django.conf import settings print(settings.CELERY_BROKER_URL)如果打印出来还是django://而你的settings.py里写的是 Redis那就是环境变量覆盖了。去检查.env文件、docker-compose.yml的environment段、以及部署平台的环境变量配置三处都看一遍。5.3 缓存导致的改了没生效Python 的__pycache__和 Celery 的配置缓存偶尔也会造成改了配置但行为没变的假象。虽然django://这种字符串不太可能被字节码缓存搞出问题但如果你改的是环境变量读取逻辑旧的.pyc确实可能让你看到旧行为。清理一下find . -name __pycache__ -type d -exec rm -rf {} 然后重启 worker 和 Django 进程。注意 Celery worker 必须完全重启--autoreload在配置变更时不一定可靠我习惯直接 kill 掉重起避免残留旧配置。注意排查这类问题时养成改完必打印实际生效值的习惯。print(settings.CELERY_BROKER_URL)这一行能省掉大量猜测比盯着配置文件反复看有效得多。6. 从这次报错延伸出的依赖管理经验这个报错表面是个 import 错误根子上是依赖版本漂移问题。老项目在新环境跑不起来十有八九是某个库的 API 或模块结构变了而项目没有锁定版本。借这次机会聊聊怎么避免同类问题反复出现。6.1 锁定依赖版本别让pip install自由发挥requirements.txt里写celery和写celery5.3.6是两回事。前者每次安装都可能拿到不同版本今天能跑明天就报错。我现在的习惯是所有直接依赖都锁精确版本间接依赖用pip freeze生成完整快照。至少保证kombu、celery、redis这几个关键包版本固定。# requirements.txt 片段 celery5.3.6 kombu5.3.4 redis5.0.1kombu虽然是 Celery 的间接依赖但它正是这次报错的主角值得单独锁一行。锁了之后任何环境装出来都是同一套组合不会出现我本地能跑服务器不行的经典问题。6.2 升级依赖前先看 changelog 的 breaking changeskombu 移除djangotransport 这种事在 changelog 里是明确写了的。升级大版本比如 3.x 到 4.x、4.x 到 5.x之前花十分钟扫一眼 breaking changes 列表能避免大部分这类事故。尤其是kombu、celery、Django这种核心库大版本升级从来不是无痛的。我一般的做法是升级前在独立分支上跑一遍完整测试重点验证任务队列、缓存、数据库迁移这几块。测试通过再合入别在主分支上直接pip install -U。6.3 给老项目做依赖体检的清单如果你手上正好有个多年没动的老 Django 项目要复活按这个清单过一遍能提前发现大部分雷pip list --outdated看哪些包落后大版本重点标记跨大版本的。全局搜django://、amqp://、redis://等 broker 字符串确认配置来源。检查settings.py里所有CELERY_开头的配置对照当前 Celery 版本的文档确认没被废弃。跑python manage.py check和python manage.py migrate --plan看有没有配置或迁移层面的警告。起一个 worker 发个测试任务端到端验证队列链路。这套流程走下来像kombu.transport.django这种问题基本在正式跑业务前就能暴露不至于上线才发现。7. 几个容易被忽略的收尾细节改完配置、验证通过还有几个收尾动作值得做不然可能留下隐患。第一检查有没有遗留的djcelery或类似的老包。早期有个django-celery包专门配合django://transport 用它会在INSTALLED_APPS里注册、建自己的表。换掉 transport 后这个包也没用了从INSTALLED_APPS里移除pip uninstall django-celery再跑一次migrate清理它留下的表。留着不删虽然不一定报错但会让人误以为项目还在用老方案。第二更新项目文档和 README 里的启动说明。很多老项目的 README 还写着确保 kombu 用 3.x 版本新同事照着做又是一轮踩坑。把 broker 配置、依赖版本、启动命令同步更新比什么都强。第三如果项目用了 Docker检查Dockerfile和docker-compose.yml里的基础镜像和依赖安装步骤。老镜像里可能预装了旧版 kombupip install -r requirements.txt时如果没加--upgrade可能不会覆盖。稳妥的做法是在Dockerfile里显式pip install --no-cache-dir -r requirements.txt并确保构建时清掉旧层缓存。我个人在实际操作中的体会是这类模块找不到的报错九成以上不是环境玄学而是配置和依赖版本对不上。与其反复重装、降级、清缓存不如先把报错信息逐字读一遍——它往往已经告诉你答案了只是需要你顺着模块路径往回推找到那个还在引用废弃配置的地方。定位到源头之后换成 Redis 或 RabbitMQ 都是十几分钟的事真正花时间的是确认到底是谁在引用它。把这一步做扎实后面就顺了。