大家在学习 Django 的时候最常见的问题不是“Django 难不难”而是“资料太多不知道先学什么”。网上关于 Django 的教程、视频、源码解析铺天盖地但大部分新手都卡在同一个地方跟着教程敲完了代码却不知道这些文件之间是什么关系更不知道下一步该往哪个方向深入。本文想帮你抓住 Django 的一条主线从环境搭建开始一步步完成一个最基础的 Web 应用让你真正理解 Django 的项目结构、请求处理流程和数据模型设计思路。这条主线捋顺之后后续学习 DRF、Celery、Channels 等进阶内容都会轻松很多。如果你是刚接触 Python Web 开发的初学者或者已经看过一些 Django 教程但总觉得没形成体系这篇文章都非常适合你。我会尽量少讲抽象概念多给可运行、可验证的代码示例每一段代码都说明放在哪个文件、起什么作用。最后还会补充常见报错和工程上的建议方便你在独立开发时少踩坑。1. Django 是什么它解决什么问题先不急着写代码我们花几分钟把 Django 的定位搞清楚。很多初学者一上来就去看中间件、信号、自定义管理器这些进阶特性结果被绕晕了。实际上Django 的核心价值可以概括为一句话它让你用最少的重复劳动快速构建一个基于数据库的 Web 应用。1.1 Django 的本质Web 框架Web 框架解决的核心问题是“接收 HTTP 请求 → 处理业务逻辑 → 返回 HTTP 响应”这一整套流程。如果没有框架你需要自己处理 socket 连接、HTTP 协议解析、URL 路由匹配、请求参数提取、数据库连接、HTML 模板渲染……这些工作量大且容易出错。Django 把这些通用能力都封装好了你只需要关注两件事定义 URL 和视图函数或者类视图的映射关系。用 Python 代码处理业务逻辑把数据交给模板去渲染。换句话说Django 帮你把“Web 服务器该干的活”和“业务开发者该干的活”做了清晰的分工。1.2 Django 的 MTV 架构很多人听说过 MVC也就是 Model-View-Controller。Django 虽然也遵循类似思想但它的官方术语是 MTVMModel数据模型层负责与数据库交互。在 Django 中你通过 Python 类定义表结构Django 负责生成 SQL 并操作数据库。TTemplate模板层负责页面的展示。模板中可以使用类似 HTML 的语法也能嵌入变量、循环、判断等逻辑。VView视图层负责业务逻辑。视图接收 HTTP 请求从 Model 中取数据或调用外部接口把数据交给 Template 渲染最终返回 HTTP 响应。可能你还是觉得有点抽象。没关系我们可以用一张简化的请求流程图来理解浏览器发起请求 ↓ Django 根据 URL 找到对应的 View视图 ↓ View 调用 Model 操作数据库读/写 ↓ View 把数据传给 Template 渲染 HTML ↓ Django 把响应返回给浏览器新手最容易混淆的地方是Django 的“视图”更像 MVC 里的 Controller而不是 MVC 里的 View。这个称呼差异不用太纠结只要记住“视图负责业务逻辑”就够了。1.3 为什么 Django 适合新手和企业开发Django 的一大特点是“内置电池”。一个完整的 Django 项目中默认包含自带 Admin 后台管理系统可以通过 Web 页面直接管理数据库记录。自带 ORM对象关系映射不用手写 SQL 就能完成大部分增删改查。自带表单处理、用户认证、会话管理、CSRF 防护等常见功能。拥有成熟的迁移机制修改模型后可以自动生成数据库变更脚本。这些内置功能让 Django 在快速原型开发和企业级项目中都很有竞争力。即使你最终不使用 Admin 后台它在开发调试阶段也能极大提升效率。2. 环境准备与版本说明开始写 Django 之前我们需要把开发环境准备好。这里不会指定某一个绝对必须使用的版本因为不同项目对 Python 和 Django 的版本要求可能不同但为了让新手能顺利跑通示例我会给出一个常见的组合并说明调整思路。2.1 Python 环境准备Django 是 Python 的第三方库所以首先需要确保你的电脑上安装了 Python。建议使用 Python 3.8 及以上版本因为新版本提供了更好的语法和性能支持Django 官方在新版本中也逐步放弃了对旧版 Python 的兼容。在命令行中检查 Python 版本python --version或者在某些系统中是python3 --version如果提示找不到命令你需要先安装 Python。安装完成后建议顺手安装pipPython 包管理工具。Python 3.4 以上版本默认自带 pip可以直接使用pip --version2.2 创建虚拟环境虚拟环境是 Python 开发中非常重要的一个习惯。每个项目都有自己的依赖库避免不同项目之间因为 Django 版本不同而互相干扰。在 Windows 上创建虚拟环境# 进入你的项目目录例如 django_project mkdir django_project cd django_project python -m venv venv在 macOS 或 Linux 上mkdir django_project cd django_project python3 -m venv venv然后激活虚拟环境。Windows 下venv\Scripts\activatemacOS 或 Linux 下source venv/bin/activate激活成功后命令行提示符前面会出现(venv)字样。之后安装的 Python 包都会进入这个环境不会污染全局环境。关于虚拟环境新手常见的两个误区忘记激活虚拟环境直接pip install django结果 Django 装到了全局环境里。换了终端窗口后虚拟环境没有被激活导致python manage.py命令找不到 Django。遇到“ModuleNotFoundError: No module named django”这类报错时第一反应就应该是检查虚拟环境是否激活、当前环境是否安装了 Django。2.3 安装 Django在激活的虚拟环境中使用 pip 安装 Djangopip install django这会安装最新稳定版本的 Django。如果你希望安装指定版本可以写成pip install django4.2.0安装完成后验证版本python -m django --version如果能看到类似4.2.0或者5.x的版本号说明安装成功。本文的示例基于 Django 4.x/5.x 的常见用法如果你的系统是其他版本大部分代码仍然适用但个别配置写法可能需要微调。2.4 IDE 与项目结构建议Django 开发不强制要求使用某个特定 IDE。你可以选择PyCharm 专业版对 Django 支持最好有模板补全、ORM 提示、调试工具。VS Code免费且轻量安装 Python 插件后也很好用。普通文本编辑器 命令行适合熟悉命令行操作的同学。本文的示例以命令行操作为主代码文件放在项目目录下你也可以直接用自己的 IDE 打开项目目录来查看和编辑文件。3. 创建 Django 项目理解项目骨架环境准备好之后我们正式进入 Django 主线。这一步会创建一个 Django 项目并解释项目生成出来的各个文件有什么用。3.1 创建项目在虚拟环境激活状态下进入你要存放项目的目录执行django-admin startproject myproject这条命令会创建一个名为myproject的目录目录内部结构大致如下myproject/ manage.py myproject/ __init__.py settings.py urls.py asgi.py wsgi.py我们需要区分两个myproject外层myproject是项目的根目录它与manage.py同级。内层myproject是一个 Python 包里面存放 Django 项目的主配置。manage.py是 Django 项目的管理脚本。后面我们执行的大多数命令都需要通过它来调用比如启动开发服务器、创建应用、执行数据库迁移等。内层myproject中的几个文件settings.py项目的总配置文件包括数据库配置、应用注册、模板路径、静态文件路径、时区、语言等。urls.pyURL 路由配置文件浏览器请求的 URL 会在这里找到对应的视图函数。asgi.py和wsgi.py部署时使用的入口文件分别对应异步和同步的 Web 服务器接口新手阶段不需要深入了解。__init__.py标识这个目录是一个 Python 包。3.2 启动开发服务器项目创建完成后进入项目根目录运行cd myproject python manage.py runserver如果一切正常命令行会提示Starting development server at http://127.0.0.1:8000/我们在浏览器中访问 http://127.0.0.1:8000/就会看到 Django 的默认欢迎页面页面上会显示一个火箭图标并提示“The install worked successfully! Congratulations!”这个页面说明你的 Django 项目已经成功运行。需要特别提醒的是Django 自带的这个服务器是开发服务器适合本地调试不能直接用于生产环境部署。在生产环境我们需要使用 Gunicorn、uWSGI 等 WSGI 服务器配合 Nginx 反向代理。这个话题后面可以单独写一篇部署教程。3.3 创建应用AppDjango 项目和应用是两个不同的概念。一个项目可以包含多个应用每个应用负责一个相对独立的功能模块。比如一个电商网站项目中可能包含users应用负责用户管理orders应用负责订单管理products应用负责商品管理。创建应用的命令python manage.py startapp article这里我们用article作为示例应用它是一个简单的文章模块。命令执行后项目根目录下会多出一个article目录结构如下article/ __init__.py admin.py apps.py models.py tests.py views.py migrations/ __init__.py这些文件的作用models.py定义数据模型也就是数据库表结构。views.py编写视图函数或类视图处理用户请求。admin.py把模型注册到 Django Admin 后台方便管理数据。apps.py应用的配置文件里面包含应用名称等信息。tests.py编写测试用例。migrations/存放数据库迁移文件。此时我们还需要把这个应用注册到项目中。打开myproject/settings.py找到INSTALLED_APPS列表把article加进去# 文件路径myproject/settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, article, # 新增这一行 ]如果不注册应用Django 虽然不会立刻报错但后面你可能会遇到No installed app with label article之类的错误或者模板、迁移命令找不到这个应用。所以每次创建一个新应用第一件事就是把它注册到INSTALLED_APPS中。4. 编写第一个视图从 URL 到页面的完整流程理解了项目结构后我们开始写第一个真正意义上的页面。这一步会贯穿 Django 最核心的请求流程URL → View → HTTP 响应。4.1 编写视图函数打开article/views.py写入# 文件路径article/views.py from django.http import HttpResponse def home(request): return HttpResponse(Hello, Django!)这是一个最简单的视图函数。request参数是 Django 封装好的 HTTP 请求对象包含了请求头、请求方法、请求参数等信息。这里我们没有使用request只是返回一个纯文本响应。4.2 配置 URL 路由接下来我们需要告诉 Django当用户访问某个 URL 时应该调用哪个视图函数。在article应用目录下新建一个urls.py文件写入# 文件路径article/urls.py from django.urls import path from . import views urlpatterns [ path(, views.home, namehome), ]然后修改项目主路由myproject/urls.py把应用的 URL 配置包含进来# 文件路径myproject/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(article.urls)), ]这里的关键是include函数。它的作用是把article应用下的urls.py文件中的 URL 配置“挂载”到主路由中。这样当用户访问根路径/时Django 会进入article/urls.py进行匹配找到views.home。4.3 验证运行效果保存文件后如果开发服务器还在运行它会自动加载新的代码。在浏览器中访问 http://127.0.0.1:8000/ 你应该能看到页面显示Hello, Django!。此时整个请求流程是浏览器请求 http://127.0.0.1:8000/ ↓ Django 读取 myproject/urls.py ↓ 匹配到 include(article.urls) ↓ 进入 article/urls.py ↓ 匹配到 path(, views.home) ↓ 执行 views.home 函数 ↓ 返回 HttpResponse(Hello, Django!)这个过程看似简单但它是 Django 一切功能的基础。无论将来你写多复杂的项目都是从这条链路延伸出去的。5. 使用模板与静态文件直接在视图里返回字符串虽然简单但真实的页面不可能都是纯文本。我们需要使用 HTML 模板来渲染页面并在页面中引入 CSS、JavaScript 等静态文件。5.1 配置模板目录Django 默认会从每个应用下的templates目录中查找模板文件所以我们可以在article应用下创建一个templates目录。然后新建一个 HTML 文件!-- 文件路径article/templates/home.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 titleDjango 新手教程/title /head body h1欢迎来到 Django 世界/h1 p这是通过模板渲染出来的页面。/p /body /html为了让模板中使用静态文件我们通常还会在应用目录下创建static目录并在模板中通过{% load static %}标签加载静态文件。不过这一步我们先不展开等用到的时候再演示。5.2 修改视图使用模板接下来修改article/views.py让它使用模板来渲染页面# 文件路径article/views.py from django.shortcuts import render def home(request): return render(request, home.html)render函数是 Django 中非常常用的一个快捷函数。它的作用是根据传入的模板名称在应用的templates目录下找到对应的模板文件。将模板渲染成 HTML 字符串。返回一个包含该 HTML 的HttpResponse对象。现在刷新浏览器你会看到页面显示“欢迎来到 Django 世界”并且页面的标题也发生了变化。5.3 在模板中传递变量模板的意义不只是静态 HTML更重要的是把后端的数据动态渲染到页面上。我们来演示如何把 Python 变量传到模板中。修改视图# 文件路径article/views.py from django.shortcuts import render def home(request): name 小明 articles [ Django 入门教程, Python 基础语法, Web 开发实战, ] context { name: name, articles: articles, } return render(request, home.html, context)这里我们定义了一个context字典里面包含了name和articles两个变量。Django 的模板语法使用双大括号{{ }}输出变量使用{% %}执行循环或判断等逻辑。修改模板文件!-- 文件路径article/templates/home.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 titleDjango 新手教程/title /head body h1你好{{ name }}/h1 ul {% for article in articles %} li{{ article }}/li {% endfor %} /ul /body /html刷新页面后你会看到输出你好小明 1. Django 入门教程 2. Python 基础语法 3. Web 开发实战这个示例展示了 Django 模板最核心的两个功能变量输出和循环遍历。后续你还会用到if条件判断、模板过滤器、模板继承等特性但核心思路始终是把 Python 对象传入模板然后按模板语法渲染。6. 模型Model与数据库操作现在我们已经掌握了从 URL 到视图再到模板的流程。但一个 Web 应用的数据通常是动态变化的比如用户发布文章、修改评论、上传文件这些数据需要保存到数据库中。Django 的 ORM 让我们可以用 Python 代码操作数据库而不需要直接写 SQL。6.1 定义模型打开article/models.py定义一个简单的文章模型# 文件路径article/models.py from django.db import models class Article(models.Model): title models.CharField(max_length200, verbose_name标题) content models.TextField(verbose_name内容) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) def __str__(self): return self.title这里我们定义了一个Article类它继承自models.Model。Django 会把这个类映射为数据库中的一张表类属性对应数据库字段。各字段的含义CharField字符串类型max_length200表示最大长度 200 个字符适合存储标题。TextField长文本类型适合存储文章正文。DateTimeField日期时间类型auto_now_addTrue表示在对象第一次创建时自动填入当前时间。__str__方法不是必须的但它能在 Django Admin 后台和命令行中更友好地显示对象。比如在后台列表中默认会显示Article object定义__str__后就会显示文章标题。6.2 生成数据库迁移文件模型定义好之后我们需要让 Django 根据模型生成数据库表。这里 Django 引入了“迁移”migration的机制。执行命令python manage.py makemigrations这个命令会扫描项目中的模型变化并在应用的migrations目录下生成迁移文件。迁移文件记录了模型的变化历史比如你新增了Article模型就会生成一个类似0001_initial.py的文件。然后执行python manage.py migrate这个命令会把迁移文件中记录的操作同步到数据库。Django 默认使用 SQLite 数据库这是一个轻量级的文件型数据库不需要额外安装任何数据库服务非常适合开发环境。执行完migrate后项目中会多出db.sqlite3文件这就是 SQLite 的数据库文件。6.3 通过 Django Shell 操作数据库我们可以通过 Django 提供的交互式命令行来测试数据操作。运行python manage.py shell然后在交互环境中输入from article.models import Article # 创建一条数据 Article.objects.create(title我的第一篇文章, content这是文章内容) # 查询所有数据 articles Article.objects.all() print(articles) # 获取第一条数据 article Article.objects.first() print(article.title) print(article.content) print(article.created_at) # 更新数据 article.title 修改后的文章标题 article.save() # 删除数据 article.delete()这些命令的执行流程Article.objects.create()向数据库插入一条记录。Article.objects.all()查询所有记录返回一个 QuerySet。Article.objects.first()返回第一条记录。修改对象属性后调用save()会更新数据库。调用delete()会删除记录。Django ORM 的核心优势在于你不必关心当前使用的是 SQLite 还是 MySQL大部分查询代码都保持一致。从开发环境切换到生产环境时只需要修改settings.py中的数据库配置代码几乎不用改。需要注意这里的delete()是一个真实删除操作会直接从数据库中移除记录。在生产环境执行删除操作前一定要确认操作范围必要的时候先备份数据库。6.4 在视图中使用模型数据接下来我们把数据库中的数据展示到页面上。修改视图# 文件路径article/views.py from django.shortcuts import render from .models import Article def home(request): name 小明 articles Article.objects.all() context { name: name, articles: articles, } return render(request, home.html, context)模板保持不变。现在刷新页面你会发现页面中显示的不再是我们在视图里硬编码的列表而是数据库中实际存在的文章标题。如果你的Article表里没有数据页面就是空的。你可以通过刚才的shell命令创建几条数据或者等下一节使用 Admin 后台来添加。7. 使用 Django Admin 后台管理数据Django Admin 是 Django 自带的后台管理系统它可以根据你在admin.py中注册的模型自动生成增删改查页面。它特别适合开发阶段的内部管理和数据调试。7.1 创建超级用户运行python manage.py createsuperuser按照提示输入用户名、邮箱可以跳过和密码。新手经常遇到的坑是密码太简单会提示验证失败比如“The password is too similar to the username.”。如果想强制使用简单密码可以输入y继续但其实在真实项目中密码强度很重要建议设置一个复杂一点的密码。7.2 注册模型打开article/admin.py写入# 文件路径article/admin.py from django.contrib import admin from .models import Article admin.register(Article) class ArticleAdmin(admin.ModelAdmin): list_display [title, created_at] search_fields [title]这里我们使用了admin.register装饰器来注册模型。list_display指定后台列表中显示哪些字段search_fields指定可以通过哪些字段进行搜索。7.3 使用后台启动开发服务器python manage.py runserver在浏览器中访问 http://127.0.0.1:8000/admin/ 使用刚才创建的超级用户登录。登录成功后你会看到Article模型的管理入口。点击进去就能看到文章列表还可以点击“ADD ARTICLE”按钮添加新文章点击文章标题进入编辑页面底部有删除按钮。对于新手来说Admin 后台是验证模型定义和快速录入数据的好工具。它暴露了 Django 的一大核心优势很多常见的后台管理功能Django 已经替你写好了。8. 常见问题与排查思路初学者在搭建 Django 项目的过程中常常会遇到一些看起来很吓人、实际很简单的报错。下面列举几个最常见的场景和排查思路。问题现象常见原因解决思路ModuleNotFoundError: No module named django没有安装 Django或虚拟环境未激活检查pip show django确认命令在激活的虚拟环境中执行File manage.py, line 17, in main ... ImportErrorPython 版本过低或者 Django 版本与 Python 版本不兼容检查python --version和python -m django --versionYou have unapplied migrations模型变更后没有执行migrate运行python manage.py migrate页面显示 404URL 路由配置错误或者访问的路径不正确检查urls.py中的path是否正确注意是否缺少include页面显示 DisallowedHost 错误ALLOWED_HOSTS配置不包含当前域名或 IP在settings.py中添加允许的域名例如ALLOWED_HOSTS [*]仅限开发环境修改模板后页面没有变化浏览器缓存了旧页面按CtrlF5强制刷新或检查模板路径是否拼写正确创建应用后找不到相关命令应用未注册到INSTALLED_APPS编辑settings.py将应用名称加入列表还有一个新手容易犯的错误直接使用python manage.py runserver 80以 80 端口启动。如果当前系统有其他程序占用了这个端口会报Error: That port is already in use。你可以换一个端口例如python manage.py runserver 8001在开发环境中8000 端口已经足够使用了。9. 工程实践与开发建议掌握基础语法之后下面这些经验能帮助你写出更规范、更易维护的 Django 项目。9.1 使用虚拟环境和依赖锁定每个 Django 项目都应该使用独立的虚拟环境。同时建议将项目依赖导出到requirements.txt文件中方便他人复现环境pip freeze requirements.txt部署到新环境时pip install -r requirements.txt9.2 合理拆分应用不要把所有的模型、视图、模板都写在一个应用里。应用应该按照业务模块拆分例如users、articles、comments等。这样项目结构清晰也方便多个开发者并行开发。9.3 重视 settings.py 的配置管理不要把生产环境的数据库密码、Secret Key 等敏感信息硬编码在settings.py中。建议通过环境变量或配置文件来管理。例如import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-only-key) DEBUG os.environ.get(DJANGO_DEBUG, True) True这样在部署到生产环境时只需要设置环境变量不需要修改代码。9.4 谨慎处理数据库操作更新和删除数据时尽量先通过查询确认操作范围。在shell中执行批量删除操作前可以先print查询结果或者使用事务包裹。生产环境的数据库备份和迁移操作建议在低峰期执行提前做好回滚方案。9.5 使用 Class-Based View 还是 Function-Based View对于新手我建议先从函数视图FBV开始因为它逻辑直观方便调试。当你对 Django 有更深理解后可以逐步学习类视图CBV例如ListView、DetailView、CreateView等它们能减少重复代码但内部机制更复杂初学者容易“知其然而不知其所以然”。9.6 日志与调试print()是新手最常用的调试手段但它不适合长期保留。Django 提供了标准的 logging 模块你可以在settings.py中配置日志输出LOGGING { version: 1, disable_existing_loggers: False, handlers: { console: { class: logging.StreamHandler, }, }, root: { handlers: [console], level: INFO, }, }然后在视图中import logging logger logging.getLogger(__name__) def home(request): logger.info(访问了首页) return render(request, home.html)这样不仅能在控制台看到日志也可以方便地扩展为文件日志、邮件通知等。在调试复杂问题时系统的日志比一次性print输出更有价值。10. 总结与下一步学习建议暂时先不急着挂上“总结”的字样。上面这些内容其实已经带你把 Django 最核心的主线走了一遍创建项目、创建应用、配置路由、编写视图、使用模板、定义模型、使用 Admin 后台。你现在应该能够独立搭建一个简单但完整的 Django 应用并且对它内部的目录结构和请求流程有了直观的认识。接下来建议你不要急着学习高深的技术而是自己动手改造一个项目。把Article模型加上“作者”字段再做一个详情页当用户点击文章标题时能看到完整的文章内容。整个过程会用到更复杂的 URL 参数配置例如path(article/int:pk/, views.detail)。单条数据的查询例如Article.objects.get(pkpk)。模板中的链接跳转例如a href{% url detail article.pk %}。完成这个改造后你会对 Django 的 URL 传参、模型查询和模板渲染有更深的理解。之后再去看 Django 官方的“编写你的第一个 Django 应用”文档你会发现很多内容都能对号入座。如果你的业务需要做 RESTful API可以在熟练基础之后学习 Django REST FrameworkDRF如果你需要处理 WebSocket 实时通信可以学习 Channels如果你要部署上线需要了解 Nginx、Gunicorn、Docker 等工具。这些进阶内容都以本文的主线为基础主线越扎实后面的路越稳。希望这篇文章能帮你迈出 Django 的第一步。
大家在学习 Django 的时候最常见的问题不是“Django 难不难”而是“资料太多不知道先学什么”。网上关于 Django 的教程、视频、源码解析铺天盖地但大部分新手都卡在同一个地方跟着教程敲完了代码却不知道这些文件之间是什么关系更不知道下一步该往哪个方向深入。本文想帮你抓住 Django 的一条主线从环境搭建开始一步步完成一个最基础的 Web 应用让你真正理解 Django 的项目结构、请求处理流程和数据模型设计思路。这条主线捋顺之后后续学习 DRF、Celery、Channels 等进阶内容都会轻松很多。如果你是刚接触 Python Web 开发的初学者或者已经看过一些 Django 教程但总觉得没形成体系这篇文章都非常适合你。我会尽量少讲抽象概念多给可运行、可验证的代码示例每一段代码都说明放在哪个文件、起什么作用。最后还会补充常见报错和工程上的建议方便你在独立开发时少踩坑。1. Django 是什么它解决什么问题先不急着写代码我们花几分钟把 Django 的定位搞清楚。很多初学者一上来就去看中间件、信号、自定义管理器这些进阶特性结果被绕晕了。实际上Django 的核心价值可以概括为一句话它让你用最少的重复劳动快速构建一个基于数据库的 Web 应用。1.1 Django 的本质Web 框架Web 框架解决的核心问题是“接收 HTTP 请求 → 处理业务逻辑 → 返回 HTTP 响应”这一整套流程。如果没有框架你需要自己处理 socket 连接、HTTP 协议解析、URL 路由匹配、请求参数提取、数据库连接、HTML 模板渲染……这些工作量大且容易出错。Django 把这些通用能力都封装好了你只需要关注两件事定义 URL 和视图函数或者类视图的映射关系。用 Python 代码处理业务逻辑把数据交给模板去渲染。换句话说Django 帮你把“Web 服务器该干的活”和“业务开发者该干的活”做了清晰的分工。1.2 Django 的 MTV 架构很多人听说过 MVC也就是 Model-View-Controller。Django 虽然也遵循类似思想但它的官方术语是 MTVMModel数据模型层负责与数据库交互。在 Django 中你通过 Python 类定义表结构Django 负责生成 SQL 并操作数据库。TTemplate模板层负责页面的展示。模板中可以使用类似 HTML 的语法也能嵌入变量、循环、判断等逻辑。VView视图层负责业务逻辑。视图接收 HTTP 请求从 Model 中取数据或调用外部接口把数据交给 Template 渲染最终返回 HTTP 响应。可能你还是觉得有点抽象。没关系我们可以用一张简化的请求流程图来理解浏览器发起请求 ↓ Django 根据 URL 找到对应的 View视图 ↓ View 调用 Model 操作数据库读/写 ↓ View 把数据传给 Template 渲染 HTML ↓ Django 把响应返回给浏览器新手最容易混淆的地方是Django 的“视图”更像 MVC 里的 Controller而不是 MVC 里的 View。这个称呼差异不用太纠结只要记住“视图负责业务逻辑”就够了。1.3 为什么 Django 适合新手和企业开发Django 的一大特点是“内置电池”。一个完整的 Django 项目中默认包含自带 Admin 后台管理系统可以通过 Web 页面直接管理数据库记录。自带 ORM对象关系映射不用手写 SQL 就能完成大部分增删改查。自带表单处理、用户认证、会话管理、CSRF 防护等常见功能。拥有成熟的迁移机制修改模型后可以自动生成数据库变更脚本。这些内置功能让 Django 在快速原型开发和企业级项目中都很有竞争力。即使你最终不使用 Admin 后台它在开发调试阶段也能极大提升效率。2. 环境准备与版本说明开始写 Django 之前我们需要把开发环境准备好。这里不会指定某一个绝对必须使用的版本因为不同项目对 Python 和 Django 的版本要求可能不同但为了让新手能顺利跑通示例我会给出一个常见的组合并说明调整思路。2.1 Python 环境准备Django 是 Python 的第三方库所以首先需要确保你的电脑上安装了 Python。建议使用 Python 3.8 及以上版本因为新版本提供了更好的语法和性能支持Django 官方在新版本中也逐步放弃了对旧版 Python 的兼容。在命令行中检查 Python 版本python --version或者在某些系统中是python3 --version如果提示找不到命令你需要先安装 Python。安装完成后建议顺手安装pipPython 包管理工具。Python 3.4 以上版本默认自带 pip可以直接使用pip --version2.2 创建虚拟环境虚拟环境是 Python 开发中非常重要的一个习惯。每个项目都有自己的依赖库避免不同项目之间因为 Django 版本不同而互相干扰。在 Windows 上创建虚拟环境# 进入你的项目目录例如 django_project mkdir django_project cd django_project python -m venv venv在 macOS 或 Linux 上mkdir django_project cd django_project python3 -m venv venv然后激活虚拟环境。Windows 下venv\Scripts\activatemacOS 或 Linux 下source venv/bin/activate激活成功后命令行提示符前面会出现(venv)字样。之后安装的 Python 包都会进入这个环境不会污染全局环境。关于虚拟环境新手常见的两个误区忘记激活虚拟环境直接pip install django结果 Django 装到了全局环境里。换了终端窗口后虚拟环境没有被激活导致python manage.py命令找不到 Django。遇到“ModuleNotFoundError: No module named django”这类报错时第一反应就应该是检查虚拟环境是否激活、当前环境是否安装了 Django。2.3 安装 Django在激活的虚拟环境中使用 pip 安装 Djangopip install django这会安装最新稳定版本的 Django。如果你希望安装指定版本可以写成pip install django4.2.0安装完成后验证版本python -m django --version如果能看到类似4.2.0或者5.x的版本号说明安装成功。本文的示例基于 Django 4.x/5.x 的常见用法如果你的系统是其他版本大部分代码仍然适用但个别配置写法可能需要微调。2.4 IDE 与项目结构建议Django 开发不强制要求使用某个特定 IDE。你可以选择PyCharm 专业版对 Django 支持最好有模板补全、ORM 提示、调试工具。VS Code免费且轻量安装 Python 插件后也很好用。普通文本编辑器 命令行适合熟悉命令行操作的同学。本文的示例以命令行操作为主代码文件放在项目目录下你也可以直接用自己的 IDE 打开项目目录来查看和编辑文件。3. 创建 Django 项目理解项目骨架环境准备好之后我们正式进入 Django 主线。这一步会创建一个 Django 项目并解释项目生成出来的各个文件有什么用。3.1 创建项目在虚拟环境激活状态下进入你要存放项目的目录执行django-admin startproject myproject这条命令会创建一个名为myproject的目录目录内部结构大致如下myproject/ manage.py myproject/ __init__.py settings.py urls.py asgi.py wsgi.py我们需要区分两个myproject外层myproject是项目的根目录它与manage.py同级。内层myproject是一个 Python 包里面存放 Django 项目的主配置。manage.py是 Django 项目的管理脚本。后面我们执行的大多数命令都需要通过它来调用比如启动开发服务器、创建应用、执行数据库迁移等。内层myproject中的几个文件settings.py项目的总配置文件包括数据库配置、应用注册、模板路径、静态文件路径、时区、语言等。urls.pyURL 路由配置文件浏览器请求的 URL 会在这里找到对应的视图函数。asgi.py和wsgi.py部署时使用的入口文件分别对应异步和同步的 Web 服务器接口新手阶段不需要深入了解。__init__.py标识这个目录是一个 Python 包。3.2 启动开发服务器项目创建完成后进入项目根目录运行cd myproject python manage.py runserver如果一切正常命令行会提示Starting development server at http://127.0.0.1:8000/我们在浏览器中访问 http://127.0.0.1:8000/就会看到 Django 的默认欢迎页面页面上会显示一个火箭图标并提示“The install worked successfully! Congratulations!”这个页面说明你的 Django 项目已经成功运行。需要特别提醒的是Django 自带的这个服务器是开发服务器适合本地调试不能直接用于生产环境部署。在生产环境我们需要使用 Gunicorn、uWSGI 等 WSGI 服务器配合 Nginx 反向代理。这个话题后面可以单独写一篇部署教程。3.3 创建应用AppDjango 项目和应用是两个不同的概念。一个项目可以包含多个应用每个应用负责一个相对独立的功能模块。比如一个电商网站项目中可能包含users应用负责用户管理orders应用负责订单管理products应用负责商品管理。创建应用的命令python manage.py startapp article这里我们用article作为示例应用它是一个简单的文章模块。命令执行后项目根目录下会多出一个article目录结构如下article/ __init__.py admin.py apps.py models.py tests.py views.py migrations/ __init__.py这些文件的作用models.py定义数据模型也就是数据库表结构。views.py编写视图函数或类视图处理用户请求。admin.py把模型注册到 Django Admin 后台方便管理数据。apps.py应用的配置文件里面包含应用名称等信息。tests.py编写测试用例。migrations/存放数据库迁移文件。此时我们还需要把这个应用注册到项目中。打开myproject/settings.py找到INSTALLED_APPS列表把article加进去# 文件路径myproject/settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, article, # 新增这一行 ]如果不注册应用Django 虽然不会立刻报错但后面你可能会遇到No installed app with label article之类的错误或者模板、迁移命令找不到这个应用。所以每次创建一个新应用第一件事就是把它注册到INSTALLED_APPS中。4. 编写第一个视图从 URL 到页面的完整流程理解了项目结构后我们开始写第一个真正意义上的页面。这一步会贯穿 Django 最核心的请求流程URL → View → HTTP 响应。4.1 编写视图函数打开article/views.py写入# 文件路径article/views.py from django.http import HttpResponse def home(request): return HttpResponse(Hello, Django!)这是一个最简单的视图函数。request参数是 Django 封装好的 HTTP 请求对象包含了请求头、请求方法、请求参数等信息。这里我们没有使用request只是返回一个纯文本响应。4.2 配置 URL 路由接下来我们需要告诉 Django当用户访问某个 URL 时应该调用哪个视图函数。在article应用目录下新建一个urls.py文件写入# 文件路径article/urls.py from django.urls import path from . import views urlpatterns [ path(, views.home, namehome), ]然后修改项目主路由myproject/urls.py把应用的 URL 配置包含进来# 文件路径myproject/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(article.urls)), ]这里的关键是include函数。它的作用是把article应用下的urls.py文件中的 URL 配置“挂载”到主路由中。这样当用户访问根路径/时Django 会进入article/urls.py进行匹配找到views.home。4.3 验证运行效果保存文件后如果开发服务器还在运行它会自动加载新的代码。在浏览器中访问 http://127.0.0.1:8000/ 你应该能看到页面显示Hello, Django!。此时整个请求流程是浏览器请求 http://127.0.0.1:8000/ ↓ Django 读取 myproject/urls.py ↓ 匹配到 include(article.urls) ↓ 进入 article/urls.py ↓ 匹配到 path(, views.home) ↓ 执行 views.home 函数 ↓ 返回 HttpResponse(Hello, Django!)这个过程看似简单但它是 Django 一切功能的基础。无论将来你写多复杂的项目都是从这条链路延伸出去的。5. 使用模板与静态文件直接在视图里返回字符串虽然简单但真实的页面不可能都是纯文本。我们需要使用 HTML 模板来渲染页面并在页面中引入 CSS、JavaScript 等静态文件。5.1 配置模板目录Django 默认会从每个应用下的templates目录中查找模板文件所以我们可以在article应用下创建一个templates目录。然后新建一个 HTML 文件!-- 文件路径article/templates/home.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 titleDjango 新手教程/title /head body h1欢迎来到 Django 世界/h1 p这是通过模板渲染出来的页面。/p /body /html为了让模板中使用静态文件我们通常还会在应用目录下创建static目录并在模板中通过{% load static %}标签加载静态文件。不过这一步我们先不展开等用到的时候再演示。5.2 修改视图使用模板接下来修改article/views.py让它使用模板来渲染页面# 文件路径article/views.py from django.shortcuts import render def home(request): return render(request, home.html)render函数是 Django 中非常常用的一个快捷函数。它的作用是根据传入的模板名称在应用的templates目录下找到对应的模板文件。将模板渲染成 HTML 字符串。返回一个包含该 HTML 的HttpResponse对象。现在刷新浏览器你会看到页面显示“欢迎来到 Django 世界”并且页面的标题也发生了变化。5.3 在模板中传递变量模板的意义不只是静态 HTML更重要的是把后端的数据动态渲染到页面上。我们来演示如何把 Python 变量传到模板中。修改视图# 文件路径article/views.py from django.shortcuts import render def home(request): name 小明 articles [ Django 入门教程, Python 基础语法, Web 开发实战, ] context { name: name, articles: articles, } return render(request, home.html, context)这里我们定义了一个context字典里面包含了name和articles两个变量。Django 的模板语法使用双大括号{{ }}输出变量使用{% %}执行循环或判断等逻辑。修改模板文件!-- 文件路径article/templates/home.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 titleDjango 新手教程/title /head body h1你好{{ name }}/h1 ul {% for article in articles %} li{{ article }}/li {% endfor %} /ul /body /html刷新页面后你会看到输出你好小明 1. Django 入门教程 2. Python 基础语法 3. Web 开发实战这个示例展示了 Django 模板最核心的两个功能变量输出和循环遍历。后续你还会用到if条件判断、模板过滤器、模板继承等特性但核心思路始终是把 Python 对象传入模板然后按模板语法渲染。6. 模型Model与数据库操作现在我们已经掌握了从 URL 到视图再到模板的流程。但一个 Web 应用的数据通常是动态变化的比如用户发布文章、修改评论、上传文件这些数据需要保存到数据库中。Django 的 ORM 让我们可以用 Python 代码操作数据库而不需要直接写 SQL。6.1 定义模型打开article/models.py定义一个简单的文章模型# 文件路径article/models.py from django.db import models class Article(models.Model): title models.CharField(max_length200, verbose_name标题) content models.TextField(verbose_name内容) created_at models.DateTimeField(auto_now_addTrue, verbose_name创建时间) def __str__(self): return self.title这里我们定义了一个Article类它继承自models.Model。Django 会把这个类映射为数据库中的一张表类属性对应数据库字段。各字段的含义CharField字符串类型max_length200表示最大长度 200 个字符适合存储标题。TextField长文本类型适合存储文章正文。DateTimeField日期时间类型auto_now_addTrue表示在对象第一次创建时自动填入当前时间。__str__方法不是必须的但它能在 Django Admin 后台和命令行中更友好地显示对象。比如在后台列表中默认会显示Article object定义__str__后就会显示文章标题。6.2 生成数据库迁移文件模型定义好之后我们需要让 Django 根据模型生成数据库表。这里 Django 引入了“迁移”migration的机制。执行命令python manage.py makemigrations这个命令会扫描项目中的模型变化并在应用的migrations目录下生成迁移文件。迁移文件记录了模型的变化历史比如你新增了Article模型就会生成一个类似0001_initial.py的文件。然后执行python manage.py migrate这个命令会把迁移文件中记录的操作同步到数据库。Django 默认使用 SQLite 数据库这是一个轻量级的文件型数据库不需要额外安装任何数据库服务非常适合开发环境。执行完migrate后项目中会多出db.sqlite3文件这就是 SQLite 的数据库文件。6.3 通过 Django Shell 操作数据库我们可以通过 Django 提供的交互式命令行来测试数据操作。运行python manage.py shell然后在交互环境中输入from article.models import Article # 创建一条数据 Article.objects.create(title我的第一篇文章, content这是文章内容) # 查询所有数据 articles Article.objects.all() print(articles) # 获取第一条数据 article Article.objects.first() print(article.title) print(article.content) print(article.created_at) # 更新数据 article.title 修改后的文章标题 article.save() # 删除数据 article.delete()这些命令的执行流程Article.objects.create()向数据库插入一条记录。Article.objects.all()查询所有记录返回一个 QuerySet。Article.objects.first()返回第一条记录。修改对象属性后调用save()会更新数据库。调用delete()会删除记录。Django ORM 的核心优势在于你不必关心当前使用的是 SQLite 还是 MySQL大部分查询代码都保持一致。从开发环境切换到生产环境时只需要修改settings.py中的数据库配置代码几乎不用改。需要注意这里的delete()是一个真实删除操作会直接从数据库中移除记录。在生产环境执行删除操作前一定要确认操作范围必要的时候先备份数据库。6.4 在视图中使用模型数据接下来我们把数据库中的数据展示到页面上。修改视图# 文件路径article/views.py from django.shortcuts import render from .models import Article def home(request): name 小明 articles Article.objects.all() context { name: name, articles: articles, } return render(request, home.html, context)模板保持不变。现在刷新页面你会发现页面中显示的不再是我们在视图里硬编码的列表而是数据库中实际存在的文章标题。如果你的Article表里没有数据页面就是空的。你可以通过刚才的shell命令创建几条数据或者等下一节使用 Admin 后台来添加。7. 使用 Django Admin 后台管理数据Django Admin 是 Django 自带的后台管理系统它可以根据你在admin.py中注册的模型自动生成增删改查页面。它特别适合开发阶段的内部管理和数据调试。7.1 创建超级用户运行python manage.py createsuperuser按照提示输入用户名、邮箱可以跳过和密码。新手经常遇到的坑是密码太简单会提示验证失败比如“The password is too similar to the username.”。如果想强制使用简单密码可以输入y继续但其实在真实项目中密码强度很重要建议设置一个复杂一点的密码。7.2 注册模型打开article/admin.py写入# 文件路径article/admin.py from django.contrib import admin from .models import Article admin.register(Article) class ArticleAdmin(admin.ModelAdmin): list_display [title, created_at] search_fields [title]这里我们使用了admin.register装饰器来注册模型。list_display指定后台列表中显示哪些字段search_fields指定可以通过哪些字段进行搜索。7.3 使用后台启动开发服务器python manage.py runserver在浏览器中访问 http://127.0.0.1:8000/admin/ 使用刚才创建的超级用户登录。登录成功后你会看到Article模型的管理入口。点击进去就能看到文章列表还可以点击“ADD ARTICLE”按钮添加新文章点击文章标题进入编辑页面底部有删除按钮。对于新手来说Admin 后台是验证模型定义和快速录入数据的好工具。它暴露了 Django 的一大核心优势很多常见的后台管理功能Django 已经替你写好了。8. 常见问题与排查思路初学者在搭建 Django 项目的过程中常常会遇到一些看起来很吓人、实际很简单的报错。下面列举几个最常见的场景和排查思路。问题现象常见原因解决思路ModuleNotFoundError: No module named django没有安装 Django或虚拟环境未激活检查pip show django确认命令在激活的虚拟环境中执行File manage.py, line 17, in main ... ImportErrorPython 版本过低或者 Django 版本与 Python 版本不兼容检查python --version和python -m django --versionYou have unapplied migrations模型变更后没有执行migrate运行python manage.py migrate页面显示 404URL 路由配置错误或者访问的路径不正确检查urls.py中的path是否正确注意是否缺少include页面显示 DisallowedHost 错误ALLOWED_HOSTS配置不包含当前域名或 IP在settings.py中添加允许的域名例如ALLOWED_HOSTS [*]仅限开发环境修改模板后页面没有变化浏览器缓存了旧页面按CtrlF5强制刷新或检查模板路径是否拼写正确创建应用后找不到相关命令应用未注册到INSTALLED_APPS编辑settings.py将应用名称加入列表还有一个新手容易犯的错误直接使用python manage.py runserver 80以 80 端口启动。如果当前系统有其他程序占用了这个端口会报Error: That port is already in use。你可以换一个端口例如python manage.py runserver 8001在开发环境中8000 端口已经足够使用了。9. 工程实践与开发建议掌握基础语法之后下面这些经验能帮助你写出更规范、更易维护的 Django 项目。9.1 使用虚拟环境和依赖锁定每个 Django 项目都应该使用独立的虚拟环境。同时建议将项目依赖导出到requirements.txt文件中方便他人复现环境pip freeze requirements.txt部署到新环境时pip install -r requirements.txt9.2 合理拆分应用不要把所有的模型、视图、模板都写在一个应用里。应用应该按照业务模块拆分例如users、articles、comments等。这样项目结构清晰也方便多个开发者并行开发。9.3 重视 settings.py 的配置管理不要把生产环境的数据库密码、Secret Key 等敏感信息硬编码在settings.py中。建议通过环境变量或配置文件来管理。例如import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-only-key) DEBUG os.environ.get(DJANGO_DEBUG, True) True这样在部署到生产环境时只需要设置环境变量不需要修改代码。9.4 谨慎处理数据库操作更新和删除数据时尽量先通过查询确认操作范围。在shell中执行批量删除操作前可以先print查询结果或者使用事务包裹。生产环境的数据库备份和迁移操作建议在低峰期执行提前做好回滚方案。9.5 使用 Class-Based View 还是 Function-Based View对于新手我建议先从函数视图FBV开始因为它逻辑直观方便调试。当你对 Django 有更深理解后可以逐步学习类视图CBV例如ListView、DetailView、CreateView等它们能减少重复代码但内部机制更复杂初学者容易“知其然而不知其所以然”。9.6 日志与调试print()是新手最常用的调试手段但它不适合长期保留。Django 提供了标准的 logging 模块你可以在settings.py中配置日志输出LOGGING { version: 1, disable_existing_loggers: False, handlers: { console: { class: logging.StreamHandler, }, }, root: { handlers: [console], level: INFO, }, }然后在视图中import logging logger logging.getLogger(__name__) def home(request): logger.info(访问了首页) return render(request, home.html)这样不仅能在控制台看到日志也可以方便地扩展为文件日志、邮件通知等。在调试复杂问题时系统的日志比一次性print输出更有价值。10. 总结与下一步学习建议暂时先不急着挂上“总结”的字样。上面这些内容其实已经带你把 Django 最核心的主线走了一遍创建项目、创建应用、配置路由、编写视图、使用模板、定义模型、使用 Admin 后台。你现在应该能够独立搭建一个简单但完整的 Django 应用并且对它内部的目录结构和请求流程有了直观的认识。接下来建议你不要急着学习高深的技术而是自己动手改造一个项目。把Article模型加上“作者”字段再做一个详情页当用户点击文章标题时能看到完整的文章内容。整个过程会用到更复杂的 URL 参数配置例如path(article/int:pk/, views.detail)。单条数据的查询例如Article.objects.get(pkpk)。模板中的链接跳转例如a href{% url detail article.pk %}。完成这个改造后你会对 Django 的 URL 传参、模型查询和模板渲染有更深的理解。之后再去看 Django 官方的“编写你的第一个 Django 应用”文档你会发现很多内容都能对号入座。如果你的业务需要做 RESTful API可以在熟练基础之后学习 Django REST FrameworkDRF如果你需要处理 WebSocket 实时通信可以学习 Channels如果你要部署上线需要了解 Nginx、Gunicorn、Docker 等工具。这些进阶内容都以本文的主线为基础主线越扎实后面的路越稳。希望这篇文章能帮你迈出 Django 的第一步。
