1. 这个报错到底在说什么
如果你正在维护一个有些年头的 Django 项目，某天敲下python manage.py runserver或者启动 Celery worker，终端冷不丁甩出一句No module named 'kombu.transport.django'，然后进程直接退出，那你大概率是撞上了 Kombu 版本演进过程中一个非常典型的历史遗留问题。这个报错本身并不复杂，但它背后牵扯的是 Celery、Kombu、Django 三者版本兼容性的一整条链路，处理不好容易反复踩坑。
先把结论摆出来：kombu.transport.django这个模块在 Kombu 4.0 之后就已经被移除了。也就是说，你的项目代码或者配置里，仍然在引用一个早已不存在的传输后端。报错信息里的kombu.transport.django是 Kombu 早期版本提供的一个基于 Django ORM 的消息传输实现，它允许你把 Django 的数据库直接当作消息队列来用，省去额外部署 RabbitMQ 或 Redis 的麻烦。这个设计在当年确实方便，尤其适合小型项目和快速原型，但它的性能和可靠性一直被人诟病，最终在 Kombu 4.0 的清理中被正式砍掉。
这个报错适合谁来参考？如果你手上维护的是 Django 1.x 时代的老项目，或者从别人那里接手了一套 Celery 配置，又或者你在照着某些年代久远的教程搭建环境，那这篇内容基本就是为你准备的。即便你是刚接触 Django 和 Celery 的新手，理解这个报错的来龙去脉，也能帮你建立起对消息队列后端选型的基本判断力，避免以后在类似问题上绕弯路。
我见过太多人遇到这个报错的第一反应是pip install kombu或者pip install django-kombu，结果装完发现报错依旧，甚至引出新的依赖冲突。原因很简单：这个模块不是"没装"，而是"已经不存在了"。你得先搞清楚它为什么消失，才能决定是降级 Kombu 还是改配置换后端。下面我就按这个思路，把这个报错从根上拆开讲清楚。
2. 报错背后的版本演进逻辑
2.1 Kombu 传输后端的历史变迁
要理解这个报错，得先知道 Kombu 是什么。Kombu 是 Celery 依赖的消息传输抽象层，它把不同消息中间件（RabbitMQ、Redis、Amazon SQS 等）的操作封装成统一的接口，让 Celery 不用关心底层用的是哪种队列。你可以把 Kombu 理解成一个"消息队列的驱动适配器"，Celery 只管发任务和收结果，具体怎么传输由 Kombu 对接。
在 Kombu 3.x 及更早的版本里，官方提供了一系列传输后端实现，其中就包括kombu.transport.django。这个后端的思路很直接：既然项目已经在用 Django，数据库连接现成的，那干脆把消息也存到数据库表里，用 ORM 来读写消息。对于不想额外维护一套消息中间件的小团队来说，这确实降低了部署门槛。
但这个方案的问题也很明显。数据库作为消息队列，在高并发场景下性能极差，消息的投递、确认、重试都靠数据库事务来保证，锁竞争严重，吞吐量上不去。而且消息堆积会直接把业务库撑爆，运维上很难隔离。Kombu 官方在 4.0 版本做了一次大规模清理，把这类"非主流"的传输后端统一移除了，kombu.transport.django就在被移除的名单里。从那以后，任何指向这个模块的配置都会在导入阶段直接报ModuleNotFoundError。
2.2 为什么老项目会引用到这个模块
问题在于，很多老项目的配置是在 Kombu 3.x 时代写下的，当时这么配完全没问题，代码跑得好好的。等到某次升级依赖，Kombu 被 pip 拉到了 4.x 甚至 5.x，配置里那句BROKER_URL = 'django://'或者broker_transport = 'django'就变成了定时炸弹。项目平时不启动 Celery 就没事，一旦启动 worker 或者触发任务，导入传输后端时立刻炸掉。
还有一种常见情况是间接引用。有些第三方包或者项目内部的工具模块，在初始化 Celery app 时硬编码了transport='django'，你在主配置里翻半天找不到django://字样，但报错照样出现。这时候就得顺着报错的调用栈往上找，看看到底是哪个模块在设置这个传输方式。
我处理过的一个案例里，项目根目录下有个celery.py，里面写着app = Celery('proj', broker='django://')，但主 settings 里又配了 Redis 的地址。开发者以为 settings 会覆盖，实际上 Celery app 初始化时传的参数优先级更高，结果一直走的是那个已经不存在的 django 传输。这种配置分散、优先级混乱的情况在老项目里特别普遍，排查时不能只盯着 settings.py 看。
2.3 报错出现的典型触发场景
这个报错不会在你写代码时冒出来，它只在运行时触发，而且触发点相对固定。最常见的三个场景：一是执行python manage.py runserver时，如果项目在AppConfig.ready()或者某个被自动导入的模块里初始化了 Celery，启动阶段就会崩；二是启动 Celery worker，celery -A proj worker -l info一执行就报；三是运行任何调用了.delay()或.apply_async()的代码，任务入队时去加载传输后端，同样会炸。
值得注意的是，有些项目在开发环境用CELERY_ALWAYS_EAGER = True让任务同步执行，这时候根本不走消息队列，所以报错不会出现。一旦切到生产配置或者关掉 eager 模式，问题立刻暴露。这种"开发环境好好的，上线就崩"的情况，往往让人措手不及，排查时容易往环境差异上想，反而忽略了配置本身的历史包袱。
3. 定位问题的完整排查路径
3.1 从报错调用栈反查配置源头
拿到报错后，第一件事不是急着改，而是把完整的调用栈看清楚。Python 的 traceback 会告诉你这个导入是在哪个文件、哪一行触发的。通常栈底是 Celery 或 Kombu 的内部代码，往上翻能找到你项目里的配置文件或初始化代码。重点看broker或transport相关的赋值语句出现在哪个模块。
如果调用栈里全是第三方库的路径，看不到项目代码，那说明配置是通过环境变量或者某个被导入的包间接设置的。这时候可以用一个笨但有效的办法：在项目里全局搜索django://、transport、broker_url这几个关键词，把搜索结果逐个过一遍。搜索范围要包括.py文件、.env文件、docker-compose.yml、启动脚本，甚至 CI 配置，因为 broker 地址经常被塞在这些地方。
提示：搜索时注意大小写和拼写变体，比如
DJANGO://、broker_transport、BROKER_TRANSPORT，老项目的配置风格五花八门，漏掉一个就可能白忙活。
3.2 确认当前安装的 Kombu 与 Celery 版本
定位到配置源头后，下一步是确认版本现状。执行pip show kombu celery看实际安装的版本号。如果 Kombu 是 4.x 及以上，那kombu.transport.django必然不存在，报错是必然的。同时看一眼 Celery 的版本，因为 Celery 和 Kombu 之间有版本对应关系，Celery 4.x 通常搭配 Kombu 4.x，Celery 5.x 搭配 Kombu 5.x，混装容易出现各种兼容问题。
有时候还会遇到pip list里显示装了某个版本，但实际导入的是另一个版本的情况，尤其是项目里存在多个 Python 环境或者用了虚拟环境但没激活。可以用python -c "import kombu; print(kombu.__version__, kombu.__file__)"直接打印运行时实际加载的版本和路径，这个结果比pip show更可信，因为它反映的是解释器真正看到的东西。
3.3 区分"配置引用"与"代码硬编码"
排查时要把两类引用分开处理。一类是配置层面的，比如BROKER_URL = 'django://'，这类改起来相对简单，换成别的后端地址即可。另一类是代码层面的硬编码，比如某个工具函数里写死了Celery(broker='django://')，或者某个自定义的传输类继承自kombu.transport.django，这类改动涉及代码逻辑，需要更谨慎。
我建议先用搜索把所有引用点列出来，做成一张清单，标注每个引用点的位置、类型（配置还是代码）、影响范围。这样改的时候心里有数，不会改了一处漏了另一处。清单可以简单用表格记录，下面给个示例结构。
| 引用位置 | 引用类型 | 具体内容 | 处理方式 |
|---|---|---|---|
| settings.py | 配置 | BROKER_URL = 'django://' | 改为 Redis 地址 |
| proj/celery.py | 代码硬编码 | Celery(broker='django://') | 移除 broker 参数，走配置 |
| tasks/utils.py | 代码硬编码 | transport='django' | 删除该参数 |
这张表看起来简单，但实际排查时非常管用。老项目的配置往往散落在十几个文件里，没有清单很容易改漏，改漏的后果就是你以为修好了，一跑又报同样的错，白白浪费一轮调试时间。
4. 三种修复方案的取舍与实操
4.1 方案一：升级配置改用 Redis 作为消息后端
这是我最推荐的方案，也是绝大多数项目的正确归宿。Redis 部署简单、性能足够、社区资料丰富，作为 Celery 的 broker 和 result backend 都很成熟。具体操作分几步走。
第一步，安装依赖。pip install redis装的是 Python 客户端，Redis 服务本身需要单独部署，本地开发可以直接用包管理器装或者跑个容器。第二步，改配置。把BROKER_URL = 'django://'换成BROKER_URL = 'redis://127.0.0.1:6379/0'，如果还要存任务结果，再加一行CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/1'。注意 broker 和 backend 用不同的 db 编号，避免键冲突，这是个很容易被忽略的细节。
第三步，清理残留引用。把前面清单里所有指向django://的地方都改掉，包括硬编码的Celery(broker=...)。第四步，验证。启动 worker 看是否正常连接，再发一个测试任务确认能入队和执行。测试任务可以写个最简单的@app.task def add(x, y): return x + y，然后add.delay(1, 2)看结果。
注意：Redis 作为 broker 时，如果开启了持久化（RDB 或 AOF），消息的可靠性会比纯内存模式好一些，但仍然不如 RabbitMQ 的确认机制严谨。对消息丢失零容忍的场景，建议直接上 RabbitMQ，别在 Redis 上纠结。
4.2 方案二：降级 Kombu 到 3.x 维持原状
有些项目因为历史原因，短期内没法改配置，或者改动涉及太多业务代码，这时候可以考虑降级 Kombu 到 3.x，让kombu.transport.django重新可用。操作上就是pip install 'kombu<4.0'，同时要注意 Celery 的版本也得跟着降，因为 Celery 4.x 依赖 Kombu 4.x，硬降 Kombu 会导致 Celery 导入失败。
这个方案的代价很明显：你把自己锁死在了一个多年前的依赖组合上，后续任何安全更新、bug 修复都享受不到，而且随着 Python 版本升级，老版本 Kombu 可能连装都装不上。我一般只建议把它当作临时过渡手段，比如生产环境紧急回滚时用一下，长期方案还是得往方案一或方案三迁移。
降级时还要注意依赖冲突。pip install 'kombu<4.0'之后，pip 可能会提示 Celery 的版本不满足依赖要求，这时候要么一起降 Celery，要么用--no-deps强行装但承担运行风险。我的经验是别用--no-deps硬来，依赖关系乱了之后排查成本极高，宁可把 Celery 和 Kombu 的版本一起锁定，写进requirements.txt里固定住。
4.3 方案三：改用数据库以外的轻量后端
如果项目规模很小，又不想引入 Redis 或 RabbitMQ，还有一个折中思路：用 SQLAlchemy 作为传输后端，也就是sqlalchemy://。这个后端在 Kombu 4.x 里仍然保留，它把消息存到关系型数据库里，思路和当年的 django 后端类似，但实现更通用，不绑定 Django ORM。
配置方式是BROKER_URL = 'sqlalchemy+sqlite:///celery.db'或者指向 MySQL、PostgreSQL。需要额外装sqlalchemy和对应的数据库驱动。这个方案的好处是不用新增中间件，坏处和当年的 django 后端一样：性能有限，不适合高并发。我一般只在单机小工具、内部脚本这类场景推荐它，正经的 Web 服务还是老老实实上 Redis。
三种方案的适用场景可以对照下面这张表来选。
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 改用 Redis | 绝大多数生产项目 | 性能好、生态成熟、部署简单 | 需额外维护 Redis 服务 |
| 降级 Kombu 3.x | 紧急回滚、短期过渡 | 改动最小、配置不动 | 锁死老版本、无安全更新 |
| 改用 SQLAlchemy | 单机小工具、内部脚本 | 不引入新中间件 | 性能差、不适合高并发 |
5. 实操过程中的关键细节与避坑
5.1 环境变量与配置文件的优先级陷阱
改配置时最容易翻车的地方，是环境变量和配置文件的优先级。很多项目在 settings 里写了BROKER_URL = os.environ.get('BROKER_URL', 'redis://...')，你以为默认值是 Redis 就万事大吉，结果部署环境里BROKER_URL环境变量还留着老的django://，运行时环境变量优先，报错照旧。
排查这类问题，最直接的办法是在启动脚本里打印实际生效的配置。可以在 Celery app 初始化后加一行日志，输出app.conf.broker_url的值，确认它到底指向哪里。别嫌这行日志丑，排查阶段它能省下大量猜测时间。确认没问题后再把日志去掉或者降级为 debug 级别。
还有一种隐蔽情况是.env文件被多个工具读取，比如python-dotenv和django-environ同时存在，加载顺序不同导致最终值不一样。这种时候要理清哪个工具先加载、哪个后加载，后加载的会覆盖先加载的。我一般建议项目里只保留一种环境变量加载方式，减少这类不确定性。
5.2 Celery app 初始化顺序引发的连锁问题
Celery 的 app 初始化顺序也是个坑。Django 项目里常见的写法是在proj/celery.py里创建 app，然后在proj/__init__.py里导入，确保 Django 启动时 Celery 也被加载。如果这个导入链条里某个模块在 app 创建之前就引用了配置，可能拿到的是默认值而不是你设置的值。
更麻烦的是循环导入。celery.py导入 settings，settings 里又通过某个 app 的ready()方法间接导入 celery，形成环。这种情况下报错信息往往很迷惑，表面看是No module named 'kombu.transport.django'，实际根因是初始化顺序错乱导致配置没生效。排查时可以在celery.py顶部加打印，看 app 创建时读到的 broker 是什么，逐步缩小范围。
我的习惯是把 Celery 的配置集中在一个地方，要么全放 settings，要么全放celery.py，不要两边都写。两边都写看着灵活，实际是给自己埋雷，尤其是团队协作时，别人改了一边不知道另一边还有覆盖，问题很难复现。
5.3 依赖锁定与 CI 环境的同步
修好本地环境不代表万事大吉，CI 环境和生产环境如果依赖没锁，下次构建可能又拉回老版本或者拉到不兼容的新版本。正确做法是把celery、kombu、redis的版本都写进requirements.txt并固定，比如celery==5.3.6、kombu==5.3.4、redis==5.0.1，用==而不是>=。
固定版本后，还要确保 CI 的缓存不会捣乱。有些 CI 会缓存 pip 的下载包，如果缓存里存着老版本的 wheel，即使 requirements 改了也可能装出旧版本。遇到这种诡异情况，清一次 CI 缓存再跑，往往就正常了。这个坑我踩过不止一次，表现就是本地好好的，CI 上死活报同样的错，查半天发现是缓存作祟。
提示：升级依赖后，记得在本地删掉
__pycache__和.pyc文件再跑一次。虽然 Python 的字节码缓存一般会自己失效，但老项目里偶尔会遇到缓存没更新的情况，清一下能排除干扰。
6. 常见问题速查与经验沉淀
6.1 报错依旧但配置已改的排查思路
改完配置还报同样的错，先别怀疑人生，按顺序排查几个点。第一，确认改的文件是不是运行时真正加载的那个，多环境、多 settings 模块的项目很容易改错文件。第二，确认有没有.pyc缓存或者 IDE 的缓存干扰，清掉重跑。第三，确认没有其他地方还在引用django://，用全局搜索再扫一遍。第四，确认虚拟环境激活正确，which python和pip show kombu对得上。
如果这四步都过了还报错，那就把完整 traceback 贴出来逐行看，重点看报错文件路径是不是你预期的那个。有时候项目里装了同名的包，或者sys.path里有奇怪的路径，导致导入的不是你以为的那个模块。用python -c "import sys; print(sys.path)"看路径列表，能发现不少隐藏问题。
6.2 升级后任务丢失或重复执行的应对
从 django 后端切到 Redis 后，有些项目会发现任务行为变了，比如任务偶尔丢失或者重复执行。这不是 Redis 的问题，而是不同后端的语义差异导致的。django 后端基于数据库事务，消息的可见性和确认机制跟 Redis 不一样，切换后需要重新审视任务的幂等性设计。
应对办法是给关键任务加幂等保护，比如用任务 ID 做去重，或者在任务开头检查状态标记。另外，Redis 作为 broker 时，如果 worker 在执行任务途中崩溃，消息可能已经出队但没执行完，默认配置下不会自动重投。对可靠性要求高的场景，可以开启task_acks_late = True让消息在任务完成后才确认，配合task_reject_on_worker_lost = True处理 worker 异常退出的情况。这两个参数的具体取值要根据业务容忍度来定，没有放之四海皆准的答案。
6.3 老项目迁移的节奏建议
如果你手上是个运行多年的老项目，别想着一次性把所有 Celery 相关配置推倒重来。我的建议是分阶段走：第一阶段先把报错止住，用降级或者临时改配置的方式让服务能跑起来；第二阶段在测试环境完整验证新后端，包括任务投递、执行、结果回写、异常重试这些路径；第三阶段再灰度切生产，观察一段时间确认稳定后再清理老配置。
迁移过程中保留回滚能力很重要。改配置前把老配置备份一份，新配置用开关控制，出问题能快速切回去。别嫌麻烦，真出问题时这几分钟的备份能救你一晚上的加班。我见过太多人改配置不留后路，结果生产出问题只能干着急。
6.4 一张表收尾：问题与对策速查
| 现象 | 可能原因 | 对策 |
|---|---|---|
| 报错 No module named 'kombu.transport.django' | 配置仍指向已移除的 django 传输 | 改用 Redis 或 SQLAlchemy 后端 |
| 改配置后报错依旧 | 环境变量覆盖、缓存、改错文件 | 打印实际生效配置、清缓存、全局搜索 |
| 降级 Kombu 后 Celery 导入失败 | Celery 与 Kombu 版本不匹配 | 同步降级 Celery 并锁定版本 |
| 切换后端后任务丢失 | 后端语义差异、确认机制不同 | 开启 acks_late、加幂等保护 |
| CI 上复现本地已修复的报错 | 依赖未锁定、CI 缓存旧包 | 固定版本号、清 CI 缓存 |
这张表里的每一条都是实际排查中反复出现的模式，遇到问题时先对照着过一遍，能快速缩小范围。真正棘手的往往不是报错本身，而是报错背后那些配置分散、版本混乱、环境不一致的隐性因素。把配置集中管理、依赖固定版本、改动留好回滚，这三条做到了，这类问题基本就翻不出什么浪花。
我个人在实际处理这类老项目时的体会是，报错信息只是冰山一角，真正花时间的是摸清项目的历史配置脉络。与其急着改那一行django://，不如先花半小时把 Celery 相关的配置全部梳理一遍，画个简单的依赖和加载顺序图，后面改起来会顺很多。很多时候改一处漏一处，根源就是没把全局看清楚就动手了。
