Django/Wagtail项目django-debug-toolbar点击面板返回404错误如何解决

问题现象 #

在Django/Wagtail项目中配置django-debug-toolbar调试工具时，工具栏可以正常显示，但点击任意面板查看调试详情时会返回404 Not Found错误。

原始配置 #

urls.py配置 #

import debug_toolbar
from django.conf import settings
from django.urls import include, path
from django.contrib import admin
from django.urls import path
from wagtail.admin import urls as wagtailadmin_urls
from wagtail.core import urls as wagtail_urls
from wagtail.documents import urls as wagtaildocs_urls
from search import views as search_views

urlpatterns = [
    path('django-admin/', admin.site.urls),

    path('admin/', include(wagtailadmin_urls)),
    path('documents/', include(wagtaildocs_urls)),

    path('search/', search_views.search, name='search'),

]

urlpatterns = urlpatterns + [
    path("", include(wagtail_urls)),
    path('__debug__/', include(debug_toolbar.urls)),
]

if settings.DEBUG:
    from django.conf.urls.static import static
    from django.contrib.staticfiles.urls import staticfiles_urlpatterns

    urlpatterns += staticfiles_urlpatterns()
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

dev.py配置 #

from .base import *

# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = 'hidden'

# SECURITY WARNING: define the correct hosts in production!
ALLOWED_HOSTS = ['*'] 

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

INSTALLED_APPS = INSTALLED_APPS + [
    'debug_toolbar'
]

MIDDLEWARE = MIDDLEWARE + [
    'debug_toolbar.middleware.DebugToolbarMiddleware',
]

INTERNAL_IPS = ("127.0.0.1")

try:
    from .local import *
except ImportError:
    pass

问题原因 #

Django路由匹配遵循从上到下的优先级规则，原配置中Wagtail的全局通配路由path("", include(wagtail_urls))位于debug toolbar路由之前，所有未被上层路由匹配的请求都会被Wagtail路由拦截，__debug__开头的调试请求无法命中对应路由，因此返回404。

解决方法 #

调整urls.py中的路由顺序，将path('__debug__/', include(debug_toolbar.urls))配置项放置在Wagtail全局通配路由的前方，避免被通配路由拦截。
修改后的核心路由配置如下：

urlpatterns = [
    path('django-admin/', admin.site.urls),
    # 将debug toolbar路由移到Wagtail通配路由之前
    path('__debug__/', include(debug_toolbar.urls)),
    path('admin/', include(wagtailadmin_urls)),
    path('documents/', include(wagtaildocs_urls)),
    path('search/', search_views.search, name='search'),
]

urlpatterns = urlpatterns + [
    # 全局通配路由放在所有特定路由之后
    path("", include(wagtail_urls)),
]

内容的提问来源于stack exchange，提问作者pedro henrique garcia pinto