我是个写过好几年 Django 的老开发了每次有人问“Django 怎么入门”我都不想直接甩官方文档——那玩意对新手太不友好翻两页就困了。所以这篇“Django 基础入门教程第一篇”没有废话不堆概念用一次完整的建站流程把 Django 最核心的东西串起来。这篇能帮你回答三个问题Django 到底是什么、它凭什么这么流行、以及我该怎么把第一个项目跑起来。就算你只是刚学完 Python 语法、还没碰过任何 Web 框架跟着这篇走一遍也能亲手做出一个带数据库后台的小网站。1. 为什么是 Django框架定位与核心设计1.1 它解决什么问题写网页最枯燥的部分其实不是业务逻辑而是那些“每个网站都有的破事”用户提交表单、登录验证、数据库读写、后台管理、防止黑客攻击。你要是每次都用原生 Python 重写一遍写完基本就废了而且安全性还没保障。Django 最大的价值就是把这一整套通用能力打包好让你专注写真正属于项目的部分。很多人一上来就纠结“Django 好还是 Flask 好”这种问题问早了。Flask 更像一把手工刀灵活但没有太多内置装备什么都得自己拼Django 更像一个精装工具箱里面头盔、护具、常用工具全齐了。对刚起步的人来说先学会用一套完整的工具干活比什么都自己造更有效率。我见过不少只用 Flask 写了两年的人连表单校验都还在手写正则到了 Django 这边发现全是现成的——这差距不是能力问题是框架的设计理念完全不同。Django 走的是“batteries included”电池全家桶路线官方自己维护 ORM、模板引擎、后台管理、认证系统生态非常统一。1.2 核心组件与一次请求的完整旅程Django 常被人说是 MTV 架构Model-Template-View这和传统的 MVC 有点区别但核心思想一样都是分层解耦。我刚学的时候觉得这术语唬人其实拆开看非常简单Model负责和数据打交道。你在 Python 里定义一个类Django 的 ORM 帮你把它映射成数据库表不用自己写 SQL。Template负责页面长什么样决定用户能看到什么 HTML。View负责业务逻辑——用户想干嘛数据该怎么取最后把结果传给哪个模板。一次完整的请求流程大致是这样用户在浏览器访问一个 URL比如http://127.0.0.1:8000/articles/Django 拿着路径去 URL 路由表里找匹配规则匹配到后把请求转交给对应的视图函数View视图函数处理逻辑通常要查询数据库Model结果数据塞给模板Template模板渲染出 HTML最后把 HTML 作为响应传回浏览器这六步就是 Django 的“心法”后面写多少代码都绕不开这个流程。我建议你把这六行抄下来贴在显示器边上遇到卡壳就对着它想“现在跑到第几步了”。1.3 认识你的工作目录结构Django 用命令行工具创建项目后会生成一个固定的骨架。第一次看到这堆文件的人都会懵我当初也懵了但其实每个文件职责非常明确。文件作用重要程度manage.py项目总指挥几乎所有命令都要通过它执行必需settings.py全局配置数据库、安装的应用、时区、模板位置等必改urls.py路由入口前端请求从这里开始分发必改wsgi.py/asgi.py部署时用本地开发基本不用碰了解db.sqlite3本地数据库文件第一次迁移后自动生成自动先把这几个文件弄明白项目的骨架就吃透了。后添加的每个“应用”也会有自己的models.py、views.py、urls.py但manage.py只管全局。2. 环境搭建与第一个项目从零跑通2.1 Python 环境与虚拟环境Django 是 Python 的第三方库装它之前先确认你的 Python 版本。当前主流版本是 3.8 到 3.12不建议用太旧的版本因为新版本 Django 已经放弃老 Python 了。装之前可以先看下官方支持的组合省得后面报一些莫名其妙的环境错误。强烈建议在虚拟环境里安装。虚拟环境相当于给每个项目单独隔一个小房间里面放的 Python 包互相不干扰。你以后会同时维护多个项目很可能这个项目要 Django 4.2、那个要 Django 5.0没有虚拟环境的话版本冲突会把你折磨到怀疑人生。命令行里这样建# 创建虚拟环境venv 是 Python 自带工具不用额外装 python3 -m venv myenv # 激活它 # Windows 环境执行 myenv\Scripts\activate # Mac / Linux 环境执行 source myenv/bin/activate激活之后终端提示符前面会出现(myenv)的字样看到它就说明当前已经在虚拟环境里了。然后安装 Django 就非常简单pip install django # 验证一下 django-admin --version如果这行能输出版本号环境就没问题了。新手最容易犯的错误是建了虚拟环境但忘了激活直接pip install django结果装到了全局环境里导致启动项目时提示找不到模块。这事我犯过不止一次先看一眼命令前的(myenv)再执行能省很多事。2.2 创建项目和应用的完整命令Django 的概念里**项目project和应用app**是两回事。项目是整个网站容器应用是里面一个个功能模块比如一个博客系统可以有文章应用、评论应用、用户应用。第一次建没必要把概念背得多熟先这样想项目是房间应用是房间里不同的家具区。创建项目# 在当前目录下创建一个名叫 myblog 的项目 django-admin startproject myblog这个命令会生成上一节说的那个骨架。然后进入项目目录再创建一个应用cd myblog python manage.py startapp articles创建完应用后有一个极其关键的步骤到settings.py里的INSTALLED_APPS列表中把你的应用加进去。不这么做的话Django 根本不知道你创建了这个应用后面数据库迁移会永远找不到你的表。INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, # ... 其他默认应用 articles, # 加上这一行 ]2.3 第一次启动项目时的常见报错配置好之后运行python manage.py runserver如果看到Starting development server at http://127.0.0.1:8000/恭喜你项目已经活了。这时在浏览器打开http://127.0.0.1:8000/会看到 Django 默认的火箭欢迎页。这个阶段容易踩的问题我整理一下端口被占用提示address already in use。要么换端口比如python manage.py runserver 8080要么把占用端口的进程杀掉。提示 No module named django几乎都是虚拟环境没激活或装错环境用pip list看看 django 在不在。改了代码但页面没变化runserver 自带自动重载但新增文件的部分情况不会自动生效重启一下就好。Django 的开发服务器有一个好处它会实时检测代码变化并自动重启这在本地开发时非常爽改完代码刷新页面就行不用手动重启。3. 核心概念逐个拆解URL、视图、ORM、模板3.1 URL 路由入口控制URL 路由是 Web 框架的交通警察。用户请求http://127.0.0.1:8000/articles/时这个路径会先进项目的urls.pyDjango 从上到下按顺序匹配规则碰到第一个能匹配的就用对应的视图。最基本的写法是path()# myblog/urls.py from django.urls import path from articles import views urlpatterns [ path(articles/, views.article_list, namearticle_list), path(articles/int:pk/, views.article_detail, namearticle_detail), ]这里int:pk是动态参数意思是这个位置接受一个整数并把它作为参数传给视图函数。除了int常用的转换器还有str字符串、slug适合文章标题型短横线字符串。这种写法比老一代的正则url()直观多了推荐新项目统一用path()。namearticle_list也很关键。你以后在模板里引用 URL 时靠的是这个名字而不是硬编码路径。比如href{% url article_list %}这样不管路径怎么改只要 name 不变模板里的链接都不会断。初学者容易犯的错是把业务路由都堆在项目根urls.py里。正确的组织方式是按应用拆分每个应用一个自己的urls.py再在主路由里用include()挂进来# myblog/urls.py from django.urls import include, path urlpatterns [ path(articles/, include(articles.urls)), ]这样文章相关的路由都在articles/urls.py里维护各管各的项目一大了优势马上体现。3.2 视图层请求与响应视图是 Django 里最核心的代码块。一个最简单的函数视图长这样# articles/views.py from django.http import HttpResponse def article_list(request): return HttpResponse(这里是文章列表)这里面的request参数携带了用户请求的所有信息请求方法GET/POST、用户是否登录、提交的表单数据、请求头里的各种信息。你可以在视图里通过request.method判断请求方式通过request.GET.get(param)拿查询参数。实际项目里视图直接返回HttpResponse(字符串)的机会不多更多是返回渲染后的 HTML 模板或者给前端接口返回 JSONfrom django.shortcuts import render from django.http import JsonResponse def article_list(request): # 假设这里用 ORM 查询到了文章数据 articles [...] if request.path.endswith(json): return JsonResponse({data: articles}) return render(request, articles/list.html, {articles: articles})render的第三个参数是个字典这字典就是给模板用的上下文模板里怎么调用待会儿说。从新手角度视图层需要掌握的套路就两条从request里取参数、用render渲染模板其他的装饰器、类视图等后面再慢慢进阶。3.3 ORM 与模型不写 SQL 的数据库操作ORM对象关系映射是 Django 最值得吹的地方之一。你在 Python 里定义的这个类就是一个数据库表# articles/models.py from django.db import models class Article(models.Model): title models.CharField(max_length200) content models.TextField() created_at models.DateTimeField(auto_now_addTrue) def __str__(self): return self.titleCharField对应数据库的 varcharTextField对应 textDateTimeField对应 datetime。Django 会根据这些字段类型自动生成建表 SQL。你不需要关心底层是 MySQL 还是 SQLite框架帮你做了抽象。写完之后关键操作是生成迁移文件并执行迁移python manage.py makemigrations python manage.py migrate第一个命令是问你“检测到模型变化生成一个迁移计划”第二个是真正“把这计划执行到数据库”。这俩顺序不能乱。新手最常犯的错是改了models.py却不重新执行这两个命令结果页面报错说没有这个表。查询数据的语法很直观# 查所有 Article.objects.all() # 过滤条件 Article.objects.filter(title__containsDjango) # 取单个 Article.objects.get(id1)注意objects.all()返回的并不是数据库里真实的数据列表而是一个 QuerySet懒查询对象真正访问数据库的时机是遍历它或者调用.first()、.count()这类方法时。这个设计是为了能多级链式过滤性能更好但新手容易产生“我明明查了为什么没数据”的错觉——先打印一下再判断。4. 一个能跑的最小 Demo完成一次数据库读写闭环4.1 定义模型并注册后台光讲概念没有用这里我带你做一个真正能跑的最小 Demo一个带后台管理的文章列表页。项目名就叫myblog应用名articles已经按上一节的步骤创建好了。先在articles/models.py里定义文章模型字段用上面写过的那个Article即可。核心是别忘了给模型加一个_str_方法不然后台里所有文章都显示成“Article object (1)”你根本分不清谁是谁。然后需要把模型注册到 Django 自带的 Admin 后台。打开articles/admin.py# articles/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, content)list_display控制后台列表页显示哪些列search_fields提供搜索框。这两项是刚需配置不加的话后台只有显示默认字段用起来很不顺手。4.2 使用系统自带后台执行完数据库迁移后需要创建管理员账号python manage.py createsuperuser按提示填用户名、邮箱可空、密码。注意密码输入时不显示字符这是正常现象不是键盘坏了。然后启动服务访问http://127.0.0.1:8000/admin/用刚创建的账号登录。这里就是 Django 最让人“哇”的地方——一个带增删改查、分页、过滤、权限控制的完整后台系统一行业务代码都没写全是框架送的。你可以在后台点几下新增几篇文章试试手感。这也是我说新手入门不要第一步就选 Flask 的原因之一Django 把管理后台送给你刚起步就有了可视化操作自信心瞬间上来。4.3 写视图、配路由、做模板后台里有数据了下一步是写一个公开的文章列表页。先在articles/views.py里写视图# articles/views.py from django.shortcuts import render from .models import Article def article_list(request): articles Article.objects.all().order_by(-created_at) return render(request, articles/list.html, {articles: articles})order_by(-created_at)表示按创建时间倒序-号是降序。这一步已经把数据库里的文章都取出来了接下来只要交给模板。在应用目录下建templates/articles/list.html注意模板目录结构不能随意Django 是按应用名/templates/应用名/模板文件的路径约定查找的应用名这层必须保留防止多个应用有同名模板时覆盖。模板内容!DOCTYPE html html head meta charsetUTF-8 title文章列表/title /head body h1最新文章/h1 {% for article in articles %} h2{{ article.title }}/h2 p{{ article.created_at }}/p p{{ article.content|truncatechars:50 }}/p hr {% empty %} p还没有文章去后台添加一篇吧。/p {% endfor %} /body /html{% for %}是模板循环语法{{ }}是变量输出{{ article.content|truncatechars:50 }}里的管道符是过滤器作用是把超长文本截断到 50 个字符。{% empty %}是数据列表为空时的兜底文案这个细节很贴心列表页不至于白花花一片。最后把路由连起来在articles/urls.py里添加# articles/urls.py from django.urls import path from . import views urlpatterns [ path(, views.article_list, namearticle_list), ]再去项目根myblog/urls.py里 include 一下# myblog/urls.py from django.urls import include, path urlpatterns [ path(admin/, admin.site.urls), path(articles/, include(articles.urls)), ]访问http://127.0.0.1:8000/articles/你就能看到后台添加的文章全部展示在页面上了。到这里一条完整的链路已经打通后台写数据、ORM 读数据、模板展示数据、URL 控制入口。别看这个小页面不起眼它涵盖了 Django 核心的八成内容。5. 新手最容易踩的坑与排查实录5.1 环境与启动类问题速查现象大概率原因解决办法No module named django虚拟环境没激活或装错环境检查命令前是否有(myenv)在正确的环境里pip install djangoImproperlyConfigured: ...settings.py 里有语法错误或引用了不存在的模块对照报错行号检查 settings启动后页面 200 但样式全没开发环境没配静态文件部署时才常见本地一般不影响功能先忽略port 8000 already in use端口占用runserver 8080换端口或杀进程改了models.py但表没变没执行 makemigrations/migrate按顺序跑这两个命令这里额外提醒一个很容易被忽略的问题Windows 上使用虚拟环境时偶尔会遇到执行activate被禁止执行的策略报错一般用激活脚本路径直接调用或者换 PowerShell 的 ExecutionPolicy 就能解决但这和治疗代码无关遇到时知道是环境权限问题就行。5.2 迁移与数据库的坑Django 的迁移系统设计得已经很自动了但有几个常见操作误区值得单独说。第一不要在没备份的情况下直接删迁移文件。有些人看到迁移文件越堆越多就手痒直接删掉整个migrations目录下的文件然后重新makemigrations如果数据库里的迁移记录和文件对不上等着你的就是各种莫名其妙的表结构错误。正确做法是保留迁移文件真有特殊情况再查文档重置。第二改了models.py的字段类型或加字段后要立刻重新生成迁移并执行。很多新手的流程是“改模型 → 刷新页面 → 报错了 → 再执行迁移”完全可以把顺序反过来每次改完模型先跑命令再调试。第三查询时小心 N1 问题。当一对多关系查询时光用objects.all()会先查一次主表然后每遍历一条数据又各查一次关联表100 条数据就会发出 101 条 SQL。解决方式是用select_related适合外键或prefetch_related适合多对多/反向关系一次性把关联数据查出来。新手阶段可能感觉不到性能差异数据量一上来这地方就是性能瓶颈。5.3 配置文件里的安全细节开发阶段为了省事很多人会把settings.py里的DEBUG一直保留为True这本身没问题。但如果你把DEBUGTrue的项目直接丢到线上那等于把自己的代码路径、配置信息、甚至数据库连接信息都暴露给访问者了。真正上线前至少要做三件事DEBUG设为FalseALLOWED_HOSTS里填上你的真实域名或 IP空或*都是有风险的状态换掉默认的SECRET_KEY这串字符是密码学签名的核心泄露了会被人伪造 session这些细节第一篇文章不展开但你先知道有这回事后面深入时就不会一脸懵。6. 一点个人建议第一篇教程到这里主线内容已经讲完了。最后分享几个我实操中觉得很有用的习惯。第一新建项目后不要急着写业务代码先跑一遍runservercreatesuperuser确认环境和后台都正常然后再开始加应用。这样每一步的“地基”都是稳的后面排查问题时能快速缩小范围。第二写视图和模板时多用 Django 自带的开发服务器实际测试别光在代码里埋头推演。打开浏览器点一点用 DevTools 看看请求是否正确返回比事后猜哪里错了高效得多。第三一定养成看报错日志的习惯。Django 的报错页是我用过的框架里最友好的页面顶部会直接告诉你异常类型、触发位置、关键代码上下文。很多人遇到红屏第一反应是截图问人其实自己读一遍最后几行大多数问题当场就能解决。这篇“Django 基础入门教程第一篇”先把 MTV 骨架和完整链路跑通后面第二篇可以深入讲模板继承、表单处理和用户认证。如果你想学的方向是写 API也可以把 ORM 和视图这块吃透后直接转 DRFDjango REST Framework路线都是通的。记住一个原则不要追求把概念背熟才开始动手先跑起来边做边理解这才是入门 Django 最快的方式。