Django 4.0官方中文文档实战：从项目骨架到ORM与避坑指南-北京尧图网络

简介Django 4.0 官方中文文档离线包专为 Python Web 开发者提供一套可随时查阅的权威参考适合刚入门的新手学习者也适合有经验者离线检索知识细节。压缩包共 1144 个文件正文主体为 547 个 HTML 页面另有 531 个文本页面以及样式表、JavaScript 脚本、SVG 图标和字体等配套资源整体仅 6.83MB目录结构清晰便于本地导航与站内搜索。目前已有 2619 人学习/下载。内容覆盖快速环境搭建、模型与 ORM 设计、视图与 URL 路由、模板语法、表单处理、中间件机制、国际化与本地化、自动化测试、安全防护及性能优化等关键主题并贯穿项目创建、数据库配置到部署上线的完整流程既是官方文档的中文镜像也可作为日常开发中随手查阅的知识手册帮助读者按模块循序渐进掌握 Django 4.0尤其适合需要系统学习或离线查阅的团队和个人能有效减少网络检索成本、提升学习效率。1. 切入 Django 4.0官方中文文档为什么值得从头啃如果你也是靠搜索引擎碎片化学习 Django 的多半经历过这种循环片段代码能跑换个环境就报错教程里还是 2.x 写法装了 4.0 全变红标。我当年接内部管理系统想用 django python 快速交付结果 URL 写法反复改两版才把 django4.0 官方中文文档从头啃完。这份文档当学习材料比当字典好环境、项目骨架、模型、视图、模板、表单、部署一条线讲全一个环节都没跳过。适合两类人——零基础想系统学 Django 的和被旧版升级反复摩擦的。2. 把项目跑起来从文档快速入门章节拆出的项目骨架2.1 先搞懂“项目和应用”的边界Django 文档在快速入门章节就反复强调 project项目和 app应用的边界。很多人以为两者画等号理解错之后后面组织代码全乱。官方定义很明确项目是配置集合承载 settings、根 URL 配置、WSGI/ASGI 入口应用是可复用的业务模块。一个项目挂多个应用一个应用原则上也能拆到第二个项目里复用。实操层面我开局会严格按文档推荐的骨架来用 django-admin startproject 建项目再用 python manage.py startapp 建应用。有人图省事直接手写目录结果 settings.py 找不对路径models.py 不会被自动导入。手写不是不行但你不清楚生成的默认文件缺了什么排错效率会低很多。# 建项目点号表示当前目录就是项目根 django-admin startproject config . # 在项目根目录下建应用 python manage.py startapp blog第一条命令末尾的点号是容易被忽略的小细节。有它项目配置文件直接进当前目录不会再多套一层同名目录。没它启动时会发现路径不对manage.py 里的 DJANGO_SETTINGS_MODULE 要改成 config.config.settings 这种别扭写法。startapp 生成的默认文件里apps.py 和 admin.py 是 4.0 的标配旧版教程没有 admin.py 的自动生成手动补总是容易漏掉注册步骤。生成后的目录结构大概是config/ settings.py urls.py wsgi.py asgi.py manage.py blog/ models.py views.py admin.py apps.py migrations/manage.py 是项目的操作入口不是应用的。任何时候执行管理命令都要待在 manage.py 所在目录或者用完整相对路径去指它。文档里的命令示例默认你就在这个目录下照做就行。2.2 settings.py 默认配置哪些要动哪些别碰打开 settings.py满屏配置项看着多实际需要主动修改的就几处。最核心的是 INSTALLED_APPS新建的应用必须在这里登记Django 才知道加载它的模型、迁移和管理后台。INSTALLED_APPS [ # 框架自带 django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, # 第三方应用 # 自建应用 blog, ]登记顺序多数时候没有严格约束。不过用 DRF 这类框架时第三方应用放自带应用之后、自建应用之前按文档推荐顺序区分更容易维护。自建应用之间有模型依赖时被依赖的排在前面。迁移执行时会按 INSTALLED_APPS 顺序去找依赖这个习惯能少碰边界情况。DATABASES 默认是 SQLite 的配置开发阶段别急着换生产库。文档数据库章节写得很明确SQLite 适合原型验证生产环境再考虑 PostgreSQL 或 MySQL。切换时要改 ENGINE、NAME、USER、PASSWORD、HOST 这些键但别在早期自己手搓连接串先用环境变量管理密码不要把明文写进 settings.py。LANGUAGE_CODE 默认 en-us改成 zh-hans 可以让 Django 后台界面变中文前提是项目里有对应的 locale 编译文件。网上有教程说改这个就完了其实没编译翻译文件时还是回退英文。TIME_ZONE 和 USE_TZ 是时区坑的主角后面避坑章节细讲这里只提醒一句默认值覆盖多数场景别乱动。2.3 URL 分发从 2.x 到 4.0 变化的重点URL 路由是请求进门的第一个关卡。Django 4.0 文档明确废除了 url() 函数全部改用 path() 和 re_path()。如果你搜到的教程还在写 from django.conf.urls import url基本可以判断是 2.x 时代的产物直接忽略。path() 的第一个参数是路由模式第二个参数是视图函数或 include() 结果name 参数用来做反向解析。from django.urls import path, include from blog import views urlpatterns [ path(admin/, admin.site.urls), path(, views.index, nameindex), path(article/int:pk/, views.article_detail, namearticle_detail), path(blog/, include(blog.urls)), ]转换器int:pk是 4.0 里最常用的路径参数写法它把 URL 对应片段转成整数传给视图函数。文档里列了 int、str、slug、uuid、path 几种内置转换器各自对应不同匹配规则。遇到不匹配的需求自己写一个转换器类实现 to_python 和 to_url 两个方法这是文档标准扩展路径。include() 的用法是 URL 分发的核心技巧。业务应用的路由不要全部塞进主项目 urls.py每个应用自己维护 urls.pyinclude 到主文件里。好处是模块边界清楚团队多人改路由时不会互相覆盖。反向解析用 name 参数后模板里直接用 {% url article_detail article.pk %}哪怕路径后面改了模板代码不用动。命名空间容易被忽略。两个应用如果各有名为 index 的路由不加命名空间时反向解析就会撞车。声明 app_name 之后模板里的 {% url blog:index %} 才能准确定位到 blog 应用下的路由。我见过项目里因为漏了这层命名空间页面跳转到了错误视图排查了两小时。3. 模型与 ORM从文档字段表格到迁移实操3.1 字段类型与参数null、blank、on_delete 的边界模型层是 Django 的核心抽象。文档里模型字段类型是一张长表格每个类型都对应数据库列类型和默认表单控件。真正容易踩坑的不是选哪个类型而是字段参数之间的语义差异特别是 null、blank、on_delete 这三个。from django.db import models class Article(models.Model): title models.CharField(max_length200, help_text文章标题) summary models.TextField(blankTrue, nullFalse, default) category models.ForeignKey(Category, on_deletemodels.PROTECT) views_count models.PositiveIntegerField(default0) is_published models.BooleanField(defaultFalse) def __str__(self): return self.titlenullTrue 影响数据库层表示这一列允许存 NULLblankTrue 影响表单校验层表示这个字段允许留空。这俩经常混用很多人一把梭直接 nullTrue, blankTrue结果本该必填的内容表单里留空也能提交数据库存了一堆 NULL。文档的建议是字符串字段优先用 blankTrue 加空字符串默认值而不是 nullTrue。因为 CharField 和 TextField 在数据库里通常约定 NOT NULL字符串字段用 NULL 和空字符串在查询时语义不同后续清洗和统计时容易出问题。on_delete 在 Django 4.0 里是外键字段的必填参数。老项目升级过来外键没写它启动直接 TypeError。CASCADE 表示父记录删除时子记录跟着删PROTECT 表示有子记录引用时禁止删父记录SET_NULL 要求字段同时设 nullTrue父记录删除后子记录外键置空。选择取决于业务语义订单明细跟着主单删用 CASCADE分类被文章引用时不允许删分类用 PROTECT。文档把每种选项的副作用都写了照着业务对应就行。3.2 迁移三步走makemigrations、sqlmigrate、migrate迁移机制是 Django 区别于很多轻量框架的重要设计文档有一整节讲原理和执行顺序。简单说两条命令makemigrations 根据模型变化生成迁移脚本migrate 把脚本落到数据库。# 检查模型变化并生成迁移文件 python manage.py makemigrations # 查看迁移文件对应的 SQL python manage.py sqlmigrate blog 0001 # 真正执行迁移 python manage.py migratemakemigrations 是只读操作不连接数据库修改数据。它读取应用 models.py和 migrations 目录下最近的迁移对比生成新的迁移文件。sqlmigrate 是排查时的利器它把迁移文件记录的操作翻译成真正要执行的 SQL 打出来不执行。我每次做模型改动都会先跑一次 sqlmigrate确认字段类型、长度、索引对得上预期。CharField 写错 max_length生成的 VARCHAR 长度不对等执行完再发现就要手工改数据库了。migrate 按依赖顺序执行所有未应用迁移包括框架自带的 auth、admin、sessions 基础表。首次建库跑一次后面模型变化再跑。迁移文件是业务资产的一部分要提交进版本库不要进 .gitignore。3.3 查询集的惰性求值常用写法一次说清QuerySet 的惰性求值是文档反复强调的概念。理解这个你才知道查询语句什么时候真正访问数据库。惰性求值意思是构造查询集对象时不执行 SQL只有迭代、取下标、调用特定触发方法时才会真正执行数据库查询。from blog.models import Article # 惰性构造此时没有 SQL 执行 qs Article.objects.filter(is_publishedTrue) # 迭代触发查询 for article in qs: print(article.title) # 切片只取前 10 条对应 LIMIT 10 top10 qs[:10] # count 是聚合查询立即触发 SQL total qs.count() # values_list 返回元组列表flatTrue 返回单列值列表 titles qs.values_list(title, flatTrue) # exists 只判断是否存在不加载行数据 has_any qs.exists()链式过滤是 ORM 的优势。filter 可以连续调用每个 filter 追加一个 AND 条件。文档例子常把不同筛选条件拆成多行可读性好很多articles Article.objects.filter( category__namePython ).filter( is_publishedTrue ).order_by(-created_at)[:10]category__name 的双下划线写法是跨表关联查询的标准做法沿 category 外键取关联模型的 name 字段筛选。常用操作符包括 __contains 做字符串包含、__in 做列表匹配、__gte / __lte 做大小比较、__date 做日期范围过滤。文档有专门一节列出这些建议用到时翻一翻。惰性求值的常见误用把查询集对象传到模板后循环多次每次循环打一次 SQL。文档建议在视图里用 list() 强制求值或者在模板里尽量只循环一次。页面一慢排查下来经常全是 ORM 在背后重复查询。4. 视图、模板与表单把数据从数据库送到页面4.1 函数视图与类视图先用 FBV再上 CBV 的取舍理由Django 文档在视图章节同时介绍函数视图FBV和类视图CBV没有倾向性淘汰哪一方。新手建议先用 FBV 把逻辑跑通原因很简单函数视图执行链路短传入 request、返回 response中间几乎没有隐藏机制报错时回溯清晰。from django.shortcuts import render, get_object_or_404 def article_detail(request, pk): article get_object_or_404(Article, pkpk, is_publishedTrue) return render(request, blog/article_detail.html, {article: article})get_object_or_404 是文档特别推荐的快捷写法。常规做法是 try / except Article.DoesNotExist它把这个流程压缩成一行。找不到记录时直接抛 Http404Django 返回 404 页面。额外传入的过滤条件会加到查询上等于同时做了权限过滤和存在性检查。FBV 跑通后再逐步迁移到类视图。ListView、DetailView 这类通用视图能省不少样板代码但背后有一段默认流程get 方法、get_queryset、get_context_data 这些钩子方法。平时不显示不代表不存在。我的习惯是只使用完全理解内部流程的通用视图如果只是图快抄了 ListView 却说不清它怎么分页出性能问题时还是要回头补课。4.2 模板系统与静态文件最容易被跳过的配置模板是 Django 自带的模板语言和框架结合度最高。文档里最常用的标签是 {% if %}、{% for %}、{% url %} 和 {% extends %}。过滤器管道符用法和 Unix 管道类似{{ article.created_at|date:Y-m-d }} 把日期对象格式化成字符串。{% extends base.html %} {% block content %} ul {% for article in articles %} lia href{% url blog:article_detail article.pk %}{{ article.title }}/a/li {% empty %} li暂无可展示文章/li {% endfor %} /ul {% endblock %}路径组织方式值得留意。文档推荐每个应用建 templates/app_name/ 两层目录防止不同应用同名模板互相覆盖。Django 加载模板时按 INSTALLED_APPS 顺序找名字直接放 templates/index.html 很容易被别的应用顶掉。静态文件这一节经常被跳过。DEBUGTrue 时开发服务器能直接提供 /static/ 路径文件但前提是 urls.py 配置了 static() 辅助路由。我第一次部署时没跑 collectstatic页面样式全丢查了很久才发现静态文件没收集到指定目录。settings.py 里 STATIC_URL 默认是 /static/开发阶段往这个目录放文件就行但要在 urls.py 加路由。4.3 表单生命周期渲染、校验、回显、重定向表单章节是文档里体量较大的一章。核心是理解表单对象从创建到处理完成的完整生命周期GET 请求时创建空表单渲染页面POST 请求时绑定数据并校验校验通过就处理业务并重定向校验失败则把错误信息回显给用户。from django import forms class ArticleForm(forms.ModelForm): class Meta: model Article fields [title, summary, category] def article_create(request): if request.method POST: form ArticleForm(request.POST) if form.is_valid(): form.save() return redirect(blog:article_list) else: form ArticleForm() return render(request, blog/article_form.html, {form: form})这段代码能跑通靠 ModelForm 特性字段校验规则从模型字段定义继承。模型里 CharField 的 max_length 在表单层自动转成长度校验BooleanField 自动生成复选框。需要额外自定义校验时在表单类里写 clean_字段名方法返回校验后的值或抛 ValidationError这是文档推荐做法。重定向这一步容易漏。POST 成功后没有 redirect用户刷新页面会把表单再提交一次产生重复数据。文档明确推荐 Post/Redirect/Get 模式我后来每次写表单都强制检查这个链路。校验失败时要保留用户输入直接用绑定了数据的表单实例去渲染模板不要重新 new 一个空表单否则用户刚填的内容全丢了。5. 排查与避坑四个经典问题都用文档解决了5.1 时区差八小时TIME_ZONE、USE_TZ 一起用才不翻车现象created_at 字段存入数据库后再取出来显示的时间比本地时间早八小时。原因USE_TZ 为 True 时Django 按 UTC 存储所有时间读取时按 settings.TIME_ZONE 转换。如果模板里没用 timezone 相关处理看到的就是 UTC 原始时间。解决settings 里 TIME_ZONE 设为 Asia/ShanghaiUSE_TZ 保持 True模板渲染时 Django 会自动做本地化。JSON 接口返回 datetime 时手动用 localtime() 转当前时区再序列化。USE_TZ 设 False 才完全禁用时区转换不推荐文档专门有一节讲多时区处理策略默认行为在服务是单一时区时足够可靠。5.2 迁移冲突什么时候执行 makemigrations --merge现象多人协作时各自基于同一个迁移版本生成了新迁移合并代码后 migrate 报告多个迁移分支指向同一个父版本。原因迁移文件是线性追加的两个分支各自 append 导致分叉。Django 检测到多个头节点拒绝继续迁移。解决按文档提示执行 python manage.py makemigrations --mergeDjango 会生成一个合并迁移文件把分叉捏回一条线。确认没有逻辑冲突后再 migrate。这个操作不更改数据表只调整迁移图的拓扑结构。5.3 静态文件 404DEBUG 模式下也出现白板页面现象DEBUGTrue 启动开发服务器页面 HTML 正常返回但所有 CSS、JS 都 404。原因settings.py 里配了 STATIC_URL但 urls.py 里没有加 static() 辅助路由开发服务器不会自动把静态文件目录映射到 URL。解决项目 urls.py 追加一段仅 DEBUG 生效的配置。from django.conf import settings from django.conf.urls.static import static if settings.DEBUG: urlpatterns static(settings.STATIC_URL, document_rootsettings.STATIC_ROOT)生产环境不要保留这段代码。部署时先跑 collectstatic 把静态文件收集到 STATIC_ROOT由 Nginx 之类的外部 Web 服务器直接提供访问Django 不参与静态文件分发。5.4 外键 on_delete 必填4.0 升级的硬性变更现象从旧教程抄的 models.py 里写了 category models.ForeignKey(Category)跑起来直接 TypeError。原因Django 2.0 起把 on_delete 参数改为必填项4.0 延续这个约束。旧的默认 CASCADE 行为被废弃防止开发者不知情时把子数据连带删掉。解决按业务语义选择显式 on_delete。父记录被删、子记录没意义用 CASCADE父记录被引用时不允许删父记录用 PROTECT父记录删除后子记录外键置空且字段本身允许 NULL用 SET_NULL。6. 进阶把文档目录当项目功能清单用的三个验证技巧6.1 目录逆向法从章节标题反推模块清单官方中文文档的目录本身就是一份完整功能地图。从快速入门到模型层、视图层、模板层、表单、认证、Admin、测试、部署、安全这一串目录标题可以直接映射成项目模块清单。我接到新需求时先打开文档目录对着需求逐条打勾有登录需求就看认证章节有后台管理需求就看 Admin 章节有接口测试需求就看测试章节。这个习惯让我写代码前就确定了要动哪些文件、要引哪些库而不是边写边翻索引。6.2 把 Tutorial 刷三遍三次验证目标不同官方 Tutorial 写得精简但值得刷三遍每遍期望不同。第一遍照着敲目标是让代码跑起来。第二遍不抄代码把每一步的逻辑写下来确认自己理解它为什么存在。第三遍不看文档靠记忆从零搭一个最小项目卡住了再回去翻。我当初就是用这种方法把 Django 的启动过程刻进脑子的。刷完第三遍你会发现自己对新版本 API 的记忆比翻了一圈博客总结都牢。6.3 版本差异是变更日志升级前先读这一节官方文档在每个大版本发布后都会更新新特性和向后不兼容的变更两个部分。这其实就是一份规范的升级变更日志。升级到新版本前先把这两部分过一遍能避免很多意外。我吃过一次亏项目从 3.x 升 4.0 时没看文档结果若干配置默认值变了从 2.x 迁移过来的 URL 写法直接失效排查大半天才回过神去看官方文档的变更页。那次之后我给自己定了个规矩每次升级前强制把官方文档相关章节从头到尾读一遍把所有标注 deprecated 和 removed 的 API 记录到自己的笔记里再动手改代码。工具用熟了反而更要看文档因为它变了你没变吃亏的是你。希望帮到你。本文还有配套的精品资源点击获取

Django 4.0官方中文文档实战：从项目骨架到ORM与避坑指南

相关推荐

通义灵码Agent闭环工作流：从代码补全到自主交付的实操指南

基于Java的高考志愿智能填报系统设计与实现

VLAN划分实战：从广播域隔离到交换机配置与故障排查

更多资讯

Linux审计事件实时分发：audispd原理与高可靠管道实践

Qt调用MATLAB生成DLL实战：跨平台算法集成方案

LEAP-1A26发动机性能建模实战：数据准备、稳态匹配与调参避坑

Starrc寄生提取与后仿偏差归因实战指南

计算机考研复试英语口语：高频题型与答题框架全攻略

版本地狱实录：Wine、FEX-Emu、DXMT 三方版本不匹配就是一场白折腾

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？