企业官网建设流程全解析

Django官网那套“编写你的第一个应用”的demo，也就是经典的投票应用polls，我前前后后跟写过三遍。第一遍是纯新人阶段，跟着点下一步，跑通hello world就觉得自己会了；第二遍是做内部培训前，自己先重写一遍，发现很多细节第一次根本没理解；第三遍是带新人时，一边看着他们踩坑一边又过了一遍。说实话，这个demo含金量被严重低估了，它不是简单的“官网教程”，而是理解Django核心设计哲学“MVT”最顺滑的一条路径。

如果你刚接触Django，或者爬了不少教程但总觉得知识是零散的，这个项目值得从头到尾亲手敲一遍，特别注意是亲手敲，不是复制粘贴。它能让你在一两个小时内看到一个完整的Web应用是怎么从零长出来的：项目结构怎么组织、请求怎么从URL走到视图、数据怎么存进数据库、页面怎么渲染出来。这篇文章我会按自己做这个demo的完整过程来写，把每一步的“为什么”也讲清楚，顺带把新手最容易卡住的那几个点单独拎出来说透，看完你不仅能跑通demo，还能知道该怎么往实战项目方向改。

1. 官网demo到底在教你什么

1.1 不是hello world，是一套完整的MVT体验

很多Web框架的入门教程止步于“如何在浏览器里打印一句话”，Django的demo直接给了你一个完整的投票系统雏形：有模型（问题、选项）、有视图（列表页、详情页、结果页、投票动作）、有模板（页面展示）、有后台（admin管理）、还有表单和测试。这其实就是Django官方想让你理解的MVT架构：Model负责数据层，Template负责展示层，View负责业务逻辑，而URLconf负责把请求交给对应的View。

整个过程下来你会发现，它不是在教“写一个页面”，而是在教“Django项目里的一个功能模块应该长什么样”。我见过太多人学Django先啃源码、啃中间件、啃信号机制，结果越学越晕。其实跟着demo走一遍，这些概念以后再接触会有一种“原来它在整个请求链里的位置是这样的”的顿悟感。所以这个demo真正的价值，是给你后续深入学习搭一副骨架。

1.2 用什么姿势跟做效果最好

我的建议是，不要打开教程复制粘贴就跑，那样跑完等于没跑。正确姿势是：先读一遍某一步的说明，理解它要干什么，然后关掉教程或者最小化窗口，自己在编辑器里敲出来。敲不出来再回去看，这个过程比你看十遍都有用。另外，Django的官方文档是没有幻觉的，里面每个代码块都对应着实际可运行的项目，这一点优于很多二手博客的碎片教程，二手教程经常因为版本不同少参数或者报错。

如果英语看着吃力，中文翻译版也可以，但遇到报错提示尽量看英文原文。Django的报错信息其实写得很良心，它通常会告诉你“缺什么”“在哪一行”“怎么改”，前提是你不要只看最后一行红色加粗，而是往上翻，看完整的Traceback。后面我会专门讲排查方法，这里先记住这个习惯。

2. 环境准备与项目初始化

2.1 虚拟环境：这一步省了，后面全是眼泪

项目开始的第一步不是pip install django，而是建虚拟环境。虚拟环境说白了就是给你这个项目单独开了一间小房间，里面装了它自己的Python解释器、自己的依赖库，跟系统全局环境互不干扰。为什么要这样？因为你手头可能同时有多个Django项目，有的用Django 4.2，有的用Django 5.0，有的Python版本都不同，如果全装到全局环境里，版本冲突会让你怀疑人生。

# 在项目根目录下执行 python3 -m venv venv source venv/bin/activate # Windows环境下用 venv\Scripts\activate

激活后命令行前面会出现（venv）前缀，这时候再装依赖就进“小房间”了。然后安装Django：

pip install django

装完可以用python -m django --version确认版本。新手阶段我建议直接用最新稳定版，比如Django 5.x，官方demo的写法对版本是有要求的，老版本的教程代码在新版本下跑会有兼容问题，但只要你跟的是官网当前版本的教程，就不会有这种烦恼。

2.2 创建项目和应用：分清两个start

环境准备好后，核心两条命令：

django-admin startproject mysite cd mysite python manage.py startapp polls

这两条命令分工完全不同：startproject创建的是整个项目的“容器”，包括全局配置文件settings.py、主路由urls.py、以及manage.py这个管理工具入口；startapp创建的则是一个具体的功能应用模块，比如这里的polls，它自带models.py、views.py、admin.py等文件。你可以把“项目”理解为一栋办公楼，“应用”是楼里的一个个公司或部门，一个项目可以塞多个应用，应用之间要保持相对独立，方便复用。

我见过不少新手直接把所有代码堆在项目的views.py里，从demo开始就要养成“一个功能一个app”的意识。官网demo里项目叫mysite，应用叫polls，本身就是很好的示范。创建完应用后，还得在settings.py的INSTALLED_APPS列表里把polls加进去，Django才知道“我楼里有这个部门”。

# settings.py INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'polls', # 加上这一行 ]

这一步漏掉的话，后面你makemigrations会发现模型装进空气里，因为Django根本不知道有polls这个应用存在。

2.3 第一次启动服务器：跑通了，然后呢

项目创建好、app注册好，就可以跑一下试试：

python manage.py runserver

浏览器访问http://127.0.0.1:8000/，看到火箭起飞页面就说明搭建成功。这里有几个小提示：Django的开发服务器是自带自动重载的，你改代码保存后它会自动重启，不用手动反复执行runserver；端口被占用时可以在后面加参数，比如python manage.py runserver 8080；另外这套服务器只适合开发，千万别用它撑线上流量，后面对并发有要求时要换uWSGI或Gunicorn这类WSGI服务器。

第一次看到火箭页的时候，不会有什么交互逻辑，但你要确认几件事：URLconf在跑、模板系统在跑、静态文件服务在跑（火箭页就依赖静态文件）。如果这步有问题，先排查环境，别急着往后写代码。

3. 从URL到视图，第一个页面是怎么出来的

3.1 路由匹配：Django怎么知道把请求发给谁

Django处理请求的顺序大致是：浏览器发来一个URL，比如/polls/1/，请求先到达项目级的主路由mysite/urls.py，主路由再把请求“分包”给各应用的子路由。这就像写字楼的快递收发室先看快递单上的“公司名”，然后把快递放到对应公司的柜子里。

主路由里这样写：

from django.contrib import admin from django.urls import include, path urlpatterns = [ path('admin/', admin.site.urls), path('polls/', include('polls.urls')), ]

这里的include('polls.urls')意思是：凡是URL以polls/开头的请求，都交给polls这个应用自己的urls.py去处理。所以接下来要在polls应用里新建一个urls.py：

# polls/urls.py from django.urls import path from . import views urlpatterns = [ path('', views.index, name='index'), ]

注意这里的URL路径是空字符串，因为它承接的是主路由里/polls/之后的剩余部分。访问http://127.0.0.1:8000/polls/时，Django先剥掉/polls/，剩下的空字符串正好匹配上。这种“主路由分发、子路由具体匹配”的设计，让每个应用的路由互不干扰，是Django项目结构清晰的根基。

3.2 视图函数：从HttpRequest到HttpResponse

路由匹配到的views.index就是一个视图函数。视图是Django里真正干活的地方，它接收一个HttpRequest对象，经过处理后返回一个HttpResponse对象。demo第一章的视图简单得离谱：

# polls/views.py from django.http import HttpResponse def index(request): return HttpResponse("Hello, world. You're at the polls index.")

这里有两个值得理解的点。第一，为什么视图必须接收request参数？因为请求相关的所有信息——路径、请求方法、请求头、用户session、表单提交的数据——都挂在这个request对象上，你后面取数据、做判断都得通过它。第二，为什么必须返回HttpResponse？因为Django底层是一个严格遵循“请求-响应”循环的框架，视图是整个链条的终点站，你把内容包装成HttpResponse后，Django才有一套标准化的东西交给服务器最终返回给浏览器。

3.3 动态路径与404：页面开始有灵魂了

光返回固定字符串肯定不够。官网demo紧接着教你设计“问题详情页”，也就是URL里带参数：/polls/1/代表查看id为1的问题。路由这样写：

# polls/urls.py path('<int:question_id>/', views.detail, name='detail'),

这里的<int:question_id>是Django路径转换器的语法，它会从URL片段里捕获一个整数，命名为question_id，作为参数传给视图函数。如果你访问/polls/abc/，Django会直接返回404，因为abc不是整数，根本匹配不上这个路由规则。

视图里怎么处理这个参数？demo的写法是先用get方法尝试取出对应问题，查不到就抛404：

# polls/views.py from django.http import HttpResponse, Http404 from .models import Question def detail(request, question_id): try: question = Question.objects.get(pk=question_id) except Question.DoesNotExist: raise Http404("Question does not exist") return HttpResponse(f"You're looking at question {question.id}.")

这里已经涉及模型查询了，你可能会好奇Question对象哪来的，别急，下一步就是它。f-string和Http404的组合在后来的实战中很常用，遇到查不到数据的场景，抛404比硬着头皮渲染空页面要规范得多。

4. 模型、数据库与管理员后台

4.1 定义模型：用Python类描述一张数据表

Django里写模型，本质是在用Python代码描述数据库表长什么样。demo里关于问题（Question）和选项（Choice）的定义是教科书级的例子：

# polls/models.py from django.db import models class Question(models.Model): question_text = models.CharField(max_length=200) pub_date = models.DateTimeField('date published') def __str__(self): return self.question_text class Choice(models.Model): question = models.ForeignKey(Question, on_delete=models.CASCADE) choice_text = models.CharField(max_length=200) votes = models.IntegerField(default=0) def __str__(self): return self.choice_text

这里的信息密度非常大，新手很容易只盯着语法看。实际上这三块内容直接对应数据库的核心概念：models.Model是让类变成“可迁移模型”的基类；CharField/DateTimeField/IntegerField这类字段类型决定数据库列的类型和约束；max_length=200、default=0对应字段长度和默认值；ForeignKey代表外键，on_delete=models.CASCADE表示关联的Question被删掉时，这个选项跟着一起删。

用一句人话概括：写模型 = 画数据库设计图，Django根据这张图去数据库里建真正的表。

4.2 迁移机制：为什么不用手动建表

模型写好后，执行两步操作：

python manage.py makemigrations polls python manage.py migrate

第一次接触Django的人都会觉得这步很玄乎。makemigrations是“把模型的变化写成一份迁移文件”，迁移文件其实就是一个Python脚本，描述了“我要在数据库里执行哪些建表/改表的SQL操作”；migrate是把这份脚本真正执行到数据库里。想要看Django要执行的SQL长什么样，可以用python manage.py sqlmigrate polls 0001预览，看完你会对这两个命令的分工有更具体的感觉。

为什么要有中间这层“迁移文件”而不是直接建表？因为项目是要演进的。今天你加一个字段，明天改一个长度，如果每个人都在数据库里手动改表，团队协作当场就乱了。迁移文件是历史记录，谁从git拉完代码，执行migrate就能把数据库结构同步到最新状态，这比人工记账靠谱太多。

4.3 ORM查询实战：执行查询和删除对象的正确姿势

从这步开始，对应热词里“django执行查询 删除对象”的内容就来了。Django的ORM（对象关系映射）让你可以用Python方法操作数据库，而不用写SQL。进交互环境最直接：

python manage.py shell

在shell里，你可以立刻实践增删改查：

from polls.models import Question, Choice from django.utils import timezone # 新增：创建一条Question数据 q = Question(question_text="你最喜欢的编程语言是什么？", pub_date=timezone.now()) q.save() # 查询：一次取出所有数据 Question.objects.all() # 查询：按条件过滤，get拿单条，不存在会抛异常 Question.objects.get(id=1) Question.objects.filter(question_text__contains="编程") # 修改：直接改属性再save q.question_text = "你更偏好哪个语言？" q.save() # 删除：调用delete() q.delete()

几个坑要提前说。第一，get查询不到会抛DoesNotExist，查到多条会抛MultipleObjectsReturned，所以只适合查必须是唯一一条的场景；第二，filter返回的是一个QuerySet，也就是一组结果集，可以继续链式调用，比如.filter(...).order_by('-pub_date')；第三，delete()是真实删除，没有后悔药，连外键关联的数据也会按on_delete规则一起处理，所以生产环境里删除前一定要想清楚，或者干脆用软删除（加一个is_active字段标记）代替真删。

ORM的好处是省去了手写SQL，但你要心里清楚它生成的SQL是什么逻辑，不然数据量大时会出现经典的N+1查询问题，这个我们以后再细说。

4.4 admin后台：Django白送的一套管理系统

当你执行python manage.py createsuperuser创建管理员账号，然后在admin.py里注册模型：

# polls/admin.py from django.contrib import admin from .models import Question, Choice admin.site.register(Question) admin.site.register(Choice)

之后再访问/admin/，登录后就可以在页面上直接增删改查问题、选项了。这个后台不是玩具，很多企业内部系统的管理界面就是直接基于admin改造的。它之所以能即插即用，是因为Django在创建项目时默认开启了django.contrib.admin应用，这个应用通过读取你注册的模型信息，自动生成对应的管理页面。

到这里，你已经看到了一个完整Web应用的闭环：用户请求 → 路由 → 视图 → 模型 → 数据库 → 后台管理。剩余的就是把展示层做得更漂亮，也就是模板和静态文件。

5. 模板、静态文件与新手必踩的坑

5.1 static文件配置：img标签图片显示不出来的真相

热词里有一条非常典型：“vscode写img标签在django的static文件中显示不了”。这个问题十个Django新手八个遇到过，根因是很多人把HTML里<img src="...">的路径当成普通文件路径来写了，但Django里静态资源必须通过static模板标签或绝对URL来引用。

如果你直接在polls应用里放了一个静态图片，目录结构长这样：

polls/ static/ polls/ images/ logo.png

模板里正确的写法是：

{% load static %} <img src="{% static 'polls/images/logo.png' %}" alt="logo">

为什么路径里有两层polls？第一层是应用下static目录的固定约定，Django会自动去每个应用的static目录找资源；第二层是命名空间，防止多个应用有同名静态文件时互相覆盖。如果你把图片放在了项目根目录下，比如assets文件夹，那还要在settings.py里配置：

# settings.py STATICFILES_DIRS = [ BASE_DIR / "assets", ]

很多教程没说清楚的是：开发阶段Django是帮你“临时托管”静态文件的，所以{% static %}能转换成可访问的URL；到了生产环境，不推荐让Django继续托管静态文件，而是执行collectstatic把所有静态文件收集到一个统一目录，交给Nginx这类服务器处理。

排查这个问题有个极快的办法：直接在浏览器里访问图片的URL，比如http://127.0.0.1:8000/static/polls/images/logo.png，如果能访问到说明Django这边没问题，问题在HTML的引用写法上；如果404，则是文件位置或STATIC配置不对，按上面两步检查。

5.2 模板继承：告别每一个页面都复制粘贴head

demo进行到一定阶段，页面多了，你会发现每个模板都有一大段重复的HTML结构，比如头部导航、底部版权、CSS引用的head。Django的模板继承机制就是为这个而生的。

先做一个base.html：

<!-- templates/base.html --> <!DOCTYPE html> <html lang="zh"> <head> <meta charset="UTF-8"> <title>{% block title %}投票站{% endblock %}</title> </head> <body> <header>这是一个投票系统</header> {% block content %} {% endblock %} </body> </html>

子模板继承它：

<!-- polls/templates/polls/detail.html --> {% extends "base.html" %} {% block title %}{{ question.question_text }}{% endblock %} {% block content %} <h1>{{ question.question_text }}</h1> <form action="{% url 'polls:vote' question.id %}" method="post"> <!-- 表单内容 --> </form> {% endblock %}

关键语法就两个：base里用{% block name %}挖坑，子模板里用{% extends "base.html" %}声明“我是基于哪个母版”，然后用{% block name %}来填坑。这套机制避免了你每次新增页面都复制几十行模板导致的维护噩梦。

5.3 表单提交与CSRF：新手第一道坎

demo第三步要做投票，表单必然用到POST。POST和GET最大的区别在于它有“副作用”，会修改服务器数据，所以Django强制要求POST请求必须带CSRF令牌来防跨站攻击。模板里表单要有这一行：

{% csrf_token %}

如果漏了这行，提交表单会直接报403 Forbidden。我第一次跑demo时就卡在这，当时还以为是表单action写错了。后来才知道这是Django很贴心的一层保护，默认给所有POST请求上了锁，防止恶意网站诱导用户提交数据到你的服务器。你在开发时如果临时想放弃这个校验，可以注释掉CSRF中间件，但绝对别在产品环境这么干。

视图里接收POST数据也有讲究：

# polls/views.py from django.shortcuts import get_object_or_404, render, redirect from django.http import HttpResponseRedirect from django.urls import reverse def vote(request, question_id): question = get_object_or_404(Question, pk=question_id) try: selected_choice = question.choice_set.get(pk=request.POST['choice']) except (KeyError, Choice.DoesNotExist): return render(request, 'polls/detail.html', { 'question': question, 'error_message': "你还没选择选项。", }) else: selected_choice.votes += 1 selected_choice.save() return HttpResponseRedirect(reverse('polls:results', args=(question.id,)))

注意这里用了一个模式：成功操作后执行重定向（PRG模式），而不是直接渲染结果页。这样用户刷新页面时不会重复提交投票。这个细节看起来不起眼，但体现了Web开发里的一个经典问题：表单重复提交。我见过不少项目因为少了这一步，一刷新就多一条垃圾数据。demo在这里点到即止，但等你做自己的项目时，凡是POST成功的请求，都应该重定向到一个GET页面。

另外一个新手容易晕的点是reverse('polls:results', args=(question.id,))。它做的事情是“根据路由name反向生成URL”，这样你以后改了路径也不用全项目搜索硬编码的URL去替换，只要name不变就一切照旧。

6. 从demo走向实战：三个常见扩展方向

6.1 权限控制：RBAC在Django里的落地思路

demo做完后，很多人会问：我这系统谁都能改数据怎么办？这就涉及热词里的RBAC（基于角色的访问控制）。RBAC的核心模型很简单：用户有角色，角色有权限，用户通过角色间接获得权限。不用被“权限模型”四个字吓到，拆开就是三张核心表：用户表、角色表、权限表，再加上用户和角色的关联表、角色和权限的关联表。

Django其实已经内置了这套机制的核心，就是auth应用里的User、Group和Permission模型。你可以在admin后台给用户分配群组，给群组配置权限，代码里再用装饰器控制视图的访问：

from django.contrib.auth.decorators import login_required, permission_required @login_required def my_view(request): ... @permission_required('polls.can_vote') def vote(request, question_id): ...

login_required要求用户必须登录，没登录就跳到登录页；permission_required要求用户有指定权限，否则返回403。这就是RBAC在Django里的最小落地，等业务复杂了再扩展自定义权限模型，比如按数据归属限制访问范围。新手做项目时别一上来就设计复杂的权限表，先用Django自带的，踩过坑再自己造轮子。

6.2 实时推送：WebSocket与后台数据推送

另一个热词是“django websocket实现后台有数据前端推送”。如果你做的是后台管理系统，比如运营后台有新订单就实时弹个提示，传统做法是前端定时发GET请求去轮询“有没有新数据”，这样既有延迟又浪费资源。WebSocket则是让前后端保持一条长连接，服务器可以直接往这条连接里推数据。

Django原生是处理HTTP请求的，处理WebSocket需要借助Channels库，它把Django升级成了同时支持HTTP和WebSocket的框架。最小实现思路是这样：pip安装channels，把它加进INSTALLED_APPS，配置ASGI_APPLICATION，然后写一个Consumer类：

# consumers.py from channels.generic.websocket import WebsocketConsumer from channels.layers import get_channel_layer from asgiref.sync import async_to_sync class ChatConsumer(WebsocketConsumer): def connect(self): self.accept() self.room_group_name = 'notifications' async_to_sync(self.channel_layer.group_add)(self.room_group_name, self.channel_name) def notify(self, event): self.send(text_data=event['content'])

当后台其他地方有数据变化时，可以通过channel layer往这个group里发消息，所有连着的WebSocket都会收到。这套机制的核心思想是“发布-订阅”：后台是发布者，前端建立的长连接是订阅者，中间通过channel_layer做消息转发。做这个功能时要注意生产环境的channel layer要换成Redis，不能用默认的InMemory，不然多进程下消息会丢。

不过我得说句大实话：demo本身不会教你WebSocket，但做完demo你有了Django的请求处理基础，再看Channels会顺利得多，因为内核还是那套“路由-视图-数据”的逻辑，只是协议从HTTP换成了WebSocket。

6.3 工程化：从demo项目到真实项目的必要改动

demo项目在本地跑没有问题，拿到实际部署场景，至少有三件事要做。第一，settings.py里不能用明文密钥、不能把DEBUG开成True、数据库账号密码要放到环境变量里；第二，静态文件要执行collectstatic收集到统一目录，让Nginx托管；第三，要用Gunicorn替代runserver。这些都是demo不会写但实战必须自己补的功课。

我接触过很多朋友，做demo时很顺利，一上云服务器就寸步难行，基本都倒在这三件事上。解决方案不复杂，核心是建立“配置隔离”意识：日常开发一套配置，生产一套配置，通过环境变量切换。这比在代码里硬编码一堆敏感信息要安全得多，也方便团队协作。

7. 常见问题速查与调试心得

7.1 新手最容易卡住的坑一览

我根据自己踩过的坑和带新人时被问得最多的问题，整理了一份速查表，先看清现象再对号入座。

这张表列的都是demo阶段的高频问题，每一条我都实际碰到过。尤其“图片不显示”和“403 CSRF”，在带新人的时候至少出现一半的人身上。

7.2 我用得最多的排查方法和工具

遇到报错，先别慌，记住一个原则：看完整的Traceback，不要只盯最后一行的红色文字。Traceback是从上往下按调用栈排列的，你项目里的文件路径通常出现在中间偏下的位置，那一行才是你代码真正出问题的地方，系统内置文件的报错往往只是上层调用被带崩了。

第二个好用的工具是django-debug-toolbar，pip安装后在settings里配置一下，页面左下角会出现一个调试面板，能看到当前页面的SQL查询、请求耗时、模板变量等。新手装上它最大的收益是快速确认“视图里的查询到底执行了几次”，能直观理解ORM的行为。demo阶段其实不需要它，但第一个实战项目可以装上。

第三是python manage.py shell，它比写完整页面调试快得多。比如你不确定某个ORM查询结果对不对，直接在shell里跑一遍就知道。再配合django_extensions里的shell_plus，会自动帮你导入所有模型，省去手动import的时间。

我个人的调试习惯是：先在视图函数里加临时print，看看变量到底是什么值，再决定下一步修哪里。等逻辑调通了，再把这行print去掉或改成日志。现在虽然有很多高级调试器，但print调试在Web开发里依然是最快的路径，因为问题往往不是你想象的那么复杂，先确认数据和流程，比对着代码空想要有效一千倍。

最后补充一点实操体会

我把官网demo完整跑过多遍之后，最大的体会是：这个项目其实是个“活教材”，你完全可以把它改成自己的专属学习沙盒。比如把投票主题改成“你今天喝什么咖啡”，加上用户登录，加上图表展示投票结果，一点一点在demo的骨架上加肉。这个过程遇到的问题，才是真正属于你的经验。另外，建议你把官方英文原文里的每一段说明都读一遍，而不是只看代码，因为Django官方文档的叙述里埋了很多“为什么”，这些是二手教程最常遗漏的东西。第一次跑通不是终点，能用自己的话把这套流程讲给另一个人听，才是真的入门了。