想用 Python 做 Web 页面开发，第一个绕不开的名字就是 Django。我几年前第一次接触 Django 时，其实心里很没底——但认真把它的 URL 路由、视图函数和模板系统串起来之后，会发现页面开发的底层逻辑一下子通了。这篇文章就适合那些已经会一点 Python，但还没搞明白“一个网站页面到底是怎么被创造出来的”的人。我不会堆概念，只按我自己实际跑通项目的顺序来说：从环境准备到写出一个带数据库、带表单的页面，再到把 DEBUG 关掉之后还能正常显示，每一环你都可以直接跟着操作。
我之前见过不少初学者卡在半路，不是因为代码难，而是因为他们不知道“先做什么、后做什么”。所以这篇 Django 入门文，干脆把它当成一条修路工程：先铺地基（环境），再立骨架（项目和应用），然后接通水电（URL 和视图），最后装修（模板、静态文件、表单），再连上仓库（数据库）。每一部分我都尽量说清“为什么这么做”，以及对应会踩到什么坑。
1. 为什么一个“全家桶”式的框架更适合 Web 页面入门
1.1 新手做页面最容易失控的点
假设你只会 Python，想做一个“展示用户留言”的页面。没有框架时，你大概会写一个 Python 脚本去读文件，再拼一段 HTML 字符串，然后用某种方式把字符串发给浏览器。但问题很快就会出现：用户留言慢慢多起来，你需要处理不同的 URL，比如/list、/detail/3；页面里要循环输出留言；表单提交后要校验内容；数据得存进数据库，而不是每次重读文件。当你发现这些需求要同时满足时，所有代码都开始纠缠在一起，改一处崩三处。
这就是我推荐新手直接上大型框架的原因：Django 把“接收请求 → 匹配 URL → 调用处理函数 → 返回 HTML → 操作数据库”这一整套动作，用清晰的目录结构和约定好的接口固定下来。你不需要自己发明轮子，只需要把手放进正确的位置。很多人担心“全家桶”太重，但对入门来说，重反而意味着“有人替你把坑填好了”。
1.2 Django 解决的核心问题：URL、HTML 和数据的粘合
Django 自己也承认，它是一个“包含一切”的框架——ORM 帮你操作数据库，模板引擎帮你生成 HTML，表单库帮你处理用户提交，admin 后台帮你管理数据。一个页面请求进来之后，Django 会依次做这几件事：先根据用户访问的路径找到对应的 URL 规则；然后调用这个规则指向的视图函数；视图函数里可能读写数据库，也可能只是组装一些变量；最后把变量交给模板文件，渲染成完整的 HTML 返回给浏览器。
这个过程中最妙的一点是：你几乎不需要关心底层网络细节，你只需要按照“一份 URL 对应一个视图，一个视图渲染一个模板”的方式组织代码。对新手的价值特别大：页面是从哪里来的、数据是怎么出现的，心里有条非常清晰的线。当你理解了这条线，之后再去学更轻量的框架或者其他后端语言，都会觉得是似曾相识。
1.3 适合谁读这篇博文
如果你符合下面任意一条，这篇入门实践就很适合你：第一，会写print和for循环，但没写过一个真正能访问的网页；第二，曾经照着教程“敲”过 Django 代码，但搞不清urls.py、views.py、models.py之间怎么协作；第三，想用 Python 快速做一个带简单交互的原型页面，不想花太多时间在服务器配置上。这篇博文里的例子都很小，每一段都可以独立验证，你不用先完整看懂所有代码，跟着做出来，再回头琢磨，理解往往会更快。
2. 环境准备：Python 版本、虚拟环境和 Django 安装
2.1 版本选择背后的现实理由
很多初学者问的第一个问题是：“我该装哪个 Python 版本？”我的建议是装 Python 3.10 或者 3.11，然后选 Django 4.2 LTS。这不是追新，而是求稳。LTS 意味着官方会持续维护安全修复，第三方库生态基本都跟得上，网上搜到的问题解决方案也多。Python 3.12 当然也可以用，但偶尔会遇到一些原生库还没编译好对应 wheel 的情况，对一个只想先把页面做出来的人来说，这种额外障碍没必要。
安装之前，最好先确认一下当前环境里有没有其他项目在跑。如果你曾经用过系统自带的 Python，又直接pip install过一堆包，时间长了依赖会乱。这也是我强调“虚拟环境”的原因——它能让你每个练习项目都拥有一个独立的小仓库，装什么包都不会污染到别的项目。
2.2 创建虚拟环境与安装
先在你打算放项目的目录下打开终端（Windows 使用 cmd 或 PowerShell，macOS/Linux 使用自带终端），然后执行：
mkdir django-blog cd django-blog python -m venv venv这里的第一个venv是 Python 自带的虚拟环境模块，第二个venv是虚拟环境目录名，你可以按喜好改名。执行完成后，目录里会出现一个venv文件夹，里面有独立的 Python 解释器和 pip。接着激活虚拟环境：
# Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活成功后，终端提示符前面会多出(venv)字样。此时再安装 Django：
pip install "Django>=4.2,<4.3"这么做是为了避免装成未来的 Django 5.x。虽然新版功能更多，但一些第三方扩展可能还没适配，入门阶段先锁死在 LTS 版本里最省心。
2.3 验证安装成功的标志
安装完成后，可以用下面这条命令确认：
python -m django --version如果能输出类似4.2.11的版本号，说明 Django 已经就位。这里有个细节：如果你执行django-admin --version报“命令不存在”，而python -m django --version正常，说明你之前没有正确激活虚拟环境，或者系统里存在多个 Python。我建议统一用python -m django这种方式，它会严格使用你当前虚拟环境里的 Python，不会搞混。
到这里，环境就准备好了。接下来正式开始生成项目和页面。
3. 创建项目和应用：看懂 manage.py 生成的每一个目录
3.1 startproject 与 startapp 到底做了什么
在虚拟环境激活的状态下，执行：
django-admin startproject myblog cd myblog你会得到一个myblog文件夹，里面有一个manage.py和另一个也叫myblog的子目录。第一次看到这种嵌套目录时我也懵了一下：外层myblog是项目容器，里面的myblog是项目的“配置包”，存放着settings.py、urls.py、wsgi.py、asgi.py。manage.py是 Django 给你的命令行工具，以后启动开发服务器、执行迁移、创建应用都要靠它。
接着创建一个应用，应用才是真正存放页面逻辑的地方：
python manage.py startapp blog执行后会出现一个新目录blog，里面有views.py、models.py、migrations/等文件。可以这样区分：一个 Django 项目可以包含多个应用，比如一个博客系统可以有blog应用管文章、comments应用管评论。项目负责全局配置，应用负责具体业务模块。
3.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', # 新增这行 ]第二个是语言和时区。默认配置是英文环境和 UTC 时间，咱们国内访问时，页面时间会差 8 小时。你可以改成：
LANGUAGE_CODE = 'zh-hans' TIME_ZONE = 'Asia/Shanghai' USE_TZ = True这里注意：USE_TZ = True表示 Django 使用带时区的时间对象，存进数据库的是 UTC，渲染时按当前时区转换。日常写练习项目，你也可以保持这个默认值不动，只需把TIME_ZONE改了。
3.3 应用注册与第一个“Hello World”页面
先把最简单的动态页面跑通。打开blog/views.py，写一个函数：
from django.http import HttpResponse def index(request): return HttpResponse("Hello, Django Web Page!")然后在项目的myblog/urls.py里把 URL 指过去：
from django.contrib import admin from django.urls import path, include urlpatterns = [ path('admin/', admin.site.urls), path('', include('blog.urls')), ]此时还没blog/urls.py，需要新建一个：
from django.urls import path from . import views urlpatterns = [ path('', views.index), ]接着启动服务器：
python manage.py runserver浏览器访问http://127.0.0.1:8000/，看到Hello, Django Web Page!，说明你从零搭起的页面已经生效了。这个过程中，你其实已经走完了 Django 最核心的链路：浏览器 → URL 配置 → 视图函数 → 返回内容。后面所有复杂功能，都是在这条链路上分支扩展。
4. URL 路由、视图函数与请求生命周期
4.1 一次浏览器请求在 Django 里的完整旅程
当你在浏览器地址栏输入网址并回车，Django 做的事情可以拆成四步。第一步，开发服务器把原始 HTTP 请求包装成一个HttpRequest对象；第二步，Django 从urls.py的urlpatterns列表里从上到下匹配请求路径；第三步，找到匹配的视图函数后，把request对象传进去；第四步，视图函数返回一个HttpResponse对象，Django 再把它转成实际的 HTTP 响应发回浏览器。
你可以把 URL 配置想象成一个快递分拣台：每个快递（请求）上面有地址，分拣员（URL dispatcher）看到/blog/3就把包裹扔到对应编号的通道（视图函数）里。如果所有通道都没有匹配的地址，Django 就会返回 404 页面。这个过程决定了你写页面时的思维顺序：先想清楚用户会访问什么路径，再去编写对应的处理函数。
4.2 path() 函数与动态参数
页面路径不可能永远是写死的，比如文章详情页/article/1、/article/2，你不可能为每一篇都写一行 URL。Django 提供了动态路径参数：
from django.urls import path from . import views urlpatterns = [ path('', views.index), path('article/<int:article_id>/', views.article_detail), ]对应视图函数：
def article_detail(request, article_id): return HttpResponse(f"正在查看第 {article_id} 篇文章")这里<int:article_id>是一个路径转换器，int表示匹配整数，并把匹配到的值作为参数article_id传给视图函数。类似的还有str、slug等。当用户访问/article/999时，视图函数收到的article_id就是整数 999。如果访问/article/abc，则无法匹配，会走 404。
4.3 为什么视图函数必须返回 HttpResponse
初学者最容易忘的是：视图函数末尾必须return一个响应对象。如果你只写了def index(request):然后什么都不返回，页面会报错。原因是 Django 需要从视图函数的返回值中提取 HTTP 状态码和响应体，没有响应对象，它就没法继续向浏览器回话。
render()是视图函数中最常用的快捷方式，它的作用是把模板文件和变量结合起来，最终返回一个完整的 HTML 响应。比如：
from django.shortcuts import render def index(request): return render(request, 'blog/index.html', {'name': 'Ming'})这里render的三个参数分别是：请求对象、模板路径、传给模板的上下文数据。它会读取模板文件，渲染完成后自动封装成HttpResponse。理解了这个，你再看后面所有基于模板的页面，都不会觉得神秘。
5. 模板系统：用 Django Template Language 搭建真实页面
5.1 模板的基本语法：变量、标签和过滤器
为了不再返回“裸字符串”，我们需要把 HTML 抽出来放到模板文件里。Django 模板默认存放在应用目录下的templates文件夹。在blog目录下新建blog/templates/blog/index.html，目录结构决定模板的命名空间，避免不同应用之间的模板文件重名。
模板不是单纯的 HTML，它允许你嵌入动态表达式。变量用双花括号包裹，比如{{ name }}；逻辑语句用{% %}包裹，比如循环和判断。举个例子：
<!DOCTYPE html> <html> <head><title>My Blog</title></head> <body> <h1>欢迎，{{ name }}</h1> {% if articles %} <ul> {% for article in articles %} <li>{{ article.title }}</li> {% endfor %} </ul> {% else %} <p>还没有文章</p> {% endif %} </body> </html>过滤器通过管道符号|使用，例如{{ article.pub_date|date:"Y-m-d" }}可以把日期对象格式化成2025-01-01。过滤器还能处理默认值、计算长度等，记不住就去查文档，用多了自然就熟。
5.2 模板继承：告别复制粘贴页面
一个真实网站往往有导航栏、页脚，它们几乎出现在每个页面上。如果每个模板都复制一份导航栏代码，改一次要改十几个文件。Django 的解决办法是模板继承。
先写一个基础模板base.html：
<!DOCTYPE html> <html> <head> <title>{% block title %}默认标题{% endblock %}</title> </head> <body> <nav>这里是导航</nav> {% block content %}{% endblock %} <footer>这里是页脚</footer> </body> </html>子模板中通过{% extends "base.html" %}声明继承，然后覆写对应 block：
{% extends "base.html" %} {% block title %}文章列表{% endblock %} {% block content %} <p>这是子页面独有的内容</p> {% endblock %}这样做的好处是：页面的公共结构只需要维护一份；如果你想让某个页面与众不同，只要在它的 block 里写新内容就行。模板继承和{% include %}不同，include是把一个模板文件嵌入到当前模板中，适合复用小块组件，比如{% include "footer.html" %}。
5.3 页面中展示动态数据的小例子
我们结合前面的 URL 和视图来一个完整小例子。假设视图函数从列表里取出数据：
def article_list(request): articles = [ {"title": "Django 入门", "pub_date": "2025-01-01"}, {"title": "模板系统实践", "pub_date": "2025-01-02"}, ] return render(request, 'blog/index.html', {'articles': articles})模板里用{% for %}循环输出标题。这样做虽然数据还是硬编码在代码里，但已经能让你直观体会到“视图准备数据 → 模板负责展示”的分工。把硬编码换成数据库内容，只差后面的模型和查询一步。
6. 静态文件与表单：让页面带样式、能交互
6.1 静态文件的配置和使用
到目前为止，页面还是纯 HTML，没有 CSS 样式，也没有图片。Django 把这类文件统称为“静态文件”。开发模式下，你需要在settings.py里确认STATIC_URL = 'static/'，然后在应用目录里创建blog/static/blog/style.css，模板中就能这样引用：
{% load static %} <link rel="stylesheet" href="{% static 'blog/style.css' %}">这里有一个隐形坑：{% load static %}必须在使用了{% static %}的模板文件开头声明，如果是子模板继承了带样式的base.html，你不需要在每个子模板里重复加载，但 base.html 本身必须{% load static %}。加载后，Django 会拼出完整的静态文件路径，比如/static/blog/style.css。
6.2 最简单的 GET/POST 表单处理
页面要“交互”，最基础的方式是表单。我们做一个留言板，用户填名字和内容，提交后页面显示出来。先写一个视图：
from django.shortcuts import render from django.http import HttpResponse def message_board(request): if request.method == 'POST': name = request.POST.get('name', '') content = request.POST.get('content', '') return HttpResponse(f"收到来自 {name} 的留言：{content}") return render(request, 'blog/message_form.html')模板里放表单：
<form method="post"> {% csrf_token %} <input type="text" name="name" placeholder="你的名字"> <textarea name="content" placeholder="留言内容"></textarea> <button type="submit">提交</button> </form>这里request.method用来区分用户是第一次打开页面（GET）还是提交了表单（POST）。request.POST.get('name')是从 POST 请求体里取出表单字段值。当你点击提交后，页面会显示“收到来自 XX 的留言：XXX”。整个过程没有任何数据库参与，但你已经完成了“浏览器 → 服务器 → 浏览器”的一次完整交互闭环。
6.3 CSRF 防护：Django 为什么强制要求 token
上面模板里的{% csrf_token %}初看似乎多余，去掉之后你会立刻遇到403 Forbidden错误。这是 Django 的安全设计：CSRF（跨站请求伪造）攻击会诱导用户在不知情的情况下向某个已登录网站发送恶意请求。为了避免这个问题，Django 要求所有 POST 表单必须携带一个一次性随机 token，这个 token 与用户的会话绑定，服务器收到请求后会验证它是否合法。
你不需要成为安全专家才能用 Django，但要理解这条规则：不是 Django 故意刁难你，而是它在默认情况下帮你挡住了最常见的攻击类型。如果你用 JavaScript 的fetch提交表单，同样需要把 token 放进请求头，这一点等你日后写前后端分离项目时会再遇到。
7. 数据库模型与 admin：不写 SQL 也能管理页面数据
7.1 ORM 模型定义与迁移
前文的页面数据都是硬编码在 Python 列表里，这离真实项目还很远。Django 的 ORM（对象关系映射）让你用 Python 类来描述数据库表结构。以留言为例，在blog/models.py中写：
from django.db import models class Message(models.Model): name = models.CharField(max_length=50) content = models.TextField() created_at = models.DateTimeField(auto_now_add=True) def __str__(self): return f"{self.name}: {self.content[:20]}"写完模型后，需要执行两条命令：
python manage.py makemigrations python manage.py migratemakemigrations会根据模型变化生成迁移文件，migrate把迁移文件真正执行到数据库里。默认情况下，Django 会使用项目根目录下的db.sqlite3文件作为数据库，对入门练习来说完全够用，不需要额外安装 MySQL 或 PostgreSQL。你可以打开迁移文件看一眼，会发现里面就像一份“建表说明书”，包含了字段类型和约束。
7.2 在页面中读取数据库内容
现在留言视图可以改写为从数据库读取：
from django.shortcuts import render from .models import Message def message_board(request): if request.method == 'POST': name = request.POST.get('name', '') content = request.POST.get('content', '') Message.objects.create(name=name, content=content) messages = Message.objects.order_by('-created_at') return render(request, 'blog/message_list.html', {'messages': messages})Message.objects.create(...)等价于在数据库里插入一条记录；Message.objects.order_by('-created_at')按创建时间倒序取出全部留言。模板里可以这样展示：
<ul> {% for msg in messages %} <li>{{ msg.name }}：{{ msg.content }}（{{ msg.created_at|date:"Y-m-d H:i" }}）</li> {% empty %} <li>还没有留言</li> {% endfor %} </ul>此时如果你清空数据库重新跑流程，提交几条留言后刷新页面，会发现数据已经持久化：即使重启服务器，历史留言也不会丢。这就是 ORM 带来的直观成就感——你不用写任何 SQL，却完成了一个带存储的真实功能。
7.3 admin 后台：免费送你一个数据管理界面
Django 自带的后台管理界面是它最吸引新手的特性之一。首先创建管理员账号：
python manage.py createsuperuser按照提示输入用户名、邮箱、密码。然后打开blog/admin.py，注册模型：
from django.contrib import admin from .models import Message admin.site.register(Message)访问http://127.0.0.1:8000/admin/，用刚创建的账号登录，你就能看到一个可视化管理页面，可以增删改查留言数据。你可以在后台删除某条不当留言，再回前台刷新验证。这个后台对于快速原型、内容管理、甚至小型内部系统都非常实用，也是很多人爱上 Django 的原因之一。
8. 上线前检查清单：DEBUG、ALLOWED_HOSTS 和静态文件收集
8.1 DEBUG=False 后的页面直接白屏？原因是这些
开发时你一直开着DEBUG = True，Django 会为你提供详细的报错页面，并自动用开发服务器处理静态文件。但把项目部署到公网时，你必须把DEBUG设为False，否则一旦代码报错，浏览器会直接把异常堆栈和本地路径暴露给用户，非常危险。
但新手往往刚把DEBUG改成False就傻眼了：页面白屏，CSS 全丢了，甚至访问后台也打不开。原因是runserver默认只在 DEBUG 模式下服务静态文件，关闭调试后，静态文件需要由 Django 收集到一个统一目录，再由部署层（比如 Nginx 或者其他 WSGI 服务器）去托管。开发时你可以继续用runserver调试，但一旦为了保证安全改了DEBUG，就要同步处理静态文件。
8.2 静态文件收集与白名单配置
在settings.py末尾追加：
ALLOWED_HOSTS = ['your-domain.com', 'www.your-domain.com'] STATIC_ROOT = BASE_DIR / 'staticfiles'这里的ALLOWED_HOSTS用来声明哪些域名可以访问你的 Django 服务。如果你部署后只是临时测试，可以写成ALLOWED_HOSTS = ['*']，但正式环境不要这么做，会让你的站点可以被任意 Host 请求访问。然后执行：
python manage.py collectstaticDjango 会把所有应用里的静态文件复制到STATIC_ROOT指定的目录，也就是staticfiles文件夹。如果你用runserver测试DEBUG=False，它仍然不负责服务这些静态文件，你需要借助符合 WSGI 规范的中间件来支持，或者让前置的 Web 服务器去处理。不过入门阶段，你只要知道流程是这样：开发时静态文件自动处理，部署时手动收集。
8.3 我个人每次部署前必查的三个点
根据我自己的经验，上线前与其看一堆部署文档，不如先检查这三件事。第一，DEBUG是否真的为False，并且ALLOWED_HOSTS里写的是实际域名而不是*。第二，collectstatic是否已经执行过，并且staticfiles目录里的 CSS/JS 文件引用的路径和模板中{% static %}输出的一致。第三，数据库有没有运行过完整迁移，最好是在全新环境从零开始migrate一遍，防止某些表在开发环境里早就建立，换台机器就漏了。
你还可以用一条命令检查完大部分配置问题：
python manage.py check --deploy它会输出几条安全警告，比如你仍开着 DEBUG、没有设置安全密钥的存储方式等。哪怕是警告，也值得逐条读懂。这个命令提示的内容，往往就是新手最容易忽略的上线死角。
说回个人体会：我最初做完这个入门流程后，并没有急着去做大项目，而是把所有小片段故意“改坏”再修好。比如把视图函数的返回类型改成字符串、忘记在表单里写 CSRF token、在模板继承时写错 block 名字。把每个错误都亲眼看到一次，比看十遍文档记得牢。这也算是我推荐的学习方式——先让页面跑起来，再把它弄坏，最后自己修好，这个过程里建立的底层逻辑，能帮你应对后面更复杂的功能开发。
