简介这是一份面向Python初学者与Web开发入门者的Django基础实践项目源码旨在帮助开发者快速掌握Django框架核心流程包括项目结构搭建、URL路由配置、视图逻辑编写、模板渲染及用户登录功能实现。资源共40个文件含13个关键.py源码如settings.py、urls.py、views.py、models.py等、24个.pyc编译文件体现多版本Python兼容性、1个readme.txt说明文档、1个poem.html前端模板及1个轻量级db.sqlite3数据库文件整体压缩包仅155KB便于快速下载与本地运行。已有480人学习下载适合教学演示、课设参考或自学练手。读者可直接部署运行直观理解Django MTV模式下各模块协同机制掌握manage.py常用命令、静态资源组织方式及基础用户认证流程为后续开发复杂Web应用打下扎实结构认知基础。1. 为什么一个“简单 Django Web 项目”比你想象中更值得从头敲一遍不是所有标着“简单”的 Django 项目都配叫「可落地的入门锚点」。我见过太多新手直接 clone 一个带 Vue 前端、Celery 异步、Docker Compose 三件套的“教学项目”结果卡在pip install -r requirements.txt第二行——因为里面混了psycopg2-binary2.9.7和Django4.2.11而他本地是 macOS M1 Python 3.12连编译器都报错“clang: error: unsupported option -fopenmp”。真正的“简单”不是功能少而是依赖干净、路径可控、错误可逆、每一步都能看见数据流怎么走。这个标题下的“基于 Python 的简单 Django Web 项目设计源码”核心价值在于它用最窄的接口暴露 Django 的骨架逻辑——URL 怎么映射到视图、模型怎么生成迁移、模板怎么接收上下文、管理后台怎么自动绑定字段。它不教你部署 Nginx但教会你python manage.py runserver --noreload --ipv6这条命令背后到底 reload 了什么、为什么关掉它能让 VS Code 断点稳定命中。适合刚写完print(Hello World)、正卡在“Django 创建 app 后不知道下一步该改哪个文件”的人也适合想快速验证某个小需求比如用户提交表单后发邮件、上传 CSV 自动生成图表是否能在 Django 框架里闭环的人。它不是玩具是能立刻 fork、删掉polls/目录、换成你自己的inventory/或sensor_log/并跑通的最小可信基线。2. 从零初始化用 django-admin 创建纯净项目骨架避开 pipenv/virtualenv 冲突陷阱2.1 为什么不用 pipenv 或 poetry先用系统级 virtualenv 稳住第一公里很多教程一上来就推pipenv install django结果新手在 Windows 上遇到Pipfile.lock not found在 Linux 上被pipenv shell卡住半天。真实产线中Django 官方文档明确推荐用 Python 自带的venv模块创建隔离环境再用pip安装。它不依赖额外工具链错误信息直白重装成本低——删掉venv/文件夹就行。尤其当你后续要对接 CI/CD比如 GitHub Actions 的ubuntu-latestrunnervenv是默认预装模块而pipenv需要额外pip install pipenv步骤徒增失败点。# 推荐用 Python 3.9 自带 venv避免 pyenv 版本混乱 python -m venv ./myproject_env source myproject_env/bin/activate # Linux/macOS # myproject_env\Scripts\activate.bat # Windows # 升级 pip 到最新稳定版关键旧 pip 会解析错某些 wheel 元数据 pip install --upgrade pip # 安装 Django —— 注意不指定版本号用最新 LTS当前为 4.2.x pip install Django4.2,4.3提示Django4.2,4.3这种写法比Django4.2.11更安全。Django 4.2.x 系列有持续的安全补丁更新如 4.2.12 修复了 CVE-2023-43665硬锁版本会错过热修复。LTS 版本支持周期长达 3 年足够覆盖一个小型项目生命周期。2.2 django-admin startproject必须加--template参数才能真正“简单”django-admin startproject mysite生成的默认结构包含mysite/__init__.py,settings.py,urls.py,asgi.py,wsgi.py—— 看似干净实则埋雷。settings.py里默认启用了DEBUGTrue、ALLOWED_HOSTS[*]、SECRET_KEY是明文字符串新手常忘记改导致上线后被扫描器爆破。更隐蔽的是DATABASES配置默认用 SQLite但NAME路径写成BASE_DIR / db.sqlite3在某些 IDE如 PyCharm里 BASE_DIR 解析可能出错导致makemigrations报No module named mysite。解决方案用自定义模板跳过这些坑。我们准备一个极简模板仅含必要文件通过--template注入# 创建模板目录只需一次 mkdir -p django-simple-template/{project_name,project_name/settings} # 下载精简模板此处用 curl 演示实际可 git clone curl -sSL https://raw.githubusercontent.com/django-templates/simple-lts/main/template.zip -o template.zip unzip template.zip -d django-simple-template # 用模板初始化项目关键--name 替换模板内占位符 django-admin startproject mysite . --template./django-simple-template --namemysite该模板的核心改造settings.py中DEBUG默认FalseALLOWED_HOSTS初始化为空列表[]强制你在部署前显式配置SECRET_KEY读取环境变量os.environ.get(DJANGO_SECRET_KEY)避免硬编码DATABASES配置为sqlite3但路径用Path(__file__).resolve().parent.parent / db.sqlite3绝对路径鲁棒性更强删除asgi.pyWebSockets 不是“简单项目”必需只保留wsgi.py。2.3 创建第一个 appstartapp后必须手动注册且顺序影响中间件加载python manage.py startapp core生成core/目录后很多人以为完事了。但 Django 的INSTALLED_APPS是一个有序列表app 的注册顺序决定了模型加载、信号注册、模板查找路径的优先级。例如如果你把自定义core放在django.contrib.admin之后那么core/templates/admin/下的模板将无法覆盖 admin 默认模板因为 Django 按INSTALLED_APPS顺序扫描templates/目录。正确做法在settings.py的INSTALLED_APPS中把你的 app 插入到django.contrib.staticfiles之前、django.contrib.admin之后# settings.py INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, # ↓ 新增你的 app 必须在这里 core, # 注意字符串名不是 core.apps.CoreConfig ]注意core是 app 目录名不是apps.py里的类名。只有当你需要自定义 AppConfig如重写ready()方法时才写core.apps.CoreConfig。对“简单项目”字符串名足够且更不易出错。3. 模型与迁移用models.py定义业务实体但makemigrations的三个隐藏开关决定能否回滚3.1 设计core/models.py从models.Model继承但字段命名必须遵循数据库友好原则“简单项目”常犯的错用 Python 变量习惯命名字段比如user_name、is_active_flag。这会导致两个问题一是 Django Admin 自动生成的列标题变成User name、Is active flag多出空格和冗余词二是未来如果迁移到 PostgreSQL字段名带下划线虽合法但与snake_case规范冲突影响团队协作。正确姿势是字段名即业务语义名不加后缀用单数名词。# core/models.py from django.db import models from django.contrib.auth.models import User class SensorReading(models.Model): 传感器读数记录温度、湿度、时间戳 # 关键字段名直接表达业务含义不加 _id 或 _flag temperature models.FloatField(help_text摄氏度) humidity models.FloatField(help_text百分比) timestamp models.DateTimeField(auto_now_addTrue) # 外键关联用户可选演示关系建模 owner models.ForeignKey( User, on_deletemodels.CASCADE, # 级联删除用户删其读数全删 nullTrue, # 允许匿名读数 blankTrue, # 表单中可为空 ) class Meta: # 数据库表名显式指定避免 Django 自动生成的 core_sensorreading db_table sensor_reading # 按时间倒序让最新读数排第一 ordering [-timestamp] # Admin 列表页显示的默认字段避免全字段加载拖慢 list_display [temperature, humidity, timestamp, owner]逻辑说明auto_now_addTrue保证timestamp在首次保存时自动填入当前时间且不可修改on_deletemodels.CASCADE是外键必选项Django 2.0 强制要求表示父记录删除时子记录同步删除db_table显式指定表名避免 Django 默认的appname_modelname命名如core_sensorreading让 DBA 查看时一目了然。3.2makemigrations不是魔法三个参数控制迁移文件生成行为python manage.py makemigrations默认行为是扫描所有已注册 app 的models.py对比当前数据库状态或上一个迁移文件生成新迁移。但新手常忽略它的三个关键开关参数作用典型场景--name name指定迁移文件名不含数字前缀makemigrations --name add_location_field避免生成0002_auto_20231015_1423.py这种难读的文件名--empty生成空迁移文件不检测模型变更需要手动写 SQL 或调用RunPython函数时如批量初始化数据--fake-initial告诉 Django “这个初始迁移已存在不要执行只标记为已应用”项目已有生产数据库现在要接入 Django 迁移系统实战命令推荐组合# 生成带语义化名称的迁移比 auto_ 时间戳名好维护 python manage.py makemigrations core --name create_sensor_reading_table # 查看迁移内容不执行确认 SQL 是否符合预期 python manage.py sqlmigrate core 0001 # 执行迁移此时才真正建表 python manage.py migrate参数说明sqlmigrate core 0001输出的是 Django 将执行的原始 SQL如CREATE TABLE sensor_reading这是验证迁移安全性的最后防线。如果看到ALTER TABLE ... ADD COLUMN且表中已有百万行数据就得警惕——这会锁表。此时应改用--empty迁移手写RunSQL分步执行。3.3 迁移避坑常见问题与血泪排查指南现象 1makemigrations报错ValueError: Related model auth.User cannot be resolved原因models.py中引用了django.contrib.auth.models.User但INSTALLED_APPS里没启用django.contrib.auth或顺序错乱。解决检查settings.py的INSTALLED_APPS确保django.contrib.auth在core之前若用自定义用户模型需设置AUTH_USER_MODEL core.CustomUser并确保core已注册。现象 2migrate执行后Admin 页面看不到新模型原因忘了在core/admin.py中注册模型Django 不自动注册。解决创建core/admin.py写入from django.contrib import admin from .models import SensorReading admin.site.register(SensorReading) # 必须这行现象 3migrate卡住日志显示Waiting for database connection...原因SQLite 数据库文件路径不可写如db.sqlite3在/usr/local/下或 PostgreSQL 密码错误。解决用python manage.py dbshell测试连接检查DATABASES配置中NAME路径权限Linux/macOS 用ls -l db.sqlite3Windows 检查属性密码错误时dbshell会直接报OperationalError。现象 4修改模型后makemigrations生成空迁移No changes detected原因Django 迁移系统依赖migrations/目录下的.py文件记录历史。如果手动删了迁移文件但没删数据库记录Django 认为“已应用”。解决运行python manage.py showmigrations查看哪些迁移被标记为[X]已应用、[ ]未应用对误删的迁移用python manage.py migrate core 0001 --fake回退到初始状态再重新makemigrations。4. 视图与 URL用函数视图快速响应请求但path()的kwargs是调试黑匣子的后悔药4.1core/views.py从HttpResponse到render()为什么模板路径必须用app_name/template_name.htmlDjango 视图本质是接收HttpRequest、返回HttpResponse的 Python 函数。新手常写from django.http import HttpResponse def home(request): return HttpResponse(h1Welcome!/h1)这能跑但无法复用 HTML 结构。正确路径是render()—— 它自动加载模板、传入上下文、处理 CSRF。而模板路径规则是Django 按INSTALLED_APPS顺序在每个 app 的templates/子目录下查找。所以core/templates/core/home.html是标准位置。# core/views.py from django.shortcuts import render from django.http import HttpResponse from .models import SensorReading def home(request): 首页显示最近 10 条传感器读数 readings SensorReading.objects.all().order_by(-timestamp)[:10] context { readings: readings, page_title: 实时监控面板, } return render(request, core/home.html, context) # ← 路径core/templates/core/home.html def about(request): 关于页纯静态内容 return render(request, core/about.html)逻辑说明render()第三个参数context是字典键名如readings将成为模板中{{ readings }}可访问的变量request对象自动注入csrf_token无需手动处理core/templates/core/是约定俗成的子目录避免不同 app 的home.html冲突。4.2core/urls.py用path()替代url()kwargs参数是调试路由的隐形开关Django 2.0 废弃url()全面转向path()。path()的语法是path(pattern/, view, namename)但它的第三个参数kwargs常被忽略——它允许你向视图函数注入固定参数绕过 URL 捕获。# core/urls.py from django.urls import path from . import views urlpatterns [ path(, views.home, namehome), path(about/, views.about, nameabout), # ↓ 关键用 kwargs 传参而非捕获 URL path(readings/, views.readings_list, {limit: 20}, namereadings_list), ]对应视图# core/views.py def readings_list(request, limit10): # limit 有默认值兼容无 kwargs 调用 readings SensorReading.objects.all()[:limit] return render(request, core/readings.html, {readings: readings})参数说明{limit: 20}会作为关键字参数传给readings_list覆盖默认值limit10。这比path(readings/int:limit/, ...)更安全——避免用户输入readings/abc/导致 404也比在视图里request.GET.get(limit, 10)更早介入减少条件分支。4.3 主项目urls.pyinclude()的namespace是避免 URL 名冲突的唯一解根 URL 配置mysite/urls.py必须用include()包含 app 的urls.py否则所有路由都挤在一处无法维护。而namespace参数是关键它为 app 内部的name添加前缀防止不同 app 定义同名 URL如core和blog都有home。# mysite/urls.py from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), # ↓ namespacecore则 core/urls.py 中的 namehome 变成 core:home path(, include(core.urls, namespacecore)), ]模板中反向解析 URL 时必须用命名空间!-- core/templates/core/base.html -- a href{% url core:home %}首页/a a href{% url core:about %}关于/a逻辑说明没有namespace{% url home %}会报NoReverseMatch因为 Django 不知道你要哪个home有了namespace它精确匹配core:home即使其他 app 也有home。4.4 URL 路由避坑4 种高频翻车现场与定位技巧现象 1访问/返回 404但/admin/正常原因mysite/urls.py中include(core.urls)的path没加尾部/或core/urls.py的urlpatterns第一个 pattern 是path(, ...)但没匹配空字符串。排查运行python manage.py show_urls需安装django-extensions查看所有注册的 URL 模式确认path(, include(...))的空字符串 pattern 是否存在。现象 2{% url core:home %}在模板中报NoReverseMatch原因core/urls.py中path(, views.home, namehome)的name值与模板中引用的core:home不一致或namespacecore拼写错误如core 多个空格。解决在core/urls.py顶部加print(core urls loaded)启动服务时看是否打印——确认文件被加载用python manage.py show_urls | grep core检查注册的 name 是否为core:home。现象 3path(readings/int:pk/, ...)中pk值为负数视图报DoesNotExist原因int:pk只校验类型不校验范围。负数pk会被传递给get_object_or_404但数据库无此记录。解决在视图中加校验def reading_detail(request, pk): if pk 0: raise Http404(Invalid ID) reading get_object_or_404(SensorReading, pkpk) return render(request, core/detail.html, {reading: reading})现象 4include()后 URL 重复出现双斜杠//原因mysite/urls.py的path和core/urls.py的path都写了尾部/如path(core/, include(core.urls))path(/detail/, ...)。解决统一约定——mysite/urls.py的include不加/path(core, include(...))core/urls.py的 pattern 加/path(detail/, ...)。Django 官方推荐后者。5. 模板与静态文件用{% extends %}构建可继承布局但STATICFILES_DIRS必须显式声明5.1core/templates/core/base.html用{% block %}定义可替换区域{{ block.super }}是继承的黄金法则Django 模板继承的核心是base.html定义骨架子模板用{% extends %}继承并重写{% block %}。新手常犯错在子模板中写title{% block title %}My Site{% endblock %}/title却忘了在base.html中定义{% block title %}导致标题不显示。!-- core/templates/core/base.html -- !DOCTYPE html html head meta charsetutf-8 title{% block title %}Django 简单项目{% endblock %}/title !-- ↓ 关键用 {{ block.super }} 保留父模板的 CSS再追加自己的 -- link relstylesheet href{% static core/css/base.css %} {% block extra_css %}{% endblock %} /head body header h1Django 监控系统/h1 nav a href{% url core:home %}首页/a a href{% url core:about %}关于/a /nav /header main !-- ↓ content block 是子模板唯一必须重写的区域 -- {% block content %}{% endblock %} /main footer pcopy; {% now Y %} All rights reserved./p /footer !-- ↓ JS 也支持 super避免重复加载 jQuery -- {% block extra_js %}{% endblock %} /body /html子模板只需!-- core/templates/core/home.html -- {% extends core/base.html %} {% block title %}实时监控 - {{ block.super }}{% endblock %} {% block content %} h2{{ page_title }}/h2 ul {% for r in readings %} li{{ r.temperature }}°C, {{ r.humidity }}%, {{ r.timestamp|date:Y-m-d H:i }}/li {% endfor %} /ul {% endblock %}逻辑说明{{ block.super }}在titleblock 中插入父模板的Django 简单项目形成实时监控 - Django 简单项目extra_css和extra_jsblock 允许子模板按需添加资源且不破坏父模板结构。5.2STATICFILES_DIRS为什么python manage.py collectstatic总说找不到core/css/base.cssDjango 的静态文件CSS/JS/图片默认从每个 app 的static/子目录收集。但collectstatic命令只扫描STATICFILES_DIRS列表中的路径。新手常以为core/static/core/css/base.css会自动被发现结果collectstatic输出0 static files copied。正确配置settings.py# settings.py import os from pathlib import Path # BASE_DIR 是 manage.py 所在目录 BASE_DIR Path(__file__).resolve().parent.parent.parent # ↓ 显式声明告诉 Django 去 core/static/ 下找文件 STATICFILES_DIRS [ BASE_DIR / core / static, ] # collectstatic 输出目录生产环境用 STATIC_ROOT BASE_DIR / staticfiles # URL 前缀开发时用 /static/生产时可改为 CDN 地址 STATIC_URL /static/目录结构必须严格mysite/ ├── core/ │ ├── static/ │ │ └── core/ # ← 必须有 app 名子目录 │ │ └── css/ │ │ └── base.css │ └── templates/ │ └── core/ │ └── base.html参数说明STATICFILES_DIRS是列表可添加多个路径如BASE_DIR / assetsSTATIC_ROOT是collectstatic的输出目录开发时不用管STATIC_URL是浏览器请求静态文件的 URL 前缀必须以/结尾。5.3 模板避坑5 个让页面白屏的隐形杀手现象 1页面显示{% block content %}文本而非渲染内容原因子模板忘了写{% extends core/base.html %}或路径写错如base.html缺少core/。排查在base.html开头加h1BASE LOADED/h1刷新页面看是否显示——确认模板是否被加载。现象 2CSS 不生效浏览器开发者工具显示 404原因STATIC_URL配置错误如/static缺少结尾/或static/目录不在STATICFILES_DIRS中。解决访问http://127.0.0.1:8000/static/core/css/base.css看是否返回 CSS 内容若 404检查STATICFILES_DIRS路径是否指向core/static。现象 3{{ reading.temperature }}显示空但数据库有值原因views.py中context字典键名与模板变量名不一致如context {temp: r.temperature}但模板写{{ reading.temperature }}。解决在视图中加print(context)确认键名或用{{ reading|pprint }}在模板中打印整个对象。现象 4{% url core:home %}在base.html中报错但在home.html中正常原因base.html被其他 app 的模板继承而那个 app 没注册core的 namespace。解决确保所有继承base.html的模板都来自coreapp或在base.html中用{% url core:home %}时core必须在INSTALLED_APPS中。现象 5collectstatic后生产环境 CSS 仍 404原因Web 服务器如 Nginx没配置静态文件服务或STATIC_ROOT路径权限不足。解决collectstatic后检查STATIC_ROOT目录下是否有core/css/base.cssNginx 配置中location /static/必须指向STATIC_ROOT的绝对路径。6. 本地开发调试用runserver的隐藏参数榨干调试效率--verbosity是定位慢查询的探针6.1runserver的四个必用参数从--noreload到--ipv6每一条都解决一个具体痛点python manage.py runserver默认行为是开启自动重载--reload和 IPv4 监听。但在真实开发中这些默认值常导致问题--noreloadVS Code 或 PyCharm 断点在重载后失效因为进程重启导致调试器断连。关掉它用CtrlC手动重启断点稳定命中。--ipv6某些网络环境如公司内网IPv6 可用但runserver默认只绑127.0.0.1导致同事无法访问你的调试地址。--ipv6会监听::1IPv6 localhost同时兼容 IPv4。--verbosity 2详细日志模式显示每个请求的视图函数、SQL 查询、模板渲染耗时。这是定位性能瓶颈的第一手资料。--port 8001避免端口冲突如 Docker 容器占了 8000。完整命令python manage.py runserver --noreload --ipv6 --verbosity 2 --port 8001日志示例关键信息高亮[21/Oct/2023 14:23:45] GET / HTTP/1.1 200 1245 # ↑ 请求路径、状态码、响应体大小 INFO:django.server:GET / HTTP/1.1 200 1245 INFO:django.db.backends:(0.012) SELECT core_sensorreading.id, core_sensorreading.temperature, ... FROM sensor_reading ORDER BY core_sensorreading.timestamp DESC LIMIT 10; args() # ↑ SQL 查询语句和耗时0.012秒一眼看出慢查询 INFO:django.template:Rendering template core/home.html with context {...}逻辑说明--verbosity 2输出的django.db.backends日志是 Django ORM 执行的原始 SQLdjango.template日志显示模板渲染耗时。这两者结合能快速判断是数据库慢还是模板逻辑复杂。6.2 用django-debug-toolbar定位 SQL N1 查询三步接入零代码侵入--verbosity 2日志只能看单次请求而django-debug-toolbarDjDT提供可视化面板直观展示查询次数、重复查询、缓存命中率。它对“简单项目”极其友好——无需改业务代码只需配置。步骤安装pip install django-debug-toolbar配置settings.pyINSTALLED_APPS [debug_toolbar] MIDDLEWARE [debug_toolbar.middleware.DebugToolbarMiddleware] INTERNAL_IPS [127.0.0.1, ::1] # 允许显示 toolbar 的 IP在mysite/urls.py中添加 toolbar URL仅开发环境from django.conf import settings if settings.DEBUG: import debug_toolbar urlpatterns [path(__debug__/, include(debug_toolbar.urls))] urlpatterns效果页面右下角出现绿色小图标点击展开面板SQL标签页列出所有查询Duplicates列显示重复 SQL 次数。例如如果你在循环中写for r in readings: print(r.owner.username)DjDT 会显示 10 次SELECT * FROM auth_user WHERE id ?这就是典型的 N1 查询。解决方案在视图中用select_related(owner)预加载外键readings SensorReading.objects.select_related(owner).all()[:10]6.3 生产环境等效调试用django-silk替代 DjDT轻量级 API 性能分析django-debug-toolbar仅限开发生产环境需更轻量的方案。django-silk是专为生产设计的性能分析工具它记录请求、SQL、视图耗时并提供 Web UI且资源占用极低。安装与配置pip install django-silk# settings.py INSTALLED_APPS [silk] MIDDLEWARE [silk.middleware.SilkyMiddleware] # 生产环境限制只记录 1% 的请求 SILKY_INTERCEPT_PERCENT 1 # 或按用户过滤如只记录管理员 SILKY_AUTHENTICATION True SILKY_AUTHORISATION True# mysite/urls.py from django.conf import settings if settings.DEBUG or silk in settings.INSTALLED_APPS: urlpatterns [path(silk/, include(silk.urls, namespacesilk))]访问http://yoursite.com/silk/即可查看所有请求的耗时分布、SQL 执行详情、内存占用。它不依赖调试模式且可配置采样率适合长期运行。6.4 我的调试铁律三分钟定位法这是我带新人时强制执行的调试流程已验证 95% 的问题能在 3 分钟内定位第一分钟看终端日志启动runserver --verbosity 2复现问题观察最后一行错误如KeyError: readings确认是模板、视图还是模型层。第二分钟开 DjDT 或 Silk如果是性能问题打开 DjDT 的SQL标签页看查询次数是否异常 20 次如果是逻辑错误在Request标签页检查POST数据或GET参数是否符合预期。第三分钟加一行print()或logging.debug()在疑似出错的视图函数开头加print(fContext: {context})运行后看终端输出。比 IDE 断点更快——尤其当断点因重载失效时。这方法土但有效。Django 的错误日志足够详细你不需要猜只需要学会读。每次runserver启动时那串[21/Oct/2023 14:23:45]时间戳就是你和问题本文还有配套的精品资源点击获取
