1. 这个报错到底在说什么：从模块导入链路拆起

先把结论摆在前面：No module named 'kombu.transport.django'这个报错，本质上不是 Django 的问题，也不是你代码写错了，而是kombu 这个库在某个版本之后把 Django 传输后端整个移除了，而你（或者你依赖的某个包）的配置里还写着用 Django 的 ORM 当消息队列的存储后端。Python 在 import 阶段找不到对应模块，直接抛ModuleNotFoundError，Django 项目启动或执行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.x），kombu.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.<scheme>，django://就对应kombu.transport.django，找不到就抛错。

我整理了一张对照表，把版本和这个 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_URL=django://。如果搜到了，恭喜，问题源头明确，直接进第 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 是最省事的选择，尤其你项目里如果已经在用 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', namespace='CELERY')这行在，它负责把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:pass@host:5672//这个格式来最稳。

RabbitMQ 还需要额外装amqp客户端，pip install "celery[amqp]"会带上。另外它的消息确认机制比 Redis 严格，任务执行失败后的重试行为、acks_late配置的效果都和 Redis 下不太一样，切换后建议拿一个会抛异常的任务实测一下重试逻辑，别想当然。

4.4 改完之后怎么验证真的通了

配置改完别急着跑业务，先做最小验证。开两个终端，一个起 worker：

celery -A 你的项目名 worker -l info

另一个在 Django shell 里发一个测试任务：

from 你的项目名.tasks import 某个任务 result = 某个任务.delay(参数) print(result.get(timeout=10))

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_URL=django://，实际生效的是环境变量。

排查方法：在 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和写celery==5.3.6是两回事。前者每次安装都可能拿到不同版本，今天能跑明天就报错。我现在的习惯是：所有直接依赖都锁精确版本，间接依赖用pip freeze生成完整快照。至少保证kombu、celery、redis这几个关键包版本固定。

# requirements.txt 片段 celery==5.3.6 kombu==5.3.4 redis==5.0.1

kombu虽然是 Celery 的间接依赖，但它正是这次报错的主角，值得单独锁一行。锁了之后，任何环境装出来都是同一套组合，不会出现"我本地能跑服务器不行"的经典问题。

6.2 升级依赖前先看 changelog 的 breaking changes

kombu 移除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里的基础镜像和依赖安装步骤。老镜像里可能预装了旧版 kombu，pip install -r requirements.txt时如果没加--upgrade，可能不会覆盖。稳妥的做法是在Dockerfile里显式pip install --no-cache-dir -r requirements.txt，并确保构建时清掉旧层缓存。

我个人在实际操作中的体会是，这类"模块找不到"的报错，九成以上不是环境玄学，而是配置和依赖版本对不上。与其反复重装、降级、清缓存，不如先把报错信息逐字读一遍——它往往已经告诉你答案了，只是需要你顺着模块路径往回推，找到那个还在引用废弃配置的地方。定位到源头之后，换成 Redis 或 RabbitMQ 都是十几分钟的事，真正花时间的是确认"到底是谁在引用它"。把这一步做扎实，后面就顺了。