刚开始学 Django 的时候我最大的感受不是“难”而是“乱”。网上的教程一会儿讲模型一会儿讲视图一会儿又来一个第三方库每个知识点单看都能懂但拼在一起就不知道项目到底是怎么跑起来的。如果你也有这种感觉说明缺的不是代码量而是一条能串起所有知识点的主线。这篇文章不打算把 Django 的每个功能都讲一遍而是围绕一条主线来写一次浏览器请求进入 Django 后是如何经过 URL 路由、视图函数、模型和模板最终把页面返回给用户的。抓住这条主线你就知道学 Django 应该先学什么、后学什么遇到报错时该去哪个环节查也能用最小的成本完成第一个能跑通的 Django 网站。本文适合完全没接触过 Django 的 Python 新手也适合学过一点但总是“学了就忘”的开发者。全文包含环境搭建、核心概念、可运行的完整项目、常见报错排查以及工程实践建议代码都可以直接复制使用。1. 背景与核心概念1.1 Django 是什么解决什么问题Django 是一个用 Python 编写的开源 Web 框架诞生于新闻网站的业务环境所以它从第一天起就在考虑三个问题快速迭代、多人协作、高并发下的稳定性。翻译成开发者的语言就是你不需要重复造轮子它已经帮你把网站开发中最常用、最繁琐的部分都准备好了。具体来说Django 自带的东西包括URL 路由系统把用户访问的网址映射到对应的处理函数。ORM对象关系映射用 Python 代码操作数据库不需要手写大量 SQL。模板引擎把数据渲染成 HTML 页面。Admin 后台自动生成一个可以管理数据的后台界面。表单处理、认证、会话、中间件覆盖 Web 开发的常见需求。所以 Django 常被称为“全家桶”式框架。它可能不如 Flask 那样轻量灵活但好处是你不需要为选哪个数据库库、哪个模板引擎、哪个表单库而纠结框架已经帮你做好了一致性的选择。1.2 Django 在国内的使用情况很多新手会犹豫学了 Django 在国内有用吗从实际招聘和技术社区反馈来看Python 后端岗位中 Django 和 Flask 是出现频率最高的两个 Web 框架。Django 尤其适合快速搭建内容型网站、企业内部管理系统、自动化运维平台、数据可视化后台这类项目。因为这些系统往往需要一个稳定的 Admin 后台而 Django 自带的 Admin 几乎可以零成本承接这个需求。另一个被低估的场景是个人项目和自动化工具。很多人用 Python 写脚本处理数据、跑爬虫、做自动化但脚本一多就没法管理这时候把脚本包装成一个 Django 项目用 Web 页面去触发和展示结果会让整个系统的可用性和维护性提升一大截。当然Django 的学习曲线相比 Flask 会稍微陡峭一点。问题不在于语法难而在于知识点多新手容易迷失。解决这个问题的最好办法就是先围绕一条主线跑通一个最小项目之后再逐步拓宽。1.3 抓住学习主线一次请求的完整旅程Django 开发并不要求你一次性掌握所有组件你只需要先理解下面这条主线浏览器输入网址 ↓ Django 的 URL 路由找到对应的视图函数 ↓ 视图函数处理业务逻辑如果需要数据就通过 ORM 操作数据库 ↓ 视图函数把数据交给模板渲染成 HTML ↓ 浏览器收到 HTML 页面并展示这条主线就是 Django 的MTV 架构Model-Template-View模型-模板-视图的运行流程Model模型负责和数据库打交道对应数据库中的表。Template模板负责页面展示是 HTML 文件中可以动态填充数据的部分。View视图负责业务逻辑相当于 Model 和 Template 之间的桥梁。很多教程会强调 MTV 和 MVC 的区别但新手阶段你只需要知道用户请求先去找 ViewView 需要数据时找 Model需要展示时找 Template。后面所有学习内容都可以挂在这条主线上。2. 环境准备与版本说明2.1 需要准备的工具在开始写代码之前先把环境准备好。Django 是 Python 的第三方库所以最基础的要求是电脑上已经安装了 Python 3。工具说明Python 3建议使用 Python 3.8 及以上版本Django 新版本对 Python 版本有要求pipPython 自带的包管理工具用来安装 DjangovenvPython 自带的虚拟环境模块用来隔离项目依赖IDE推荐 PyCharm 或 VS Code初学者用 VS Code 更轻量浏览器Chrome、Edge 均可用于访问开发服务器页面这篇文章以 Django 当前常见的 LTS 版本为例这类版本维护周期长、资料多、踩坑少。你不需要纠结具体版本安装时优先选择 LTS 版本或者最新稳定版即可。2.2 虚拟环境与安装步骤为什么一定要用虚拟环境因为不同项目的 Python 库版本可能互相冲突。比如项目 A 需要 Django 3.2项目 B 需要 Django 4.2如果全部装在系统全局环境里就会互相覆盖。虚拟环境相当于给每个项目一个独立的“沙盒”。下面是在 Windows 和 macOS/Linux 上通用的命令行操作# 1. 创建项目目录并进入目录 mkdir django_demo cd django_demo # 2. 创建虚拟环境 python -m venv venv # 3. 激活虚拟环境 # Windows 下执行 venv\Scripts\activate # macOS / Linux 下执行 source venv/bin/activate # 4. 安装 Django pip install django # 5. 验证安装结果 python -m django --version激活虚拟环境后命令行前面通常会出现(venv)前缀说明你当前已经处于虚拟环境中安装的库只会影响这个项目。如果你执行python -m django --version能看到版本号输出说明 Django 已经安装成功。如果提示找不到模块通常有两种原因一是虚拟环境没有激活二是 pip 安装过程有问题。此时可以重新激活环境再执行一次安装命令。2.3 创建一个最小项目验证环境安装成功后先不要急着写代码用 Django 提供的命令创建一个空项目确认整个链路是通的django-admin startproject myblog .执行完这条命令后当前目录下会生成一个manage.py文件和myblog配置目录。接下来启动开发服务器python manage.py runserver浏览器访问http://127.0.0.1:8000/如果看到 Django 默认的欢迎页面说明环境完全没问题。这个页面虽然只是静态欢迎页但它走完了“启动服务 → 处理请求 → 返回页面”的完整过程。3. 核心语法、配置与原理拆解在进入实战之前把 Django 最核心的几块知识点提前讲清楚。这样写项目的时候你就不是在“抄代码”而是理解每一行配置在做什么。3.1 URL 路由访问入口Django 的 URL 路由配置写在urls.py文件中。它的作用是把用户在浏览器里输入的网址映射到某个视图函数上。看一个最基础的配置# 文件路径myblog/urls.py from django.contrib import admin from django.urls import path urlpatterns [ path(admin/, admin.site.urls), ]这里path(admin/, admin.site.urls)的含义是当用户访问http://127.0.0.1:8000/admin/时交给 Django 自带的 Admin 后台处理。新手容易忽略的一个点是Django 匹配 URL 时是“从上到下”依次匹配的一旦匹配成功就不会继续向下匹配。所以如果你配置了path(, views.home)和path(post/, views.post)那么访问/post/时只会走第二个规则不会先匹配第一个规则。URL 里的int:post_id这种写法叫“路径参数”表示把 URL 中对应位置的值作为参数传给视图函数path(post/int:post_id/, views.post_detail, namepost_detail)访问/post/3/时Django 会调用views.post_detail(request, post_id3)。3.2 视图函数业务逻辑的地方视图函数是 Django 主线上最核心的一环。它接收两个重要信息一个是request对象包含用户请求的所有信息请求方式、参数、Cookie、Session 等另一个是 URL 路由传过来的参数。视图函数可以有两种编写风格函数视图直接用 Python 函数处理请求。from django.http import HttpResponse def home(request): return HttpResponse(Hello, Django!)类视图用类来组织逻辑适合处理“同一个 URL 需要支持 GET、POST 等多种请求方式”的场景。新手阶段先从函数视图开始理解起来更直观等接触了增删改查之后再慢慢迁移到类视图会自然体会到类视图的好处。视图函数的返回值通常有三种HttpResponse直接返回字符串内容render()渲染模板并返回 HTMLredirect()跳转到其他 URL。3.3 模型与 ORM操作数据库模型是 Django 操作数据库的入口。你在models.py中定义的每个类对应数据库中的一张表类中的属性对应表中的字段。# 文件路径blog/models.py from django.db import models class Post(models.Model): title models.CharField(max_length200) content models.TextField() created_at models.DateTimeField(auto_now_addTrue)上面这段代码定义了一个Post模型会自动生成一张表包含title、content、created_at三个字段。你不需要自己写建表 SQLDjango 的迁移工具会帮你完成。Django 的 ORM 强大之处在于你可以用 Python 代码完成大部分数据库操作# 新增数据 Post.objects.create(title第一篇, contenthello) # 查询数据 posts Post.objects.all() # 查所有 post Post.objects.get(id1) # 按 id 查单条不存在会报错 post Post.objects.filter(title第一篇) # 按条件过滤 # 修改数据 post Post.objects.get(id1) post.title 修改后的标题 post.save() # 删除数据 post Post.objects.get(id1) post.delete()需要注意get()和filter()的区别get()要求查询结果必须只有一条否则会抛出异常filter()返回一个查询集QuerySet即使没有结果也不会报错只是返回空集。删除对象这个操作在开发环境里很容易被忽视但在生产环境里非常危险。建议新手养成一个习惯删除前先用filter()查询确认数据范围再执行删除。比如批量删除时你应该清楚知道Post.objects.filter(content广告).delete()会删除所有满足条件的数据不要把filter()去掉写成Post.objects.all().delete()那会把整张表清空。3.4 模板数据如何变成页面模板是 Django 中负责展示的部分。它并不是普通的 HTML 文件而是 Django 的模板语言支持变量、循环、判断等逻辑。!-- 文件路径blog/templates/blog/post_list.html -- !DOCTYPE html html langzh-cn head meta charsetUTF-8 title文章列表/title /head body h1文章列表/h1 ul {% for post in posts %} li{{ post.title }} —— {{ post.created_at|date:Y-m-d }}/li {% empty %} li暂时没有文章/li {% endfor %} /ul /body /html模板中有两种标签{{ variable }}输出变量值。{% tag %}执行逻辑控制比如循环、判断。{{ post.created_at|date:Y-m-d }}这种写法叫过滤器作用是对变量做格式化处理。date过滤器把created_at时间对象格式化成字符串。模板文件放在哪里、叫什么名字虽然可以自己定义但 Django 有一个约定俗成的查找规则。通常每个 app 下会有一个templates目录Django 会自动去这个目录下找模板文件。为了防止不同 app 之间模板文件重名推荐在templates目录下再建一层以 app 名字命名的文件夹例如blog/templates/blog/post_list.html。3.5 Admin 后台免费的数据库管理界面Django 的 Admin 是新手最容易获得成就感的功能。只要你在admin.py中注册模型Django 就会自动生成一个后台管理界面可以在网页上对数据进行增删改查。# 文件路径blog/admin.py from django.contrib import admin from .models import Post admin.site.register(Post)注册之后访问/admin/用超级管理员账号登录就能看到Post数据表的列表、详情和编辑页面。对于企业内部系统这个功能几乎可以省掉一个前端管理后台的开发。3.6 数据迁移模型和数据库的同步机制当你修改了models.py中的模型定义数据库并不会自动同步而是需要执行两步操作# 1. 根据模型变化生成迁移文件 python manage.py makemigrations # 2. 把迁移文件应用到数据库 python manage.py migratemakemigrations像是生成一份“变更计划”migrate才是真正执行计划。新手经常犯的错误是修改了模型但忘记执行迁移结果页面报错“no such column”之类的错误。以后只要修改了模型就立刻执行这两步。4. 完整实战案例从零搭建一个文章管理网站下面通过一个完整的“文章管理”网站把上面所有知识点串起来。这个项目麻雀虽小但五脏俱全包含模型、视图、模板、URL 配置、Admin 后台和 ORM 操作。4.1 创建项目结构在第二步已经创建了项目myblog现在在项目中创建一个名为blog的 app。app 是 Django 中功能模块的划分方式一个项目可以有多个 app比如博客项目的blog、用户系统的users、评论系统的comments。python manage.py startapp blog创建完成后项目目录结构如下django_demo/ ├── manage.py ├── myblog/ │ ├── __init__.py │ ├── settings.py │ ├── urls.py │ └── wsgi.py └── blog/ ├── __init__.py ├── admin.py ├── apps.py ├── models.py ├── tests.py ├── urls.py └── views.pyblog目录是自动生成的但blog/urls.py目前不存在需要自己创建。这样做的目的是让blog这个 app 拥有自己独立的路由配置主项目只需要把它 include 进来即可。4.2 配置项目注册 app打开myblog/settings.py把blog加入INSTALLED_APPS# 文件路径myblog/settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, # 新增的 app blog, ]同时可以把语言和时区改成中文# 文件路径myblog/settings.py LANGUAGE_CODE zh-hans TIME_ZONE Asia/ShanghaiLANGUAGE_CODE zh-hans会让 Admin 后台显示中文界面TIME_ZONE Asia/Shanghai会让时间以北京时间显示。这两个配置在开发测试时非常实用。4.3 定义模型打开blog/models.py定义文章模型# 文件路径blog/models.py from django.db import models class Post(models.Model): title models.CharField(max_length200, verbose_name标题) content models.TextField(verbose_name内容) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) class Meta: verbose_name 文章 verbose_name_plural 文章 def __str__(self): return self.titleverbose_name是给字段起一个人类可读的名字会显示在 Admin 后台中。__str__方法让对象在后台列表里显示成标题文本而不是一串默认的对象名。4.4 生成并执行迁移修改完模型后立刻执行迁移python manage.py makemigrations blog python manage.py migrate执行makemigrations blog时Django 会在blog/migrations/目录下生成一个迁移文件。如果提示No changes detected说明模型定义和之前的迁移记录一致可能是你修改的字段名有误或者没有保存文件。4.5 注册 Admin 后台打开blog/admin.py注册模型# 文件路径blog/admin.py from django.contrib import admin from .models import Post admin.register(Post) class PostAdmin(admin.ModelAdmin): list_display [id, title, created_at]list_display指定后台列表中显示的字段。这样注册之后后台会显示文章 id、标题和创建时间三列比默认展示更直观。4.6 编写视图函数打开blog/views.py编写两个视图# 文件路径blog/views.py from django.shortcuts import render from .models import Post def post_list(request): 文章列表页展示所有文章 posts Post.objects.all().order_by(-created_at) return render(request, blog/post_list.html, {posts: posts}) def post_detail(request, post_id): 文章详情页展示单篇文章 post Post.objects.get(idpost_id) return render(request, blog/post_detail.html, {post: post})order_by(-created_at)表示按创建时间倒序排列最新的文章排在最前面。render()的第三个参数是一个字典里面的键就是模板中可以直接使用的变量名。注意post_detail中的Post.objects.get(idpost_id)是直接查询单条记录。如果数据库里没有这篇文章会抛出DoesNotExist异常。在开发教程中可以先用最简单的写法等理解了之后再引入错误处理。4.7 配置 app 路由先在blog目录下创建urls.py# 文件路径blog/urls.py需要手动创建 from django.urls import path from . import views app_name blog urlpatterns [ path(, views.post_list, namepost_list), path(post/int:post_id/, views.post_detail, namepost_detail), ]app_name blog是 URL 命名空间的配置。好处是将来在主项目里可以通过blog:post_detail这种带前缀的名字引用路由避免不同 app 之间 URL 重名。然后在主项目的myblog/urls.py中引入blog的路由# 文件路径myblog/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]这里path(, include(blog.urls))把根路径http://127.0.0.1:8000/下的所有 URL 交给blog.urls处理。如果你希望博客文章挂在/blog/下可以改成path(blog/, include(blog.urls))访问地址也会相应变化。4.8 创建模板文件在blog目录下创建templates/blog/文件夹然后创建两个模板文件。文章列表页!-- 文件路径blog/templates/blog/post_list.html -- !DOCTYPE html html langzh-cn head meta charsetUTF-8 title文章列表/title style body { font-family: Arial, sans-serif; max-width: 800px; margin: 40px auto; line-height: 1.6; } a { color: #0366d6; text-decoration: none; } a:hover { text-decoration: underline; } /style /head body h1文章列表/h1 ul {% for post in posts %} li a href{% url blog:post_detail post.id %}{{ post.title }}/a span{{ post.created_at|date:Y-m-d }}/span /li {% empty %} li还没有文章请先到后台添加。/li {% endfor %} /ul /body /html文章详情页!-- 文件路径blog/templates/blog/post_detail.html -- !DOCTYPE html html langzh-cn head meta charsetUTF-8 title{{ post.title }}/title style body { font-family: Arial, sans-serif; max-width: 800px; margin: 40px auto; line-height: 1.8; } .content { white-space: pre-wrap; } /style /head body h1{{ post.title }}/h1 p发布时间{{ post.created_at|date:Y-m-d H:i }}/p hr div classcontent{{ post.content }}/div pa href{% url blog:post_list %}返回列表/a/p /body /html模板中的{% url blog:post_detail post.id %}是 Django 的反向解析功能。它不会把 URL 地址写死而是根据路由配置自动生成链接。将来你修改了 URL 路径只要name不变模板里的链接就不需要改。4.9 创建超级管理员账号文章数据需要通过 Admin 后台录入所以先创建超级管理员账号python manage.py createsuperuser命令会依次提示你输入用户名、邮箱和密码。密码输入时不会显示内容这是终端的安全策略并不是键盘坏了正常输入即可。4.10 运行并验证启动开发服务器python manage.py runserver在浏览器中访问http://127.0.0.1:8000/看到文章列表页此时还是空列表。http://127.0.0.1:8000/admin/用刚才创建的超级管理员账号登录。在后台点击“文章”右侧的“增加”添加两条文章数据。回到http://127.0.0.1:8000/刷新页面就能看到文章列表。点击文章标题进入详情页URL 会变成类似http://127.0.0.1:8000/post/1/的形式页面显示标题、时间和正文内容。到这里你已经完整走过了 Django 的一条主线URL 路由 → 视图函数 → ORM 查询 → 模板渲染 → 浏览器展示。这个项目虽然简单但所有 Django 网站的基本骨架都是这样的。4.11 用 ORM 做一次删除操作练习文章列表页目前没有删除功能但可以用 Django 的 shell 环境来体验 ORM 删除操作。运行python manage.py shell在交互环境中执行from blog.models import Post # 查看当前所有文章 print(Post.objects.all()) # 删除 id 为指定值的文章先查询确认目标存在再删除 post Post.objects.filter(id1).first() if post: post.delete() print(删除成功) else: print(该文章不存在) # 退出 shell exit()在这个示例中filter(id1).first()是安全的写法。它不会在数据不存在时抛出异常而是返回None。相比直接使用get()这种写法更适合在删除前做“是否存在”的判断。再次强调在生产环境或真实项目中执行删除前务必用查询条件确认目标数据的范围。如果需要恢复数据必须在删除前做好备份或者使用“软删除”方案给模型增加一个is_deleted字段逻辑上隐藏而不是物理删除。5. 常见问题与排查思路5.1 启动报错No module named django这个报错几乎都是因为虚拟环境没有激活或者 Django 没装到当前环境里。排查步骤确认命令行前面有没有(venv)前缀。如果没有在项目目录下执行激活命令。重新执行pip install django。执行python -m django --version验证。5.2 页面 404提示 xxx not found开发环境下 404 通常集中在三个原因URL 路由没有匹配上。检查urls.py中的path()路径是否与浏览器访问的地址一致。URL 地址末尾的斜杠问题。Django 默认开启APPEND_SLASH访问/post/1时可能会自动跳转到/post/1/但如果你关闭了这个配置就会出现末尾少斜杠的 404。请求的是静态资源图片、CSS、JS但 URL 没有配置静态文件服务。开发环境下需要在settings.py中确认django.contrib.staticfiles已加入INSTALLED_APPS。5.3 修改模型后界面报错no such column这个报错的根本原因是你修改了models.py但数据库还没有同步新字段。解决方法是执行迁移命令python manage.py makemigrations python manage.py migrate如果执行makemigrations时提示检测不到变化检查模型文件是否保存以及是否在正确的 app 下修改了代码。5.4 Admin 后台没有显示中文确认settings.py中LANGUAGE_CODE的值。旧项目默认是en-us需要改为LANGUAGE_CODE zh-hans修改后刷新后台页面不需要重启服务器但浏览器可能需要清一下缓存。5.5 创建超级管理员时报错createsuperuser报错最常见的原因是密码太简单。Django 默认有密码强度校验密码长度不能少于 8 位且不能太接近用户名。开发环境想快速测试可以设置类似admin123456的密码。如果提示UNIQUE constraint failed: auth_user.username说明用户名已存在换一个用户名即可。5.6 在 Windows 上开发、部署到 Linux 服务器后出现问题本地 Windows 环境正常部署到 Linux 服务器后报错通常有三个原因依赖没有完整导出。本地项目里安装了大量 Python 库但服务器只装了 Django缺少其他依赖。应该执行pip freeze requirements.txt在服务器上执行pip install -r requirements.txt。数据库没有迁移。服务器上的数据库是全新的需要重新执行python manage.py migrate。路径分隔符不同。Windows 使用反斜杠\Linux 使用正斜杠/。代码中不要硬编码带盘符的绝对路径尽量使用 Django 提供的BASE_DIR来拼接路径。# 文件路径myblog/settings.py from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent5.7 常见问题汇总表问题现象常见原因解决思路提示 no module named django虚拟环境未激活或未安装依赖激活环境后重新 pip install django首页 404URL 路由配置不匹配检查 path() 的路径与 name 参数数据库操作报 no such column模型已修改但未迁移执行 makemigrations 和 migrateAdmin 后台是英文LANGUAGE_CODE 未修改改为 zh-hanscreatesuperuser 失败密码强度不足或用户名重复更换更复杂的密码或换用户名部署到 Linux 后报错依赖缺失或迁移未执行导出 requirements.txt重新 migrate6. 最佳实践与工程建议6.1 从第一天就使用虚拟环境这一点再怎么强调都不过分。不要因为“只是练手项目”就把 Django 装到全局环境否则当你有三四个项目时依赖冲突会让你非常痛苦。创建项目时的标准流程是先建目录再建虚拟环境再装 Django。6.2 把敏感配置与代码分离Django 项目的settings.py中有一项SECRET_KEY这是用于加密会话、签名数据的密钥。不要在 GitHub 等公开仓库中泄露它。即使只是个人项目也建议把SECRET_KEY、数据库密码等敏感信息放到环境变量或本地.env文件中读取。# 文件路径myblog/settings.py import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-insecure-key) DEBUG os.environ.get(DJANGO_DEBUG, True) True这样项目在本地开发时使用默认值在服务器上通过环境变量注入真实配置。6.3 生产环境必须关闭 DEBUGDjango 开发服务器在DEBUGTrue时会把完整的报错堆栈显示在页面上这非常方便调试但也非常危险。生产环境一旦开启 DEBUG访问者可以看到项目的目录结构、依赖版本甚至配置片段等于把攻击面直接暴露出去。部署上线时至少要检查两件事DEBUG设置为False。ALLOWED_HOSTS配置为允许访问的域名或 IP 列表不能留空。6.4 ORM 操作中的安全边界操作数据库时永远保持“最小影响范围”的意识更新或删除数据前先用filter()条件缩小影响范围。不要轻易使用Model.objects.all().delete()除非你确定要清空整张表。重要数据不要物理删除建议增加is_active或is_deleted字段做逻辑删除。多表操作涉及数据一致性时使用 Django 的事务控制。from django.db import transaction with transaction.atomic(): # 在这个代码块中执行的数据库操作要么全部成功要么全部回滚 post Post.objects.get(id1) post.title 新标题 post.save()transaction.atomic()是 Django 中最常用的事务写法。当一组操作中任何一步失败时之前已经执行的数据库变更会被回滚不会出现“只改了一半”的脏数据。6.5 命名规范与文件组织Django 对文件路径有自己的约定新手尽量不要反着来app 名称使用小写英文单词例如blog、users、orders。模型类名使用大写开头的驼峰命名例如Post、OrderItem。视图函数使用小写加下划线例如post_list、post_detail。模板文件放在app/templates/app/目录下避免不同 app 模板重名。保持这些规范的最大好处是别人接手你的项目时不需要额外学习你的目录结构Django 的经验可以直接迁移过来。6.6 日志记录初学者很容易只在代码里用print()输出调试信息但真实的线上项目需要系统化的日志。Django 的日志配置虽然看起来复杂但只需要一个基础配置就能覆盖大部分场景。建议在settings.py中配置一个简单的日志把运行信息写入文件# 文件路径myblog/settings.py LOGGING { version: 1, disable_existing_loggers: False, handlers: { file: { level: INFO, class: logging.FileHandler, filename: django.log, }, }, loggers: { django: { handlers: [file], level: INFO, propagate: True, }, }, }在代码中你可以用 Python 标准库的logging记录业务日志import logging logger logging.getLogger(__name__) def post_detail(request, post_id): try: post Post.objects.get(idpost_id) except Post.DoesNotExist: logger.warning(文章不存在id%s, post_id) return render(request, blog/404.html, status404) return render(request, blog/post_detail.html, {post: post})6.7 从开发到部署的升级路径本文的项目只能用于学习和本地开发。如果要部署到真实的服务器你还需要补齐以下内容用 Gunicorn 或 uWSGI 运行 Django 应用而不是使用runserver。用 Nginx 做反向代理和静态文件服务。把数据库从默认的 SQLite 切换到 PostgreSQL 或 MySQL。使用 Docker 打包应用统一开发环境和部署环境。配置 HTTPS 证书。定期备份数据库。这些内容不需要在第一天全部学会但它们是你学会 Django 基础之后自然要走的下一步。保留一个印象等真正需要部署时再逐个了解即可。7. 总结与学习路线回到文章开头提出的问题学 Django 到底应该抓住哪条主线答案就是用户请求 → URL 路由 → 视图函数 → 模型ORM→ 模板 → 浏览器响应。围绕这条主线你已经完成了环境搭建、项目创建、模型迁移、Admin 配置、视图编写、模板渲染、ORM 删除操作这些基础动作。以后学新功能时你只需要问自己它在这条主线的哪个位置是给路由加新地址还是给模型加新字段还是给视图加新逻辑这样就不会再迷路。下一步的推荐学习顺序是表单处理学习 Django Form 和 ModelForm让用户可以在网页上提交数据。用户认证学习 Django 自带的登录、注册、权限控制。类视图熟悉ListView、DetailView等通用视图减少重复代码。数据库扩展把 SQLite 切换为真实的数据库理解配置差异。Django REST Framework学习写接口前后端分离开发。在这个过程中优先学会看报错信息。Django 的报错提示在众多 Web 框架中算是非常友好的它通常会告诉你错误出现在哪个文件、哪一行、以及可能的原因。很多人卡住不动是因为看到英文报错就慌其实只要把报错信息复制到搜索引擎大多数都能找到答案。最后送你一个建议不要试图一次性背下 Django 的所有 API也不需要把官方文档从头读到尾。先把今天这个小项目亲手跑通然后在它的基础上不断加功能——加一个翻页、加一个搜索框、加一个评论功能。每加一个功能你对这条主线的理解就会深一层。动手永远比看教程快。 从请求到响应：Django MTV架构核心流程与实战入门
刚开始学 Django 的时候我最大的感受不是“难”而是“乱”。网上的教程一会儿讲模型一会儿讲视图一会儿又来一个第三方库每个知识点单看都能懂但拼在一起就不知道项目到底是怎么跑起来的。如果你也有这种感觉说明缺的不是代码量而是一条能串起所有知识点的主线。这篇文章不打算把 Django 的每个功能都讲一遍而是围绕一条主线来写一次浏览器请求进入 Django 后是如何经过 URL 路由、视图函数、模型和模板最终把页面返回给用户的。抓住这条主线你就知道学 Django 应该先学什么、后学什么遇到报错时该去哪个环节查也能用最小的成本完成第一个能跑通的 Django 网站。本文适合完全没接触过 Django 的 Python 新手也适合学过一点但总是“学了就忘”的开发者。全文包含环境搭建、核心概念、可运行的完整项目、常见报错排查以及工程实践建议代码都可以直接复制使用。1. 背景与核心概念1.1 Django 是什么解决什么问题Django 是一个用 Python 编写的开源 Web 框架诞生于新闻网站的业务环境所以它从第一天起就在考虑三个问题快速迭代、多人协作、高并发下的稳定性。翻译成开发者的语言就是你不需要重复造轮子它已经帮你把网站开发中最常用、最繁琐的部分都准备好了。具体来说Django 自带的东西包括URL 路由系统把用户访问的网址映射到对应的处理函数。ORM对象关系映射用 Python 代码操作数据库不需要手写大量 SQL。模板引擎把数据渲染成 HTML 页面。Admin 后台自动生成一个可以管理数据的后台界面。表单处理、认证、会话、中间件覆盖 Web 开发的常见需求。所以 Django 常被称为“全家桶”式框架。它可能不如 Flask 那样轻量灵活但好处是你不需要为选哪个数据库库、哪个模板引擎、哪个表单库而纠结框架已经帮你做好了一致性的选择。1.2 Django 在国内的使用情况很多新手会犹豫学了 Django 在国内有用吗从实际招聘和技术社区反馈来看Python 后端岗位中 Django 和 Flask 是出现频率最高的两个 Web 框架。Django 尤其适合快速搭建内容型网站、企业内部管理系统、自动化运维平台、数据可视化后台这类项目。因为这些系统往往需要一个稳定的 Admin 后台而 Django 自带的 Admin 几乎可以零成本承接这个需求。另一个被低估的场景是个人项目和自动化工具。很多人用 Python 写脚本处理数据、跑爬虫、做自动化但脚本一多就没法管理这时候把脚本包装成一个 Django 项目用 Web 页面去触发和展示结果会让整个系统的可用性和维护性提升一大截。当然Django 的学习曲线相比 Flask 会稍微陡峭一点。问题不在于语法难而在于知识点多新手容易迷失。解决这个问题的最好办法就是先围绕一条主线跑通一个最小项目之后再逐步拓宽。1.3 抓住学习主线一次请求的完整旅程Django 开发并不要求你一次性掌握所有组件你只需要先理解下面这条主线浏览器输入网址 ↓ Django 的 URL 路由找到对应的视图函数 ↓ 视图函数处理业务逻辑如果需要数据就通过 ORM 操作数据库 ↓ 视图函数把数据交给模板渲染成 HTML ↓ 浏览器收到 HTML 页面并展示这条主线就是 Django 的MTV 架构Model-Template-View模型-模板-视图的运行流程Model模型负责和数据库打交道对应数据库中的表。Template模板负责页面展示是 HTML 文件中可以动态填充数据的部分。View视图负责业务逻辑相当于 Model 和 Template 之间的桥梁。很多教程会强调 MTV 和 MVC 的区别但新手阶段你只需要知道用户请求先去找 ViewView 需要数据时找 Model需要展示时找 Template。后面所有学习内容都可以挂在这条主线上。2. 环境准备与版本说明2.1 需要准备的工具在开始写代码之前先把环境准备好。Django 是 Python 的第三方库所以最基础的要求是电脑上已经安装了 Python 3。工具说明Python 3建议使用 Python 3.8 及以上版本Django 新版本对 Python 版本有要求pipPython 自带的包管理工具用来安装 DjangovenvPython 自带的虚拟环境模块用来隔离项目依赖IDE推荐 PyCharm 或 VS Code初学者用 VS Code 更轻量浏览器Chrome、Edge 均可用于访问开发服务器页面这篇文章以 Django 当前常见的 LTS 版本为例这类版本维护周期长、资料多、踩坑少。你不需要纠结具体版本安装时优先选择 LTS 版本或者最新稳定版即可。2.2 虚拟环境与安装步骤为什么一定要用虚拟环境因为不同项目的 Python 库版本可能互相冲突。比如项目 A 需要 Django 3.2项目 B 需要 Django 4.2如果全部装在系统全局环境里就会互相覆盖。虚拟环境相当于给每个项目一个独立的“沙盒”。下面是在 Windows 和 macOS/Linux 上通用的命令行操作# 1. 创建项目目录并进入目录 mkdir django_demo cd django_demo # 2. 创建虚拟环境 python -m venv venv # 3. 激活虚拟环境 # Windows 下执行 venv\Scripts\activate # macOS / Linux 下执行 source venv/bin/activate # 4. 安装 Django pip install django # 5. 验证安装结果 python -m django --version激活虚拟环境后命令行前面通常会出现(venv)前缀说明你当前已经处于虚拟环境中安装的库只会影响这个项目。如果你执行python -m django --version能看到版本号输出说明 Django 已经安装成功。如果提示找不到模块通常有两种原因一是虚拟环境没有激活二是 pip 安装过程有问题。此时可以重新激活环境再执行一次安装命令。2.3 创建一个最小项目验证环境安装成功后先不要急着写代码用 Django 提供的命令创建一个空项目确认整个链路是通的django-admin startproject myblog .执行完这条命令后当前目录下会生成一个manage.py文件和myblog配置目录。接下来启动开发服务器python manage.py runserver浏览器访问http://127.0.0.1:8000/如果看到 Django 默认的欢迎页面说明环境完全没问题。这个页面虽然只是静态欢迎页但它走完了“启动服务 → 处理请求 → 返回页面”的完整过程。3. 核心语法、配置与原理拆解在进入实战之前把 Django 最核心的几块知识点提前讲清楚。这样写项目的时候你就不是在“抄代码”而是理解每一行配置在做什么。3.1 URL 路由访问入口Django 的 URL 路由配置写在urls.py文件中。它的作用是把用户在浏览器里输入的网址映射到某个视图函数上。看一个最基础的配置# 文件路径myblog/urls.py from django.contrib import admin from django.urls import path urlpatterns [ path(admin/, admin.site.urls), ]这里path(admin/, admin.site.urls)的含义是当用户访问http://127.0.0.1:8000/admin/时交给 Django 自带的 Admin 后台处理。新手容易忽略的一个点是Django 匹配 URL 时是“从上到下”依次匹配的一旦匹配成功就不会继续向下匹配。所以如果你配置了path(, views.home)和path(post/, views.post)那么访问/post/时只会走第二个规则不会先匹配第一个规则。URL 里的int:post_id这种写法叫“路径参数”表示把 URL 中对应位置的值作为参数传给视图函数path(post/int:post_id/, views.post_detail, namepost_detail)访问/post/3/时Django 会调用views.post_detail(request, post_id3)。3.2 视图函数业务逻辑的地方视图函数是 Django 主线上最核心的一环。它接收两个重要信息一个是request对象包含用户请求的所有信息请求方式、参数、Cookie、Session 等另一个是 URL 路由传过来的参数。视图函数可以有两种编写风格函数视图直接用 Python 函数处理请求。from django.http import HttpResponse def home(request): return HttpResponse(Hello, Django!)类视图用类来组织逻辑适合处理“同一个 URL 需要支持 GET、POST 等多种请求方式”的场景。新手阶段先从函数视图开始理解起来更直观等接触了增删改查之后再慢慢迁移到类视图会自然体会到类视图的好处。视图函数的返回值通常有三种HttpResponse直接返回字符串内容render()渲染模板并返回 HTMLredirect()跳转到其他 URL。3.3 模型与 ORM操作数据库模型是 Django 操作数据库的入口。你在models.py中定义的每个类对应数据库中的一张表类中的属性对应表中的字段。# 文件路径blog/models.py from django.db import models class Post(models.Model): title models.CharField(max_length200) content models.TextField() created_at models.DateTimeField(auto_now_addTrue)上面这段代码定义了一个Post模型会自动生成一张表包含title、content、created_at三个字段。你不需要自己写建表 SQLDjango 的迁移工具会帮你完成。Django 的 ORM 强大之处在于你可以用 Python 代码完成大部分数据库操作# 新增数据 Post.objects.create(title第一篇, contenthello) # 查询数据 posts Post.objects.all() # 查所有 post Post.objects.get(id1) # 按 id 查单条不存在会报错 post Post.objects.filter(title第一篇) # 按条件过滤 # 修改数据 post Post.objects.get(id1) post.title 修改后的标题 post.save() # 删除数据 post Post.objects.get(id1) post.delete()需要注意get()和filter()的区别get()要求查询结果必须只有一条否则会抛出异常filter()返回一个查询集QuerySet即使没有结果也不会报错只是返回空集。删除对象这个操作在开发环境里很容易被忽视但在生产环境里非常危险。建议新手养成一个习惯删除前先用filter()查询确认数据范围再执行删除。比如批量删除时你应该清楚知道Post.objects.filter(content广告).delete()会删除所有满足条件的数据不要把filter()去掉写成Post.objects.all().delete()那会把整张表清空。3.4 模板数据如何变成页面模板是 Django 中负责展示的部分。它并不是普通的 HTML 文件而是 Django 的模板语言支持变量、循环、判断等逻辑。!-- 文件路径blog/templates/blog/post_list.html -- !DOCTYPE html html langzh-cn head meta charsetUTF-8 title文章列表/title /head body h1文章列表/h1 ul {% for post in posts %} li{{ post.title }} —— {{ post.created_at|date:Y-m-d }}/li {% empty %} li暂时没有文章/li {% endfor %} /ul /body /html模板中有两种标签{{ variable }}输出变量值。{% tag %}执行逻辑控制比如循环、判断。{{ post.created_at|date:Y-m-d }}这种写法叫过滤器作用是对变量做格式化处理。date过滤器把created_at时间对象格式化成字符串。模板文件放在哪里、叫什么名字虽然可以自己定义但 Django 有一个约定俗成的查找规则。通常每个 app 下会有一个templates目录Django 会自动去这个目录下找模板文件。为了防止不同 app 之间模板文件重名推荐在templates目录下再建一层以 app 名字命名的文件夹例如blog/templates/blog/post_list.html。3.5 Admin 后台免费的数据库管理界面Django 的 Admin 是新手最容易获得成就感的功能。只要你在admin.py中注册模型Django 就会自动生成一个后台管理界面可以在网页上对数据进行增删改查。# 文件路径blog/admin.py from django.contrib import admin from .models import Post admin.site.register(Post)注册之后访问/admin/用超级管理员账号登录就能看到Post数据表的列表、详情和编辑页面。对于企业内部系统这个功能几乎可以省掉一个前端管理后台的开发。3.6 数据迁移模型和数据库的同步机制当你修改了models.py中的模型定义数据库并不会自动同步而是需要执行两步操作# 1. 根据模型变化生成迁移文件 python manage.py makemigrations # 2. 把迁移文件应用到数据库 python manage.py migratemakemigrations像是生成一份“变更计划”migrate才是真正执行计划。新手经常犯的错误是修改了模型但忘记执行迁移结果页面报错“no such column”之类的错误。以后只要修改了模型就立刻执行这两步。4. 完整实战案例从零搭建一个文章管理网站下面通过一个完整的“文章管理”网站把上面所有知识点串起来。这个项目麻雀虽小但五脏俱全包含模型、视图、模板、URL 配置、Admin 后台和 ORM 操作。4.1 创建项目结构在第二步已经创建了项目myblog现在在项目中创建一个名为blog的 app。app 是 Django 中功能模块的划分方式一个项目可以有多个 app比如博客项目的blog、用户系统的users、评论系统的comments。python manage.py startapp blog创建完成后项目目录结构如下django_demo/ ├── manage.py ├── myblog/ │ ├── __init__.py │ ├── settings.py │ ├── urls.py │ └── wsgi.py └── blog/ ├── __init__.py ├── admin.py ├── apps.py ├── models.py ├── tests.py ├── urls.py └── views.pyblog目录是自动生成的但blog/urls.py目前不存在需要自己创建。这样做的目的是让blog这个 app 拥有自己独立的路由配置主项目只需要把它 include 进来即可。4.2 配置项目注册 app打开myblog/settings.py把blog加入INSTALLED_APPS# 文件路径myblog/settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, # 新增的 app blog, ]同时可以把语言和时区改成中文# 文件路径myblog/settings.py LANGUAGE_CODE zh-hans TIME_ZONE Asia/ShanghaiLANGUAGE_CODE zh-hans会让 Admin 后台显示中文界面TIME_ZONE Asia/Shanghai会让时间以北京时间显示。这两个配置在开发测试时非常实用。4.3 定义模型打开blog/models.py定义文章模型# 文件路径blog/models.py from django.db import models class Post(models.Model): title models.CharField(max_length200, verbose_name标题) content models.TextField(verbose_name内容) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) class Meta: verbose_name 文章 verbose_name_plural 文章 def __str__(self): return self.titleverbose_name是给字段起一个人类可读的名字会显示在 Admin 后台中。__str__方法让对象在后台列表里显示成标题文本而不是一串默认的对象名。4.4 生成并执行迁移修改完模型后立刻执行迁移python manage.py makemigrations blog python manage.py migrate执行makemigrations blog时Django 会在blog/migrations/目录下生成一个迁移文件。如果提示No changes detected说明模型定义和之前的迁移记录一致可能是你修改的字段名有误或者没有保存文件。4.5 注册 Admin 后台打开blog/admin.py注册模型# 文件路径blog/admin.py from django.contrib import admin from .models import Post admin.register(Post) class PostAdmin(admin.ModelAdmin): list_display [id, title, created_at]list_display指定后台列表中显示的字段。这样注册之后后台会显示文章 id、标题和创建时间三列比默认展示更直观。4.6 编写视图函数打开blog/views.py编写两个视图# 文件路径blog/views.py from django.shortcuts import render from .models import Post def post_list(request): 文章列表页展示所有文章 posts Post.objects.all().order_by(-created_at) return render(request, blog/post_list.html, {posts: posts}) def post_detail(request, post_id): 文章详情页展示单篇文章 post Post.objects.get(idpost_id) return render(request, blog/post_detail.html, {post: post})order_by(-created_at)表示按创建时间倒序排列最新的文章排在最前面。render()的第三个参数是一个字典里面的键就是模板中可以直接使用的变量名。注意post_detail中的Post.objects.get(idpost_id)是直接查询单条记录。如果数据库里没有这篇文章会抛出DoesNotExist异常。在开发教程中可以先用最简单的写法等理解了之后再引入错误处理。4.7 配置 app 路由先在blog目录下创建urls.py# 文件路径blog/urls.py需要手动创建 from django.urls import path from . import views app_name blog urlpatterns [ path(, views.post_list, namepost_list), path(post/int:post_id/, views.post_detail, namepost_detail), ]app_name blog是 URL 命名空间的配置。好处是将来在主项目里可以通过blog:post_detail这种带前缀的名字引用路由避免不同 app 之间 URL 重名。然后在主项目的myblog/urls.py中引入blog的路由# 文件路径myblog/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]这里path(, include(blog.urls))把根路径http://127.0.0.1:8000/下的所有 URL 交给blog.urls处理。如果你希望博客文章挂在/blog/下可以改成path(blog/, include(blog.urls))访问地址也会相应变化。4.8 创建模板文件在blog目录下创建templates/blog/文件夹然后创建两个模板文件。文章列表页!-- 文件路径blog/templates/blog/post_list.html -- !DOCTYPE html html langzh-cn head meta charsetUTF-8 title文章列表/title style body { font-family: Arial, sans-serif; max-width: 800px; margin: 40px auto; line-height: 1.6; } a { color: #0366d6; text-decoration: none; } a:hover { text-decoration: underline; } /style /head body h1文章列表/h1 ul {% for post in posts %} li a href{% url blog:post_detail post.id %}{{ post.title }}/a span{{ post.created_at|date:Y-m-d }}/span /li {% empty %} li还没有文章请先到后台添加。/li {% endfor %} /ul /body /html文章详情页!-- 文件路径blog/templates/blog/post_detail.html -- !DOCTYPE html html langzh-cn head meta charsetUTF-8 title{{ post.title }}/title style body { font-family: Arial, sans-serif; max-width: 800px; margin: 40px auto; line-height: 1.8; } .content { white-space: pre-wrap; } /style /head body h1{{ post.title }}/h1 p发布时间{{ post.created_at|date:Y-m-d H:i }}/p hr div classcontent{{ post.content }}/div pa href{% url blog:post_list %}返回列表/a/p /body /html模板中的{% url blog:post_detail post.id %}是 Django 的反向解析功能。它不会把 URL 地址写死而是根据路由配置自动生成链接。将来你修改了 URL 路径只要name不变模板里的链接就不需要改。4.9 创建超级管理员账号文章数据需要通过 Admin 后台录入所以先创建超级管理员账号python manage.py createsuperuser命令会依次提示你输入用户名、邮箱和密码。密码输入时不会显示内容这是终端的安全策略并不是键盘坏了正常输入即可。4.10 运行并验证启动开发服务器python manage.py runserver在浏览器中访问http://127.0.0.1:8000/看到文章列表页此时还是空列表。http://127.0.0.1:8000/admin/用刚才创建的超级管理员账号登录。在后台点击“文章”右侧的“增加”添加两条文章数据。回到http://127.0.0.1:8000/刷新页面就能看到文章列表。点击文章标题进入详情页URL 会变成类似http://127.0.0.1:8000/post/1/的形式页面显示标题、时间和正文内容。到这里你已经完整走过了 Django 的一条主线URL 路由 → 视图函数 → ORM 查询 → 模板渲染 → 浏览器展示。这个项目虽然简单但所有 Django 网站的基本骨架都是这样的。4.11 用 ORM 做一次删除操作练习文章列表页目前没有删除功能但可以用 Django 的 shell 环境来体验 ORM 删除操作。运行python manage.py shell在交互环境中执行from blog.models import Post # 查看当前所有文章 print(Post.objects.all()) # 删除 id 为指定值的文章先查询确认目标存在再删除 post Post.objects.filter(id1).first() if post: post.delete() print(删除成功) else: print(该文章不存在) # 退出 shell exit()在这个示例中filter(id1).first()是安全的写法。它不会在数据不存在时抛出异常而是返回None。相比直接使用get()这种写法更适合在删除前做“是否存在”的判断。再次强调在生产环境或真实项目中执行删除前务必用查询条件确认目标数据的范围。如果需要恢复数据必须在删除前做好备份或者使用“软删除”方案给模型增加一个is_deleted字段逻辑上隐藏而不是物理删除。5. 常见问题与排查思路5.1 启动报错No module named django这个报错几乎都是因为虚拟环境没有激活或者 Django 没装到当前环境里。排查步骤确认命令行前面有没有(venv)前缀。如果没有在项目目录下执行激活命令。重新执行pip install django。执行python -m django --version验证。5.2 页面 404提示 xxx not found开发环境下 404 通常集中在三个原因URL 路由没有匹配上。检查urls.py中的path()路径是否与浏览器访问的地址一致。URL 地址末尾的斜杠问题。Django 默认开启APPEND_SLASH访问/post/1时可能会自动跳转到/post/1/但如果你关闭了这个配置就会出现末尾少斜杠的 404。请求的是静态资源图片、CSS、JS但 URL 没有配置静态文件服务。开发环境下需要在settings.py中确认django.contrib.staticfiles已加入INSTALLED_APPS。5.3 修改模型后界面报错no such column这个报错的根本原因是你修改了models.py但数据库还没有同步新字段。解决方法是执行迁移命令python manage.py makemigrations python manage.py migrate如果执行makemigrations时提示检测不到变化检查模型文件是否保存以及是否在正确的 app 下修改了代码。5.4 Admin 后台没有显示中文确认settings.py中LANGUAGE_CODE的值。旧项目默认是en-us需要改为LANGUAGE_CODE zh-hans修改后刷新后台页面不需要重启服务器但浏览器可能需要清一下缓存。5.5 创建超级管理员时报错createsuperuser报错最常见的原因是密码太简单。Django 默认有密码强度校验密码长度不能少于 8 位且不能太接近用户名。开发环境想快速测试可以设置类似admin123456的密码。如果提示UNIQUE constraint failed: auth_user.username说明用户名已存在换一个用户名即可。5.6 在 Windows 上开发、部署到 Linux 服务器后出现问题本地 Windows 环境正常部署到 Linux 服务器后报错通常有三个原因依赖没有完整导出。本地项目里安装了大量 Python 库但服务器只装了 Django缺少其他依赖。应该执行pip freeze requirements.txt在服务器上执行pip install -r requirements.txt。数据库没有迁移。服务器上的数据库是全新的需要重新执行python manage.py migrate。路径分隔符不同。Windows 使用反斜杠\Linux 使用正斜杠/。代码中不要硬编码带盘符的绝对路径尽量使用 Django 提供的BASE_DIR来拼接路径。# 文件路径myblog/settings.py from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent5.7 常见问题汇总表问题现象常见原因解决思路提示 no module named django虚拟环境未激活或未安装依赖激活环境后重新 pip install django首页 404URL 路由配置不匹配检查 path() 的路径与 name 参数数据库操作报 no such column模型已修改但未迁移执行 makemigrations 和 migrateAdmin 后台是英文LANGUAGE_CODE 未修改改为 zh-hanscreatesuperuser 失败密码强度不足或用户名重复更换更复杂的密码或换用户名部署到 Linux 后报错依赖缺失或迁移未执行导出 requirements.txt重新 migrate6. 最佳实践与工程建议6.1 从第一天就使用虚拟环境这一点再怎么强调都不过分。不要因为“只是练手项目”就把 Django 装到全局环境否则当你有三四个项目时依赖冲突会让你非常痛苦。创建项目时的标准流程是先建目录再建虚拟环境再装 Django。6.2 把敏感配置与代码分离Django 项目的settings.py中有一项SECRET_KEY这是用于加密会话、签名数据的密钥。不要在 GitHub 等公开仓库中泄露它。即使只是个人项目也建议把SECRET_KEY、数据库密码等敏感信息放到环境变量或本地.env文件中读取。# 文件路径myblog/settings.py import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-insecure-key) DEBUG os.environ.get(DJANGO_DEBUG, True) True这样项目在本地开发时使用默认值在服务器上通过环境变量注入真实配置。6.3 生产环境必须关闭 DEBUGDjango 开发服务器在DEBUGTrue时会把完整的报错堆栈显示在页面上这非常方便调试但也非常危险。生产环境一旦开启 DEBUG访问者可以看到项目的目录结构、依赖版本甚至配置片段等于把攻击面直接暴露出去。部署上线时至少要检查两件事DEBUG设置为False。ALLOWED_HOSTS配置为允许访问的域名或 IP 列表不能留空。6.4 ORM 操作中的安全边界操作数据库时永远保持“最小影响范围”的意识更新或删除数据前先用filter()条件缩小影响范围。不要轻易使用Model.objects.all().delete()除非你确定要清空整张表。重要数据不要物理删除建议增加is_active或is_deleted字段做逻辑删除。多表操作涉及数据一致性时使用 Django 的事务控制。from django.db import transaction with transaction.atomic(): # 在这个代码块中执行的数据库操作要么全部成功要么全部回滚 post Post.objects.get(id1) post.title 新标题 post.save()transaction.atomic()是 Django 中最常用的事务写法。当一组操作中任何一步失败时之前已经执行的数据库变更会被回滚不会出现“只改了一半”的脏数据。6.5 命名规范与文件组织Django 对文件路径有自己的约定新手尽量不要反着来app 名称使用小写英文单词例如blog、users、orders。模型类名使用大写开头的驼峰命名例如Post、OrderItem。视图函数使用小写加下划线例如post_list、post_detail。模板文件放在app/templates/app/目录下避免不同 app 模板重名。保持这些规范的最大好处是别人接手你的项目时不需要额外学习你的目录结构Django 的经验可以直接迁移过来。6.6 日志记录初学者很容易只在代码里用print()输出调试信息但真实的线上项目需要系统化的日志。Django 的日志配置虽然看起来复杂但只需要一个基础配置就能覆盖大部分场景。建议在settings.py中配置一个简单的日志把运行信息写入文件# 文件路径myblog/settings.py LOGGING { version: 1, disable_existing_loggers: False, handlers: { file: { level: INFO, class: logging.FileHandler, filename: django.log, }, }, loggers: { django: { handlers: [file], level: INFO, propagate: True, }, }, }在代码中你可以用 Python 标准库的logging记录业务日志import logging logger logging.getLogger(__name__) def post_detail(request, post_id): try: post Post.objects.get(idpost_id) except Post.DoesNotExist: logger.warning(文章不存在id%s, post_id) return render(request, blog/404.html, status404) return render(request, blog/post_detail.html, {post: post})6.7 从开发到部署的升级路径本文的项目只能用于学习和本地开发。如果要部署到真实的服务器你还需要补齐以下内容用 Gunicorn 或 uWSGI 运行 Django 应用而不是使用runserver。用 Nginx 做反向代理和静态文件服务。把数据库从默认的 SQLite 切换到 PostgreSQL 或 MySQL。使用 Docker 打包应用统一开发环境和部署环境。配置 HTTPS 证书。定期备份数据库。这些内容不需要在第一天全部学会但它们是你学会 Django 基础之后自然要走的下一步。保留一个印象等真正需要部署时再逐个了解即可。7. 总结与学习路线回到文章开头提出的问题学 Django 到底应该抓住哪条主线答案就是用户请求 → URL 路由 → 视图函数 → 模型ORM→ 模板 → 浏览器响应。围绕这条主线你已经完成了环境搭建、项目创建、模型迁移、Admin 配置、视图编写、模板渲染、ORM 删除操作这些基础动作。以后学新功能时你只需要问自己它在这条主线的哪个位置是给路由加新地址还是给模型加新字段还是给视图加新逻辑这样就不会再迷路。下一步的推荐学习顺序是表单处理学习 Django Form 和 ModelForm让用户可以在网页上提交数据。用户认证学习 Django 自带的登录、注册、权限控制。类视图熟悉ListView、DetailView等通用视图减少重复代码。数据库扩展把 SQLite 切换为真实的数据库理解配置差异。Django REST Framework学习写接口前后端分离开发。在这个过程中优先学会看报错信息。Django 的报错提示在众多 Web 框架中算是非常友好的它通常会告诉你错误出现在哪个文件、哪一行、以及可能的原因。很多人卡住不动是因为看到英文报错就慌其实只要把报错信息复制到搜索引擎大多数都能找到答案。最后送你一个建议不要试图一次性背下 Django 的所有 API也不需要把官方文档从头读到尾。先把今天这个小项目亲手跑通然后在它的基础上不断加功能——加一个翻页、加一个搜索框、加一个评论功能。每加一个功能你对这条主线的理解就会深一层。动手永远比看教程快。