Django的路由系统负责把浏览器请求的URL地址映射到对应的视图函数上，是整个请求处理流程的入口。理解urls.py的配置方式，是学习Django绕不开的一步。本文将结合代码实例，从基础配置讲到进阶用法，把路由配置中的关键点逐一拆解。
一、urls.py的基本结构与工作原理
创建一个Django项目后，根目录下会自动生成一个与项目同名的包，里面包含urls.py文件，这就是全局路由配置文件。Django收到请求后，会从ROOT_URLCONF设置项指定的模块开始，按顺序匹配urlpatterns列表中的每一条规则，一旦命中就停止匹配并调用对应视图。
最小化的一套配置如下：
from django.contrib import admin
from django.urls import path
from blog import views
urlpatterns = [
path('admin/', admin.site.urls),
path('articles/', views.article_list, name='article-list'),
]
urlpatterns必须是一个列表（或元组），列表中的每个元素由path()或re_path()生成。Django在匹配时是从上到下顺序执行的，所以更具体的规则要放在前面，否则会被宽泛的规则提前拦截，这是新手最常踩的坑之一。
另一个值得注意的细节是末尾斜杠问题。Django默认开启了APPEND_SLASH设置，当请求的URL不匹配但补上斜杠后能匹配时，服务器会返回301重定向到带斜杠的地址。比如访问/articles会被重定向到/articles/。如果不想启用这个行为，可以在settings.py中把它设为False，但要保证前后端对URL格式的约定保持一致。
二、path与re_path：两种路由写法的取舍
Django 2.0之后推荐使用path()函数，它语法简洁、可读性强，支持在URL中捕获参数并自动做类型转换。常见写法如下：
from django.urls import path
from blog import views
urlpatterns = [
# 捕获整数类型的文章id，视图函数直接拿到int
path('article/<int:article_id>/', views.article_detail),
# 捕获字符串参数，str不能包含斜杠
path('user/<str:username>/', views.user_profile),
# slug类型：字母、数字、连字符、下划线
path('post/<slug:post_slug>/', views.post_detail),
# uuid类型：常用于一次性链接、激活邮件
path('activate/<uuid:token>/', views.activate_account),
]
内置的路径转换器有str、int、slug、uuid、path五种。其中path转换器比较特殊，它可以匹配包含斜杠的完整路径，适合做文件路由。如果这些转换器不够用，还可以自定义转换器，注册后就能在path中使用。
而在需要更灵活匹配规则的场景下，re_path()仍然有它的用武之地。它接收一个正则表达式作为路由规则，捕获组的内容会以字符串形式传给视图：
from django.urls import re_path
from blog import views
urlpatterns = [
# 匹配四位数字的年份，如 /archive/2024/
re_path(r'^archive/(?P<year>\d{4})/$', views.archive),
# 命名分组捕获月份和日期
re_path(r'^archive/(?P<year>\d{4})/(?P<month>\d{2})/$', views.archive_month),
]
两者的选择原则很明确：能用path()解决的优先用path()，只有在匹配逻辑复杂到内置转换器无法表达时才使用re_path()。正则路由虽然强大，但可读性差、容易出错，而且捕获的参数都是字符串，视图里还得自己转换类型，长期维护成本更高。
三、使用include拆分大型项目的路由
当项目包含多个应用时，把所有路由都堆在全局urls.py里会让文件迅速膨胀，且不同应用之间容易产生命名冲突。Django提供了include()机制，让每个应用管理自己的路由，全局文件只负责分发：
# 项目全局 urls.py
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
path('admin/', admin.site.urls),
path('blog/', include('blog.urls')),
path('shop/', include('shop.urls')),
]
# blog/urls.py
from django.urls import path
from . import views
app_name = 'blog' # 声明应用命名空间
urlpatterns = [
path('', views.index, name='index'),
path('list/', views.article_list, name='article-list'),
]
这样拆分之后，blog应用下的路由都挂在/blog/前缀下，shop应用同理。每个应用内部的URL修改不会影响全局文件，多人协作时也减少了同一文件的冲突。
注意app_name = 'blog'这一行，它声明了应用的命名空间。当多个应用中存在同名的路由（比如两个应用都有index）时，反解析时必须带上命名空间才能准确定位，写法是reverse('blog:index')。如果省略命名空间，Django会返回最后一个匹配的URL，结果往往不是你想要的。
四、URL命名与reverse反解析
在模板和视图中硬编码URL是典型的反模式。一旦路由规则调整，所有写死的地方都得逐一修改。正确做法是给每条路由起名字，然后通过名字反查URL：
# 视图中使用reverse
from django.urls import reverse
from django.shortcuts import redirect
def go_to_list(request):
url = reverse('blog:article-list')
return redirect(url)
# 模板中使用url标签
# <a href="{% url 'blog:article-detail' article.id %}">{{ article.title }}</a>
带参数的路由在反解析时把参数传进去即可，例如reverse('blog:article-detail', args=[42])会生成/blog/article/42/。这样模板与路由彻底解耦，路由规则怎么改，代码里的引用都会自动更新。
此外，视图函数上还可以使用@permalink风格的get_absolute_url方法，为模型实例提供标准URL。这个方法内部调用reverse返回结果，供后台管理和模板统一使用，是保持URL引用一致性的推荐做法。
五、常见问题与排查思路
配置路由时经常遇到404错误，排查可以从这几个方向入手：首先确认访问的URL是否与urlpatterns中的规则完全匹配，注意斜杠和大小写；其次检查规则顺序，宽泛规则是否把请求提前截胡；最后确认ROOT_URLCONF指向的模块是否正确，多环境部署时这个配置有时会被覆盖。
另一个高频问题是参数类型不匹配。比如用<int:pk>却访问了非数字路径，Django会认为不匹配并继续向下找，最终404。这时可以临时把规则改成<str:pk>验证视图本身是否正常，再回头收紧匹配规则。
部署到生产环境后如果出现循环重定向，多半是APPEND_SLASH与反向代理的路径处理叠加造成的。排查时可暂时关闭该设置观察现象，或在代理层统一处理末尾斜杠，避免多层都做重定向。
总体来说，Django的路由配置遵循「path优先、include拆分、命名引用」三原则，就能搭建出一套清晰、可扩展的路由体系。随着项目规模增长，这套结构的价值会越来越明显。
Django URL配置Python路由Django path函数修改时间：2026-09-14 04:10:43