很多人学 Django 都有一种共同的困惑语法看懂了官方教程跟着敲完了但真要自己从零搭建一个“真实项目”时却不知道从哪下手。尤其是当你面对的不再是Hello World而是多个 App、数据表关联、后台管理、模板渲染、部署上线这一整条链路时教程里没讲清楚的细节会集中爆发。这篇文章是我学习《Python Django 大师班构建真实 Web 应用》系列过程中整理的核心笔记也是中文语音课程第一部分的实战复盘。我会抛开“照着敲一遍”的无效学习方式用一条完整链路带你从环境准备、项目初始化、数据建模、视图路由一直走到后台管理和运行验证。读完你会发现Django 真正强大的地方不是“写接口快”而是它把 Web 开发里最繁琐、最重复的工程问题都替你解决掉了你要做的反而只剩下两件事想清楚数据结构组织好业务逻辑。为了让你看得不累我先把本篇文章的判断放在最前面Django 适合做“业务逻辑复杂、后台管理需求重、需要快速上线”的 Web 应用。它不适合做极致的接口性能调优和高并发 I/O 密集型服务那是另一个技术栈的战场。如果你正准备用 Python 进入 Web 开发领域或者公司内部需要一个能快速交付的管理系统Django 是你今天就能开始动手的技术。1. 为什么 Django 值得作为构建真实 Web 应用的主框架先解决一个认知问题Python 生态里 Web 框架不止一个Flask 轻巧、FastAPI 高性能为什么还要学 Django我的理解是——Django 自带“全家桶”。它不是一个单独的 Web 服务器也不是一个简单的路由分发器而是一整套 Web 开发基础设施ORM把数据库表映射成 Python 对象不需要写原生 SQL 也能完成绝大部分增删改查。Admin 后台模型定义完之后Django 自动生成一个可用的管理后台这对企业内部系统来说几乎等于白送了一套中台。表单系统处理用户输入、数据校验、错误提示。认证系统用户登录、退出、权限、会话管理内置且经过多年生产环境验证。安全防护XSS、CSRF、SQL 注入等常见 Web 攻击框架层面已经做了默认防护。迁移机制数据模型改动后通过命令同步到数据库团队协作时能保证各环境数据结构一致。这些能力意味着你从“写接口”到“上线一个用户可用的系统”中间省去了大量选型和组装工作。Flask 需要你自己决定用 SQLAlchemy 还是 Peewee用 WTForms 还是自研校验Django 则直接告诉你遵循我的约定东西我都给你了。拿我自己的经验来说之前用 Flask 做一个内部管理系统光是把用户认证、权限控制、数据模型初始化这三件事搭起来就花了两天。后来换 Django 重写一个晚上就完成了核心骨架。这种差距不是代码量的问题而是框架设计哲学的区别。所以如果你的目标是“快速构建一个真实、完整、可维护的 Web 应用”Django 是目前 Python 生态里综合成本最低的选择。1.1 课程第一部分到底在讲什么《Python Django 大师班》这门课的中文语音部分被拆分成了四段内容本次是第一段。从学习路径来看第一部分完成了从“完全不会”到“能独立创建项目并运行数据库迁移”的跨越。具体覆盖这些知识点Django 环境安装与项目初始化项目 Project 与应用 App 的区别settings.py 核心配置项基于 ORM 的模型定义与数据库迁移Django Admin 后台配置与使用这四个模块构成了所有 Django 项目的底座。无论你以后做电商、内容管理、物联网平台还是企业内部系统第一天写代码时面对的一定是这些内容。1.2 什么样的读者最适合读这篇文章如果你符合下面任一情况这篇文章会特别适合你学完 Python 基础语法想进入 Web 开发但不知道第一个框架选什么。用 Flask 写过一些接口想对比学习 Django 的全栈式开发思维。需要在公司内部快速交付一个带后台管理的业务系统。准备面试需要系统梳理 Django 的核心知识点。反过来如果你的需求是“写一个高并发、纯 API 后端”那 FastAPI 可能更适合如果你的应用只暴露几个接口不需要后台和模板Django 稍显厚重。技术选型没有绝对的好坏只有适合不适合。2. Django 的 MTV 架构先理解请求在框架里怎么走一遍在学习任何代码之前先理解 Django 的架构思想这会让你后面写代码时少走很多弯路。Django 使用的是 MTV 模式全称是 Model、Template、View看起来和 MVCModel、View、Controller很像但职责划分有区别。Model模型数据层。定义数据结构与数据库交互。一个模型类对应数据库中的一张表。Template模板表现层。负责 HTML 页面的渲染里面可以使用 Django 模板语法比如{{ variable }}、{% for %}。View视图逻辑层。接收用户请求操作模型数据然后决定把数据交给哪个模板渲染。这里注意Django 中的 View 相当于 MVC 里的 Controller。一次完整的请求流程是这样的用户在浏览器输入 URL。Django 根据 URL 配置urls.py找到对应的视图函数。视图函数收到请求HttpRequest如果需要数据就通过模型类操作数据库。视图把从数据库拿到的数据打包成上下文context交给模板。模板把数据填充进 HTML 页面生成一个完整的 HTTP 响应HttpResponse。浏览器收到响应渲染页面。有一个非常经典的误区很多新手以为 Django 里的 View 是给前端提供 JSON 数据的接口层实际上在传统 MTV 架构里View 的作用更像“调度中心”——它把数据从数据库里取出来再决定怎么展示。当然现在很多人用 Django 开发纯后端 API通过JsonResponse返回 JSON 数据这也没有问题。但你要清楚那不是 Django 的默认姿态而是它的能力之一。理解 MTV 能帮你搞明白 Django 的模板系统为什么存在以及视图函数里为什么经常写着“先查数据库再 render 页面”这样的代码。学习 Django 时不要一上来就追求“前后端分离”。先按照 Django 原生的 MTV 方式做一个完整项目把模型、视图、模板之间的协作关系跑通你才算真正理解了 Django。之后再接触 DRFDjango REST Framework做接口开发会轻松很多。2.1 为什么要先理解请求流转因为后面的所有代码都是在回答三个问题用户访问哪个地址URL 配置这个地址对应的处理逻辑是什么视图处理完之后展示什么模板把这三个问题先装进脑子再看代码就不会迷路。3. 环境准备Python 虚拟环境与 Django 安装开始写代码前先把环境准备好。注意我下面所有的操作都以 Windows/macOS/Linux 通用命令行方式为例版本相关的细节会重点说明。Django 主体版本以实际安装为准本文演示的思路适用于 Django 4.x / 5.x 以上版本。3.1 Python 版本选择Django 是一个纯 Python 编写的框架所以你的机器上必须先有 Python。建议安装 Python 3.10 及以上版本越新越好。一个重要的经验是不要使用系统自带的 Python 来搞 Web 开发尤其是 macOS 和 Linux 用户。系统 Python 通常被系统工具依赖直接往里面安装第三方包容易引发权限问题或依赖冲突。推荐从 Python 官网下载安装包安装时勾选“Add Python to PATH”这样终端里才能直接运行 python 和 pip。安装完成后打开终端或命令行工具验证版本python --version如果提示找不到命令检查环境变量是否配置正确。Windows 用户如果安装了多个 Python 版本可能需要用py -3 --version来指定版本。3.2 为什么必须使用虚拟环境虚拟环境是 Python 开发里最基础、也最容易被忽略的一环。简单说虚拟环境就是一个独立的 Python 运行目录。这个目录里安装的第三方包只对当前项目生效不会污染全局环境。这有什么用举个例子你有一个项目 A 用的是 Django 4.2另一个项目 B 用的是 Django 5.2。如果没有虚拟环境你只能在全局环境里安装一个版本换项目就要卸载重装非常痛苦。有了虚拟环境A 和 B 各自拥有独立的依赖包互不干扰。更关键的是部署到服务器时虚拟环境可以帮你清晰地导出依赖清单requirements.txt别人拿到清单就能复现你的环境。这一点在团队协作和生产部署中极其重要。3.3 创建虚拟环境并安装 Django打开终端进入你想存放项目的目录执行# 创建虚拟环境 python -m venv venv这条命令会在当前目录下生成一个名为venv的文件夹里面是独立的 Python 解释器和包管理工具。然后激活虚拟环境Windowsvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活成功后命令行提示符前面会出现(venv)标志。这时候你执行的 python、pip 命令都指向虚拟环境内部的解释器。接下来安装 Djangopip install django如果想指定版本可以写pip install django4.2.16具体版本以你的项目需求为准不要盲目追求最新。新版本虽然功能更新但第三方插件的兼容性不一定同步。验证安装python -m django --version能正常输出版本号说明安装成功。这里我想多说一句很多新手在当前目录下执行pip install django然后发现命令找不到或者安装后仍然提示ModuleNotFoundError。绝大多数原因都是没有激活虚拟环境pip 安装到了全局环境而当前终端却指向虚拟环境。所以激活虚拟环境后再执行安装命令这是铁律。3.4 IDE 选择PyCharm 还是 VS Code这个问题经常被问起。我的看法是PyCharm专业版对 Django 支持极好有模板补全、URL 跳转、ORM 调试等功能新手用起来省心。VS Code免费、轻量配合 Python 插件也可以获得不错的开发体验。选哪个不关键关键是你愿意花时间熟悉它。我的建议是新手先从 PyCharm Community社区版开始等你对 Django 的项目结构有了完整认识再换 VS Code 也完全来得及。社区版虽然没有 Django 专属功能但作为代码编辑器配合终端运行命令体验也足够流畅。4. 创建项目和应用理解 project 与 app 的分工环境准备好了接下来创建 Django 项目。这里有一个很重要的概念需要先弄清楚Project项目和App应用是两回事。Project一个网站整体的配置入口。它包含全局的 URL 配置、settings 配置、数据库配置等。一个 Project 可以承载多个 App。App一个功能模块。比如一个博客网站会有用户管理 App、文章管理 App、评论管理 App。每个 App 都是相对独立的业务模块。这个设计的好处是复用性。你现在做的电商项目里的“商品管理 App”以后做二手交易平台时可以直接复制过去只要稍作修改就能用。4.1 创建项目在虚拟环境激活的状态下执行django-admin startproject myproject这条命令会生成一个myproject文件夹内部结构如下myproject/ ├── manage.py └── myproject/ ├── __init__.py ├── settings.py ├── urls.py └── wsgi.py初学者容易搞混的是外层myproject和里层myproject名字一样。外层myproject/项目根目录。manage.py在这里以后大部分命令行操作都要在这个目录下执行。内层myproject/项目配置文件包。settings.py是全局配置urls.py是根路由配置wsgi.py是部署时用的入口文件。为了减少混淆建议你给项目起一个有意义的名字比如blog_project、shop_project。4.2 创建应用执行python manage.py startapp todo这会生成一个todo文件夹里面有todo/ ├── migrations/ ├── __init__.py ├── admin.py ├── apps.py ├── models.py ├── tests.py └── views.py每一个文件都有明确职责models.py定义数据模型。views.py业务逻辑处理。admin.py把模型注册到后台管理。migrations/数据库迁移记录由命令自动生成不需要手动编辑。创建完 App 后必须手动把它注册到项目里否则 Django 不知道这个 App 的存在。4.3 注册 App 到 INSTALLED_APPS打开myproject/settings.py找到INSTALLED_APPS列表加一行# 文件路径myproject/settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, todo, # 新增 ]这里一定不要漏掉。遗忘注册 App 的话后面运行迁移命令时Django 完全不会创建这个应用的数据表而且不会报任何错误排查起来非常隐蔽。4.4 启动开发服务器验证在项目根目录包含manage.py的目录执行python manage.py runserver看到类似下面的输出说明项目创建成功Starting development server at http://127.0.0.1:8000/浏览器打开这个地址能看到 Django 的默认欢迎页就是那个火箭图标页面。此时可以顺便测试一下如果没有注册 App 直接启动服务器不会有任何问题但一旦执行迁移命令你会看到它只处理了内置 App 的迁移自己创建的 todo 应用完全消失。这就是“不报错但数据表缺失”的经典场景。5. 关键配置文件 settings.py时区、语言、数据库项目能跑起来之后先别急着写代码。有一个文件你必须花时间仔细理解它就是settings.py。这个文件控制着 Django 项目的全局行为。5.1 基本信息配置打开settings.py重点关注以下几项。SECRET_KEYDjango 加密签名用的密钥涉及 Session、CSRF、密码重置等功能。生产环境必须把这个值换成一个随机的长字符串并且不要提交到代码仓库。DEBUG调试模式开关。开发时必须为True这样出错时会显示详细的堆栈信息。但部署到生产环境必须改成False否则用户能看到你的源代码路径、数据库配置甚至局部代码片段。ALLOWED_HOSTS允许访问站点的域名列表。DEBUG True时可以为空但部署阶段必须写入你的域名或服务器 IP否则会报DisallowedHost错误。5.2 语言与时区Django 默认语言是英语默认时区是 UTC。对于中文项目强烈建议修改为# 文件路径myproject/settings.py LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai USE_TZ True这里有一个需要注意的细节USE_TZ True表示数据库存储时间时使用 UTC 时间展示时自动转换为当前时区。如果你的项目不需要处理跨时区用户可以保留这个默认设置如果你确定所有用户都在同一时区也可以改成False但一般不建议。改完语言和时区后重启开发服务器进入 Django 后台时你会发现界面变成了中文。这是一个非常直观的“配置生效”体验。5.3 数据库配置Django 默认使用 SQLite 数据库配置文件长这样# 文件路径myproject/settings.py DATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } }初学者完全不需要急着换数据库。SQLite 零配置、文件型、随项目走非常适合开发和测试。等你把业务逻辑全部跑通了部署前再切换成 MySQL 或 PostgreSQLDjango 的 ORM 层保证了你绝大部分代码不需要变动。以后切换到 MySQL 时配置会变成DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: your_database_name, USER: your_user, PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, } }不理解 ORM 的话你会觉得切换数据库是件大事。理解了之后就会发现Django 把底层差异全部隔离了切换数据库只是改配置而已。5.4 静态文件配置Django 处理 CSS、JS、图片这些静态文件需要指定目录。默认配置里有一段STATIC_URL static/STATIC_URL是浏览器访问静态文件的 URL 前缀。实际项目开发中你通常还要加上一个专门存放静态文件的目录STATICFILES_DIRS [ BASE_DIR / static, ]然后在项目根目录手动创建一个static文件夹把 CSS 和 JS 放进去。这里有个新手经常踩的坑明明把style.css放在了项目根目录的static文件夹里但页面加载不出来。原因就是只配置了STATIC_URL没有配置STATICFILES_DIRS。Django 根本不知道去哪里找这个静态文件夹。6. 第一个真实功能用 ORM 定义任务数据模型理解了配置之后我们开始写第一个真实功能。我选了“任务管理Todo”这个案例因为它足够小但覆盖了模型、迁移、后台管理、视图、模板五个核心环节——没有任何多余的“魔法”。6.1 定义模型打开todo/models.py定义一个任务类# 文件路径todo/models.py from django.db import models class Task(models.Model): title models.CharField(任务标题, max_length200) description models.TextField(任务描述, blankTrue) completed models.BooleanField(是否完成, defaultFalse) created_at models.DateTimeField(创建时间, auto_now_addTrue) def __str__(self): return self.title class Meta: verbose_name 任务 verbose_name_plural 任务这段代码做了四件事继承models.Model告诉 Django 这是一个数据库表。定义四个字段标题字符串、描述长文本、是否完成布尔值、创建时间自动记录。定义__str__方法让后台列表显示任务标题而不是Task object。定义Meta给模型起中文名。关于字段类型先记住三个最常用的CharField短文本必须指定max_length。TextField长文本不限制长度。BooleanField布尔值常用作状态开关。6.2 生成数据库迁移模型定义好之后数据库里还没有对应的表。需要通过两步命令同步python manage.py makemigrations python manage.py migratemakemigrations会生成一个迁移文件位置在todo/migrations/下记录你对模型的创建或改动。migrate负责把迁移记录真正执行到数据库完成建表。执行完第一条命令后你会看到类似输出Migrations for todo: todo/migrations/0001_initial.py - Create model Task如果这一步什么都没输出说明 Django 没检测到模型变化。多数情况是因为 App 没注册到INSTALLED_APPS回去检查一下。6.3 认识 Django ORM 的基础增删改查Django ORM 的价值在于你不写 SQL 也能完成数据库操作。在虚拟环境里执行python manage.py shell进入交互式环境后我们可以测试几个核心操作# 新增 task Task.objects.create(title学习 Django, description完成大师班第一课) task.pk # 输出1主键自动生成 # 查询所有 tasks Task.objects.all() print(tasks) # 条件查询 unfinished Task.objects.filter(completedFalse) # 修改 task.completed True task.save() # 删除 task.delete()这就是 ORM 最核心的四个动作增、查、改、删。以后你在视图里写的大部分逻辑本质上都是这几行代码的变体。6.4 注册到 Django Admin 后台Django 自带一个可视化数据管理后台这是很多其他框架不具备的能力。注册模型后你就能在后台直接维护任务数据不需要自己写管理页面。打开todo/admin.py写入# 文件路径todo/admin.py from django.contrib import admin from .models import Task admin.register(Task) class TaskAdmin(admin.ModelAdmin): list_display (title, completed, created_at) list_filter (completed,) search_fields (title,)这里配置了三个实用功能list_display列表页显示哪些字段。list_filter右侧按“是否完成”筛选。search_fields支持按标题搜索。启动服务器python manage.py runserver访问http://127.0.0.1:8000/admin/第一步要先登录。Django 需要你创建超级管理员在项目目录执行python manage.py createsuperuser按提示输入用户名、邮箱可跳过、密码。登录后台后你会看到“认证和授权”以及“任务管理”两个模块点进“任务”就能操作刚才生成的表数据。到这里你已经完成了 Django 数据层的完整闭环定义模型 → 迁移建表 → 后台管理。这一步对新手来说是里程碑式的收获数据库、管理后台、数据增删改查全部搞定全程没有手写一行 SQL。7. 视图、URL 与模板让数据在页面上“活”起来数据已经在后台可以管理了但普通用户不能也不需要进入后台。下一步是写一个页面把这些任务展示出来并允许用户完成标记。7.1 创建第一个视图函数打开todo/views.py写入# 文件路径todo/views.py from django.shortcuts import render from .models import Task def task_list(request): tasks Task.objects.all().order_by(-created_at) return render(request, todo/task_list.html, {tasks: tasks})代码逻辑很简单查询所有任务按创建时间倒序排列交给模板渲染。这里需要注意一个约定render函数的第二个参数是模板路径Django 默认在项目根目录下的templates文件夹里寻找模板。为了让不同 App 的模板不互相覆盖惯例是templates/应用名/模板名.html这样组织。7.2 配置路由 URLDjango 里的 URL 配置分成两层根路由和应用路由。先在myproject/urls.py里配置总路由# 文件路径myproject/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(todo.urls)), ]然后在todo/目录下新建一个urls.py文件# 文件路径todo/urls.py from django.urls import path from . import views urlpatterns [ path(, views.task_list, nametask_list), ]这里的设计思路是项目的根路由只管把/admin/和业务功能分开具体业务模块内部的 URL 由每个 App 自己管理。项目变大后每个 App 的路由相互独立不会杂乱无章。7.3 编写模板文件在项目根目录创建templates/todo/task_list.html!-- 文件路径templates/todo/task_list.html -- !DOCTYPE html html langzh-hans head meta charsetUTF-8 title任务清单/title /head body h1我的任务/h1 ul {% for task in tasks %} li {% if task.completed %} ✅ {{ task.title }}已完成 {% else %} {{ task.title }} {% endif %} /li {% empty %} li暂无任务/li {% endfor %} /ul /body /html这里用到了两个最常用的 Django 模板语法{% for task in tasks %}循环遍历视图传入的列表。{% if task.completed %}条件判断。{% empty %}当列表为空时显示提示。刷新浏览器访问http://127.0.0.1:8000/你会看到任务列表已经渲染在页面上。刚才在后台或 shell 里创建的数据现在全部展示出来了。7.4 完整示例实现“标记完成”功能静态展示数据还不够一个真实的 Web 应用必须能响应用户操作。我们在列表后面加上一个“完成”按钮。修改路由和视图# 文件路径todo/urls.py from django.urls import path from . import views urlpatterns [ path(, views.task_list, nametask_list), path(complete/int:task_id/, views.complete_task, namecomplete_task), ]视图函数# 文件路径todo/views.py from django.shortcuts import render, get_object_or_404, redirect from .models import Task def task_list(request): tasks Task.objects.all().order_by(-created_at) return render(request, todo/task_list.html, {tasks: tasks}) def complete_task(request, task_id): task get_object_or_404(Task, pktask_id) task.completed True task.save() return redirect(task_list)模板里加上链接li {% if task.completed %} ✅ {{ task.title }}已完成 {% else %} {{ task.title }} a href{% url complete_task task.id %}完成/a {% endif %} /li现在点击“完成”任务状态会更新页面刷新后显示为已完成。这个简单的交互背后完整走了一遍“URL → 视图 → 模型更新 → 重定向到列表”的请求流程。它是所有业务功能的缩影。以后你做更复杂的系统比如订单支付状态更新、文章发布、用户关注底层全是这个模式。7.5 加一点样式静态文件处理为了让页面不至于太朴素可以加一个简单的 CSS 文件。在项目根目录创建static/css/style.css/* 文件路径static/css/style.css */ body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; line-height: 1.6; color: #333; } a { color: #007bff; text-decoration: none; }修改模板引入静态文件!-- 文件路径templates/todo/task_list.html -- {% load static %} !DOCTYPE html html langzh-hans head meta charsetUTF-8 title任务清单/title link relstylesheet href{% static css/style.css %} /head body !-- 其他内容不变 -- /body /html注意两件事第一模板里必须先用{% load static %}加载静态文件标签第二settings.py里必须已经配置了STATICFILES_DIRS否则样式文件找不到。刷新页面样式生效。到这里一个没有任何脚手架、不带任何多余依赖的完整 Django 应用——数据模型、后台管理、列表展示、状态更新、静态样式——已经全部跑通了。8. 常见问题与排查思路初学者遇到报错时第一反应往往是“我代码写错了”但实际上大量错误来自环境、配置和路径问题。这里整理我实践过程中最常碰到的几个问题供你排查时参考。问题现象可能原因排查方式解决方案django-admin不是内部或外部命令Django 未安装或未激活虚拟环境运行pip show django检查是否安装激活虚拟环境执行pip install djangoModuleNotFoundError: No module named djangoPython 解释器路径不对安装在全局环境终端输入python -c import django; print(django.__version__)验证确保当前环境是虚拟环境重新安装 DjangoDisallowedHost错误访问域名不在ALLOWED_HOSTS中查看报错信息中的域名把域名或 IP 加入ALLOWED_HOSTSmakemigrations提示“没有变化”App 未注册到INSTALLED_APPS打开 settings.py 检查在INSTALLED_APPS中加入应用名称后台页面加载不出 CSSSTATICFILES_DIRS未配置浏览器开发者工具检查请求 URL配置静态文件目录模板中使用{% load static %}页面显示Page not foundURL 路径错误或未 include 应用路由检查myproject/urls.py注册应用路由到根路由数据库查询数据为空未执行迁移或未创建数据后台检查数据表是否有记录执行makemigrations和migrate保存中文乱码数据库编码不支持 UTF-8如果是 MySQL检查库表字符集统一为 utf8mb4 编码一个重要习惯报错时不要只看最后一行从日志最底部往上翻找到第一个File ...开头的行那才是真正出错的位置。Django 的错误页面在DEBUGTrue时会直接告诉你文件名和行号大多数时候问题都能快速定位。9. 最佳实践与生产环境部署提醒项目跑通只是第一步。如果想把它变成一个能上线、可维护、能交付的真实应用下面这些工程层面的建议请认真对待。9.1 环境隔离与依赖管理虚拟环境是开发阶段的保障但回到一台新电脑或部署服务器时你的项目必须能快速复制环境。建议在项目根目录生成依赖清单pip freeze requirements.txt别人拿到你的项目后只需要python -m venv venv source venv/bin/activate pip install -r requirements.txt就能完整复现环境。注意pip freeze会导出虚拟环境里所有的包包括间接依赖。如果希望更精准可以用pipreqs之类的工具只导出项目直接使用的依赖但对于个人项目来说pip freeze已经足够。9.2 配置文件分离与敏感信息保护把所有配置写在一个settings.py里一开始没问题一旦项目上线问题就来了开发环境的DEBUG要开生产环境要关开发用 SQLite生产用 MySQL两个环境的SECRET_KEY也不能一样。业界常用的做法是设置环境变量或者把配置拆分成多个文件。最轻量的方案是利用环境变量覆盖import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-only-key) DEBUG os.environ.get(DJANGO_DEBUG, True) True这样同一个代码库不同的服务器设置不同的环境变量就能跑出不同的配置行为。更重要的是生产环境的SECRET_KEY和数据库密码绝不能硬编码提交到 Git 仓库。9.3 生产环境部署前的检查清单如果你准备把项目部署到云服务器比如常见的宝塔面板环境上线前必须确认DEBUG False否则用户能看到详细报错信息。ALLOWED_HOSTS配置为你的域名或服务器 IP。SECRET_KEY更换为随机值不要用默认值。使用真实数据库MySQL 或 PostgreSQL而不是 SQLite。收集静态文件python manage.py collectstatic这条命令会把所有 App 内的静态文件统一收集到一个目录方便 Nginx 托管。使用 Gunicorn 或 uWSGI 作为应用服务器而不是 Django 自带的 runserver。开发服务器性能极低只适合本机调试。这一步涉及到的知识量比较大本文先给出方向。后续如果用宝塔面板部署 Django整个流程可以拆成一篇文章专门讲。9.4 继续深入的方向学完这篇内容你已经掌握了 Django 项目的地基。接下来建议按照这个顺序继续精进Django 模板进阶模板继承、自定义过滤器、context processor。表单系统用 Django Form 处理用户提交校验数据安全问题。认证与权限用户注册、登录、修改密码、分组权限。Django REST Framework前后端分离开发、API 设计。部署实战使用 Nginx Gunicorn 部署到云服务器配置 HTTPS。不要试图一次学完所有内容Web 开发是一个实践性极强的领域。把本文的任务管理应用做完、部署上线、让朋友能用你的域名注册账号你对 Django 的掌握程度会远超那些只刷教程的人。回到本文开头的那句话Django 是构建真实 Web 应用的主框架它的门槛不在写代码而在理解工程结构。当你理解了 Project、App、Model、View、Template 是怎么配合的剩下的就是一件需要时间打磨的手艺活。你现在的第一段代码已经跑起来了离一个真实应用只差“继续写完”这步而已。
Django实战：从环境搭建到构建完整Web应用的开发指南
很多人学 Django 都有一种共同的困惑语法看懂了官方教程跟着敲完了但真要自己从零搭建一个“真实项目”时却不知道从哪下手。尤其是当你面对的不再是Hello World而是多个 App、数据表关联、后台管理、模板渲染、部署上线这一整条链路时教程里没讲清楚的细节会集中爆发。这篇文章是我学习《Python Django 大师班构建真实 Web 应用》系列过程中整理的核心笔记也是中文语音课程第一部分的实战复盘。我会抛开“照着敲一遍”的无效学习方式用一条完整链路带你从环境准备、项目初始化、数据建模、视图路由一直走到后台管理和运行验证。读完你会发现Django 真正强大的地方不是“写接口快”而是它把 Web 开发里最繁琐、最重复的工程问题都替你解决掉了你要做的反而只剩下两件事想清楚数据结构组织好业务逻辑。为了让你看得不累我先把本篇文章的判断放在最前面Django 适合做“业务逻辑复杂、后台管理需求重、需要快速上线”的 Web 应用。它不适合做极致的接口性能调优和高并发 I/O 密集型服务那是另一个技术栈的战场。如果你正准备用 Python 进入 Web 开发领域或者公司内部需要一个能快速交付的管理系统Django 是你今天就能开始动手的技术。1. 为什么 Django 值得作为构建真实 Web 应用的主框架先解决一个认知问题Python 生态里 Web 框架不止一个Flask 轻巧、FastAPI 高性能为什么还要学 Django我的理解是——Django 自带“全家桶”。它不是一个单独的 Web 服务器也不是一个简单的路由分发器而是一整套 Web 开发基础设施ORM把数据库表映射成 Python 对象不需要写原生 SQL 也能完成绝大部分增删改查。Admin 后台模型定义完之后Django 自动生成一个可用的管理后台这对企业内部系统来说几乎等于白送了一套中台。表单系统处理用户输入、数据校验、错误提示。认证系统用户登录、退出、权限、会话管理内置且经过多年生产环境验证。安全防护XSS、CSRF、SQL 注入等常见 Web 攻击框架层面已经做了默认防护。迁移机制数据模型改动后通过命令同步到数据库团队协作时能保证各环境数据结构一致。这些能力意味着你从“写接口”到“上线一个用户可用的系统”中间省去了大量选型和组装工作。Flask 需要你自己决定用 SQLAlchemy 还是 Peewee用 WTForms 还是自研校验Django 则直接告诉你遵循我的约定东西我都给你了。拿我自己的经验来说之前用 Flask 做一个内部管理系统光是把用户认证、权限控制、数据模型初始化这三件事搭起来就花了两天。后来换 Django 重写一个晚上就完成了核心骨架。这种差距不是代码量的问题而是框架设计哲学的区别。所以如果你的目标是“快速构建一个真实、完整、可维护的 Web 应用”Django 是目前 Python 生态里综合成本最低的选择。1.1 课程第一部分到底在讲什么《Python Django 大师班》这门课的中文语音部分被拆分成了四段内容本次是第一段。从学习路径来看第一部分完成了从“完全不会”到“能独立创建项目并运行数据库迁移”的跨越。具体覆盖这些知识点Django 环境安装与项目初始化项目 Project 与应用 App 的区别settings.py 核心配置项基于 ORM 的模型定义与数据库迁移Django Admin 后台配置与使用这四个模块构成了所有 Django 项目的底座。无论你以后做电商、内容管理、物联网平台还是企业内部系统第一天写代码时面对的一定是这些内容。1.2 什么样的读者最适合读这篇文章如果你符合下面任一情况这篇文章会特别适合你学完 Python 基础语法想进入 Web 开发但不知道第一个框架选什么。用 Flask 写过一些接口想对比学习 Django 的全栈式开发思维。需要在公司内部快速交付一个带后台管理的业务系统。准备面试需要系统梳理 Django 的核心知识点。反过来如果你的需求是“写一个高并发、纯 API 后端”那 FastAPI 可能更适合如果你的应用只暴露几个接口不需要后台和模板Django 稍显厚重。技术选型没有绝对的好坏只有适合不适合。2. Django 的 MTV 架构先理解请求在框架里怎么走一遍在学习任何代码之前先理解 Django 的架构思想这会让你后面写代码时少走很多弯路。Django 使用的是 MTV 模式全称是 Model、Template、View看起来和 MVCModel、View、Controller很像但职责划分有区别。Model模型数据层。定义数据结构与数据库交互。一个模型类对应数据库中的一张表。Template模板表现层。负责 HTML 页面的渲染里面可以使用 Django 模板语法比如{{ variable }}、{% for %}。View视图逻辑层。接收用户请求操作模型数据然后决定把数据交给哪个模板渲染。这里注意Django 中的 View 相当于 MVC 里的 Controller。一次完整的请求流程是这样的用户在浏览器输入 URL。Django 根据 URL 配置urls.py找到对应的视图函数。视图函数收到请求HttpRequest如果需要数据就通过模型类操作数据库。视图把从数据库拿到的数据打包成上下文context交给模板。模板把数据填充进 HTML 页面生成一个完整的 HTTP 响应HttpResponse。浏览器收到响应渲染页面。有一个非常经典的误区很多新手以为 Django 里的 View 是给前端提供 JSON 数据的接口层实际上在传统 MTV 架构里View 的作用更像“调度中心”——它把数据从数据库里取出来再决定怎么展示。当然现在很多人用 Django 开发纯后端 API通过JsonResponse返回 JSON 数据这也没有问题。但你要清楚那不是 Django 的默认姿态而是它的能力之一。理解 MTV 能帮你搞明白 Django 的模板系统为什么存在以及视图函数里为什么经常写着“先查数据库再 render 页面”这样的代码。学习 Django 时不要一上来就追求“前后端分离”。先按照 Django 原生的 MTV 方式做一个完整项目把模型、视图、模板之间的协作关系跑通你才算真正理解了 Django。之后再接触 DRFDjango REST Framework做接口开发会轻松很多。2.1 为什么要先理解请求流转因为后面的所有代码都是在回答三个问题用户访问哪个地址URL 配置这个地址对应的处理逻辑是什么视图处理完之后展示什么模板把这三个问题先装进脑子再看代码就不会迷路。3. 环境准备Python 虚拟环境与 Django 安装开始写代码前先把环境准备好。注意我下面所有的操作都以 Windows/macOS/Linux 通用命令行方式为例版本相关的细节会重点说明。Django 主体版本以实际安装为准本文演示的思路适用于 Django 4.x / 5.x 以上版本。3.1 Python 版本选择Django 是一个纯 Python 编写的框架所以你的机器上必须先有 Python。建议安装 Python 3.10 及以上版本越新越好。一个重要的经验是不要使用系统自带的 Python 来搞 Web 开发尤其是 macOS 和 Linux 用户。系统 Python 通常被系统工具依赖直接往里面安装第三方包容易引发权限问题或依赖冲突。推荐从 Python 官网下载安装包安装时勾选“Add Python to PATH”这样终端里才能直接运行 python 和 pip。安装完成后打开终端或命令行工具验证版本python --version如果提示找不到命令检查环境变量是否配置正确。Windows 用户如果安装了多个 Python 版本可能需要用py -3 --version来指定版本。3.2 为什么必须使用虚拟环境虚拟环境是 Python 开发里最基础、也最容易被忽略的一环。简单说虚拟环境就是一个独立的 Python 运行目录。这个目录里安装的第三方包只对当前项目生效不会污染全局环境。这有什么用举个例子你有一个项目 A 用的是 Django 4.2另一个项目 B 用的是 Django 5.2。如果没有虚拟环境你只能在全局环境里安装一个版本换项目就要卸载重装非常痛苦。有了虚拟环境A 和 B 各自拥有独立的依赖包互不干扰。更关键的是部署到服务器时虚拟环境可以帮你清晰地导出依赖清单requirements.txt别人拿到清单就能复现你的环境。这一点在团队协作和生产部署中极其重要。3.3 创建虚拟环境并安装 Django打开终端进入你想存放项目的目录执行# 创建虚拟环境 python -m venv venv这条命令会在当前目录下生成一个名为venv的文件夹里面是独立的 Python 解释器和包管理工具。然后激活虚拟环境Windowsvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活成功后命令行提示符前面会出现(venv)标志。这时候你执行的 python、pip 命令都指向虚拟环境内部的解释器。接下来安装 Djangopip install django如果想指定版本可以写pip install django4.2.16具体版本以你的项目需求为准不要盲目追求最新。新版本虽然功能更新但第三方插件的兼容性不一定同步。验证安装python -m django --version能正常输出版本号说明安装成功。这里我想多说一句很多新手在当前目录下执行pip install django然后发现命令找不到或者安装后仍然提示ModuleNotFoundError。绝大多数原因都是没有激活虚拟环境pip 安装到了全局环境而当前终端却指向虚拟环境。所以激活虚拟环境后再执行安装命令这是铁律。3.4 IDE 选择PyCharm 还是 VS Code这个问题经常被问起。我的看法是PyCharm专业版对 Django 支持极好有模板补全、URL 跳转、ORM 调试等功能新手用起来省心。VS Code免费、轻量配合 Python 插件也可以获得不错的开发体验。选哪个不关键关键是你愿意花时间熟悉它。我的建议是新手先从 PyCharm Community社区版开始等你对 Django 的项目结构有了完整认识再换 VS Code 也完全来得及。社区版虽然没有 Django 专属功能但作为代码编辑器配合终端运行命令体验也足够流畅。4. 创建项目和应用理解 project 与 app 的分工环境准备好了接下来创建 Django 项目。这里有一个很重要的概念需要先弄清楚Project项目和App应用是两回事。Project一个网站整体的配置入口。它包含全局的 URL 配置、settings 配置、数据库配置等。一个 Project 可以承载多个 App。App一个功能模块。比如一个博客网站会有用户管理 App、文章管理 App、评论管理 App。每个 App 都是相对独立的业务模块。这个设计的好处是复用性。你现在做的电商项目里的“商品管理 App”以后做二手交易平台时可以直接复制过去只要稍作修改就能用。4.1 创建项目在虚拟环境激活的状态下执行django-admin startproject myproject这条命令会生成一个myproject文件夹内部结构如下myproject/ ├── manage.py └── myproject/ ├── __init__.py ├── settings.py ├── urls.py └── wsgi.py初学者容易搞混的是外层myproject和里层myproject名字一样。外层myproject/项目根目录。manage.py在这里以后大部分命令行操作都要在这个目录下执行。内层myproject/项目配置文件包。settings.py是全局配置urls.py是根路由配置wsgi.py是部署时用的入口文件。为了减少混淆建议你给项目起一个有意义的名字比如blog_project、shop_project。4.2 创建应用执行python manage.py startapp todo这会生成一个todo文件夹里面有todo/ ├── migrations/ ├── __init__.py ├── admin.py ├── apps.py ├── models.py ├── tests.py └── views.py每一个文件都有明确职责models.py定义数据模型。views.py业务逻辑处理。admin.py把模型注册到后台管理。migrations/数据库迁移记录由命令自动生成不需要手动编辑。创建完 App 后必须手动把它注册到项目里否则 Django 不知道这个 App 的存在。4.3 注册 App 到 INSTALLED_APPS打开myproject/settings.py找到INSTALLED_APPS列表加一行# 文件路径myproject/settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, todo, # 新增 ]这里一定不要漏掉。遗忘注册 App 的话后面运行迁移命令时Django 完全不会创建这个应用的数据表而且不会报任何错误排查起来非常隐蔽。4.4 启动开发服务器验证在项目根目录包含manage.py的目录执行python manage.py runserver看到类似下面的输出说明项目创建成功Starting development server at http://127.0.0.1:8000/浏览器打开这个地址能看到 Django 的默认欢迎页就是那个火箭图标页面。此时可以顺便测试一下如果没有注册 App 直接启动服务器不会有任何问题但一旦执行迁移命令你会看到它只处理了内置 App 的迁移自己创建的 todo 应用完全消失。这就是“不报错但数据表缺失”的经典场景。5. 关键配置文件 settings.py时区、语言、数据库项目能跑起来之后先别急着写代码。有一个文件你必须花时间仔细理解它就是settings.py。这个文件控制着 Django 项目的全局行为。5.1 基本信息配置打开settings.py重点关注以下几项。SECRET_KEYDjango 加密签名用的密钥涉及 Session、CSRF、密码重置等功能。生产环境必须把这个值换成一个随机的长字符串并且不要提交到代码仓库。DEBUG调试模式开关。开发时必须为True这样出错时会显示详细的堆栈信息。但部署到生产环境必须改成False否则用户能看到你的源代码路径、数据库配置甚至局部代码片段。ALLOWED_HOSTS允许访问站点的域名列表。DEBUG True时可以为空但部署阶段必须写入你的域名或服务器 IP否则会报DisallowedHost错误。5.2 语言与时区Django 默认语言是英语默认时区是 UTC。对于中文项目强烈建议修改为# 文件路径myproject/settings.py LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai USE_TZ True这里有一个需要注意的细节USE_TZ True表示数据库存储时间时使用 UTC 时间展示时自动转换为当前时区。如果你的项目不需要处理跨时区用户可以保留这个默认设置如果你确定所有用户都在同一时区也可以改成False但一般不建议。改完语言和时区后重启开发服务器进入 Django 后台时你会发现界面变成了中文。这是一个非常直观的“配置生效”体验。5.3 数据库配置Django 默认使用 SQLite 数据库配置文件长这样# 文件路径myproject/settings.py DATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } }初学者完全不需要急着换数据库。SQLite 零配置、文件型、随项目走非常适合开发和测试。等你把业务逻辑全部跑通了部署前再切换成 MySQL 或 PostgreSQLDjango 的 ORM 层保证了你绝大部分代码不需要变动。以后切换到 MySQL 时配置会变成DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: your_database_name, USER: your_user, PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, } }不理解 ORM 的话你会觉得切换数据库是件大事。理解了之后就会发现Django 把底层差异全部隔离了切换数据库只是改配置而已。5.4 静态文件配置Django 处理 CSS、JS、图片这些静态文件需要指定目录。默认配置里有一段STATIC_URL static/STATIC_URL是浏览器访问静态文件的 URL 前缀。实际项目开发中你通常还要加上一个专门存放静态文件的目录STATICFILES_DIRS [ BASE_DIR / static, ]然后在项目根目录手动创建一个static文件夹把 CSS 和 JS 放进去。这里有个新手经常踩的坑明明把style.css放在了项目根目录的static文件夹里但页面加载不出来。原因就是只配置了STATIC_URL没有配置STATICFILES_DIRS。Django 根本不知道去哪里找这个静态文件夹。6. 第一个真实功能用 ORM 定义任务数据模型理解了配置之后我们开始写第一个真实功能。我选了“任务管理Todo”这个案例因为它足够小但覆盖了模型、迁移、后台管理、视图、模板五个核心环节——没有任何多余的“魔法”。6.1 定义模型打开todo/models.py定义一个任务类# 文件路径todo/models.py from django.db import models class Task(models.Model): title models.CharField(任务标题, max_length200) description models.TextField(任务描述, blankTrue) completed models.BooleanField(是否完成, defaultFalse) created_at models.DateTimeField(创建时间, auto_now_addTrue) def __str__(self): return self.title class Meta: verbose_name 任务 verbose_name_plural 任务这段代码做了四件事继承models.Model告诉 Django 这是一个数据库表。定义四个字段标题字符串、描述长文本、是否完成布尔值、创建时间自动记录。定义__str__方法让后台列表显示任务标题而不是Task object。定义Meta给模型起中文名。关于字段类型先记住三个最常用的CharField短文本必须指定max_length。TextField长文本不限制长度。BooleanField布尔值常用作状态开关。6.2 生成数据库迁移模型定义好之后数据库里还没有对应的表。需要通过两步命令同步python manage.py makemigrations python manage.py migratemakemigrations会生成一个迁移文件位置在todo/migrations/下记录你对模型的创建或改动。migrate负责把迁移记录真正执行到数据库完成建表。执行完第一条命令后你会看到类似输出Migrations for todo: todo/migrations/0001_initial.py - Create model Task如果这一步什么都没输出说明 Django 没检测到模型变化。多数情况是因为 App 没注册到INSTALLED_APPS回去检查一下。6.3 认识 Django ORM 的基础增删改查Django ORM 的价值在于你不写 SQL 也能完成数据库操作。在虚拟环境里执行python manage.py shell进入交互式环境后我们可以测试几个核心操作# 新增 task Task.objects.create(title学习 Django, description完成大师班第一课) task.pk # 输出1主键自动生成 # 查询所有 tasks Task.objects.all() print(tasks) # 条件查询 unfinished Task.objects.filter(completedFalse) # 修改 task.completed True task.save() # 删除 task.delete()这就是 ORM 最核心的四个动作增、查、改、删。以后你在视图里写的大部分逻辑本质上都是这几行代码的变体。6.4 注册到 Django Admin 后台Django 自带一个可视化数据管理后台这是很多其他框架不具备的能力。注册模型后你就能在后台直接维护任务数据不需要自己写管理页面。打开todo/admin.py写入# 文件路径todo/admin.py from django.contrib import admin from .models import Task admin.register(Task) class TaskAdmin(admin.ModelAdmin): list_display (title, completed, created_at) list_filter (completed,) search_fields (title,)这里配置了三个实用功能list_display列表页显示哪些字段。list_filter右侧按“是否完成”筛选。search_fields支持按标题搜索。启动服务器python manage.py runserver访问http://127.0.0.1:8000/admin/第一步要先登录。Django 需要你创建超级管理员在项目目录执行python manage.py createsuperuser按提示输入用户名、邮箱可跳过、密码。登录后台后你会看到“认证和授权”以及“任务管理”两个模块点进“任务”就能操作刚才生成的表数据。到这里你已经完成了 Django 数据层的完整闭环定义模型 → 迁移建表 → 后台管理。这一步对新手来说是里程碑式的收获数据库、管理后台、数据增删改查全部搞定全程没有手写一行 SQL。7. 视图、URL 与模板让数据在页面上“活”起来数据已经在后台可以管理了但普通用户不能也不需要进入后台。下一步是写一个页面把这些任务展示出来并允许用户完成标记。7.1 创建第一个视图函数打开todo/views.py写入# 文件路径todo/views.py from django.shortcuts import render from .models import Task def task_list(request): tasks Task.objects.all().order_by(-created_at) return render(request, todo/task_list.html, {tasks: tasks})代码逻辑很简单查询所有任务按创建时间倒序排列交给模板渲染。这里需要注意一个约定render函数的第二个参数是模板路径Django 默认在项目根目录下的templates文件夹里寻找模板。为了让不同 App 的模板不互相覆盖惯例是templates/应用名/模板名.html这样组织。7.2 配置路由 URLDjango 里的 URL 配置分成两层根路由和应用路由。先在myproject/urls.py里配置总路由# 文件路径myproject/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(todo.urls)), ]然后在todo/目录下新建一个urls.py文件# 文件路径todo/urls.py from django.urls import path from . import views urlpatterns [ path(, views.task_list, nametask_list), ]这里的设计思路是项目的根路由只管把/admin/和业务功能分开具体业务模块内部的 URL 由每个 App 自己管理。项目变大后每个 App 的路由相互独立不会杂乱无章。7.3 编写模板文件在项目根目录创建templates/todo/task_list.html!-- 文件路径templates/todo/task_list.html -- !DOCTYPE html html langzh-hans head meta charsetUTF-8 title任务清单/title /head body h1我的任务/h1 ul {% for task in tasks %} li {% if task.completed %} ✅ {{ task.title }}已完成 {% else %} {{ task.title }} {% endif %} /li {% empty %} li暂无任务/li {% endfor %} /ul /body /html这里用到了两个最常用的 Django 模板语法{% for task in tasks %}循环遍历视图传入的列表。{% if task.completed %}条件判断。{% empty %}当列表为空时显示提示。刷新浏览器访问http://127.0.0.1:8000/你会看到任务列表已经渲染在页面上。刚才在后台或 shell 里创建的数据现在全部展示出来了。7.4 完整示例实现“标记完成”功能静态展示数据还不够一个真实的 Web 应用必须能响应用户操作。我们在列表后面加上一个“完成”按钮。修改路由和视图# 文件路径todo/urls.py from django.urls import path from . import views urlpatterns [ path(, views.task_list, nametask_list), path(complete/int:task_id/, views.complete_task, namecomplete_task), ]视图函数# 文件路径todo/views.py from django.shortcuts import render, get_object_or_404, redirect from .models import Task def task_list(request): tasks Task.objects.all().order_by(-created_at) return render(request, todo/task_list.html, {tasks: tasks}) def complete_task(request, task_id): task get_object_or_404(Task, pktask_id) task.completed True task.save() return redirect(task_list)模板里加上链接li {% if task.completed %} ✅ {{ task.title }}已完成 {% else %} {{ task.title }} a href{% url complete_task task.id %}完成/a {% endif %} /li现在点击“完成”任务状态会更新页面刷新后显示为已完成。这个简单的交互背后完整走了一遍“URL → 视图 → 模型更新 → 重定向到列表”的请求流程。它是所有业务功能的缩影。以后你做更复杂的系统比如订单支付状态更新、文章发布、用户关注底层全是这个模式。7.5 加一点样式静态文件处理为了让页面不至于太朴素可以加一个简单的 CSS 文件。在项目根目录创建static/css/style.css/* 文件路径static/css/style.css */ body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; line-height: 1.6; color: #333; } a { color: #007bff; text-decoration: none; }修改模板引入静态文件!-- 文件路径templates/todo/task_list.html -- {% load static %} !DOCTYPE html html langzh-hans head meta charsetUTF-8 title任务清单/title link relstylesheet href{% static css/style.css %} /head body !-- 其他内容不变 -- /body /html注意两件事第一模板里必须先用{% load static %}加载静态文件标签第二settings.py里必须已经配置了STATICFILES_DIRS否则样式文件找不到。刷新页面样式生效。到这里一个没有任何脚手架、不带任何多余依赖的完整 Django 应用——数据模型、后台管理、列表展示、状态更新、静态样式——已经全部跑通了。8. 常见问题与排查思路初学者遇到报错时第一反应往往是“我代码写错了”但实际上大量错误来自环境、配置和路径问题。这里整理我实践过程中最常碰到的几个问题供你排查时参考。问题现象可能原因排查方式解决方案django-admin不是内部或外部命令Django 未安装或未激活虚拟环境运行pip show django检查是否安装激活虚拟环境执行pip install djangoModuleNotFoundError: No module named djangoPython 解释器路径不对安装在全局环境终端输入python -c import django; print(django.__version__)验证确保当前环境是虚拟环境重新安装 DjangoDisallowedHost错误访问域名不在ALLOWED_HOSTS中查看报错信息中的域名把域名或 IP 加入ALLOWED_HOSTSmakemigrations提示“没有变化”App 未注册到INSTALLED_APPS打开 settings.py 检查在INSTALLED_APPS中加入应用名称后台页面加载不出 CSSSTATICFILES_DIRS未配置浏览器开发者工具检查请求 URL配置静态文件目录模板中使用{% load static %}页面显示Page not foundURL 路径错误或未 include 应用路由检查myproject/urls.py注册应用路由到根路由数据库查询数据为空未执行迁移或未创建数据后台检查数据表是否有记录执行makemigrations和migrate保存中文乱码数据库编码不支持 UTF-8如果是 MySQL检查库表字符集统一为 utf8mb4 编码一个重要习惯报错时不要只看最后一行从日志最底部往上翻找到第一个File ...开头的行那才是真正出错的位置。Django 的错误页面在DEBUGTrue时会直接告诉你文件名和行号大多数时候问题都能快速定位。9. 最佳实践与生产环境部署提醒项目跑通只是第一步。如果想把它变成一个能上线、可维护、能交付的真实应用下面这些工程层面的建议请认真对待。9.1 环境隔离与依赖管理虚拟环境是开发阶段的保障但回到一台新电脑或部署服务器时你的项目必须能快速复制环境。建议在项目根目录生成依赖清单pip freeze requirements.txt别人拿到你的项目后只需要python -m venv venv source venv/bin/activate pip install -r requirements.txt就能完整复现环境。注意pip freeze会导出虚拟环境里所有的包包括间接依赖。如果希望更精准可以用pipreqs之类的工具只导出项目直接使用的依赖但对于个人项目来说pip freeze已经足够。9.2 配置文件分离与敏感信息保护把所有配置写在一个settings.py里一开始没问题一旦项目上线问题就来了开发环境的DEBUG要开生产环境要关开发用 SQLite生产用 MySQL两个环境的SECRET_KEY也不能一样。业界常用的做法是设置环境变量或者把配置拆分成多个文件。最轻量的方案是利用环境变量覆盖import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-only-key) DEBUG os.environ.get(DJANGO_DEBUG, True) True这样同一个代码库不同的服务器设置不同的环境变量就能跑出不同的配置行为。更重要的是生产环境的SECRET_KEY和数据库密码绝不能硬编码提交到 Git 仓库。9.3 生产环境部署前的检查清单如果你准备把项目部署到云服务器比如常见的宝塔面板环境上线前必须确认DEBUG False否则用户能看到详细报错信息。ALLOWED_HOSTS配置为你的域名或服务器 IP。SECRET_KEY更换为随机值不要用默认值。使用真实数据库MySQL 或 PostgreSQL而不是 SQLite。收集静态文件python manage.py collectstatic这条命令会把所有 App 内的静态文件统一收集到一个目录方便 Nginx 托管。使用 Gunicorn 或 uWSGI 作为应用服务器而不是 Django 自带的 runserver。开发服务器性能极低只适合本机调试。这一步涉及到的知识量比较大本文先给出方向。后续如果用宝塔面板部署 Django整个流程可以拆成一篇文章专门讲。9.4 继续深入的方向学完这篇内容你已经掌握了 Django 项目的地基。接下来建议按照这个顺序继续精进Django 模板进阶模板继承、自定义过滤器、context processor。表单系统用 Django Form 处理用户提交校验数据安全问题。认证与权限用户注册、登录、修改密码、分组权限。Django REST Framework前后端分离开发、API 设计。部署实战使用 Nginx Gunicorn 部署到云服务器配置 HTTPS。不要试图一次学完所有内容Web 开发是一个实践性极强的领域。把本文的任务管理应用做完、部署上线、让朋友能用你的域名注册账号你对 Django 的掌握程度会远超那些只刷教程的人。回到本文开头的那句话Django 是构建真实 Web 应用的主框架它的门槛不在写代码而在理解工程结构。当你理解了 Project、App、Model、View、Template 是怎么配合的剩下的就是一件需要时间打磨的手艺活。你现在的第一段代码已经跑起来了离一个真实应用只差“继续写完”这步而已。
