这次我们直接聊 Django。它最大的特点不是“新”而是“全”ORM、Admin 后台、用户认证、表单处理、模板引擎、路由系统全部内置新手不用在技术选型上反复纠结装完 Django 就能开始写业务代码。很多新手第一次从 Java 生态听说过“若依”这类后台管理框架到了 Python 生态对应物其实就是 Django Admin。学习 Django 最怕的是抓不住主线卡在“该先学模型还是先学视图”“要不要一上来就学 Django REST Framework”“模板语法要不要背”这些问题上。其实只要沿着“建项目 - 建应用 - 建模型 - 迁移数据库 - 写视图 - 配路由 - 渲染模板 - 注册后台”这条链路完整跑通一个最小案例Django 的整体运行逻辑就清楚了。本文不铺开讲理论只做一件事带你把这条开发主线完整跑一遍顺便把环境准备、Admin 后台、ORM 查询、URL 路由、模板渲染、DRF 接口以及常见坑位梳理清楚。先看核心规格再动手。1. Django 框架核心能力速览能力项说明框架类型基于 Python 的全栈 Web 框架采用 MTVModel-Template-View架构当前主流版本Django 4.2 LTS / 5.xPython 版本要求Django 4.2 建议 Python 3.8Django 5.x 要求 Python 3.10数据库支持内置 SQLite支持 MySQL、PostgreSQL、Oracle内置功能ORM、Admin 后台、认证系统、表单处理、模板引擎、中间件、静态文件管理API 扩展配合 Django REST FrameworkDRF开发 RESTful API开发启动方式命令启动python manage.py runserver生产部署方式Gunicorn/uWSGI Nginx或 Docker 容器化典型应用场景内容管理网站、企业内部系统、电商后台、API 服务、数据展示系统新手友好度高官方文档完善、社区案例多、内置功能降低选型成本需要注意一点Django 不是性能最快的 Python Web 框架但它是“功能最完整”的。它的灵感最初来自新闻网站的内容发布需求所以内容管理、后台管理、用户体系这类场景是它的强项。如果你只需要一个小型 JSON APIFlask 或 FastAPI 会更轻但如果你要的是带后台、带用户体系、带数据库管理的完整系统Django 开箱即用的优势非常明显。2. 适用场景与使用边界2.1 适合什么场景内容型网站博客、新闻、文档站、企业内部 CMSDjango 内置的 Admin 可以让编辑人员直接维护数据。管理后台企业内部数据录入、订单管理、用户管理。Django Admin 基于模型自动生成增删改查界面开发速度很快。电商系统商品、订单、用户、购物车这类业务模型非常适合用 Django ORM 建模。API 服务配合 Django REST Framework 做移动端或前端项目的后端接口。数据展示系统配合 pandas 和图表库把数据分析结果做成 Web 报表。2.2 不适合什么场景高实时性场景多人实时协同、游戏服务端等Django 默认是请求响应模式需要额外引入 Channels 或换更合适的方案。极微型脚本服务只有一个接口的小工具用 FastAPI 或 Flask 更轻量。性能竞赛型场景高并发接口需要配合缓存、消息队列、数据库读写分离等架构设计Django 本身不是问题但新手直接裸写的风险很高。2.3 使用边界与合规提醒Django 常用来处理用户数据和业务数据开发阶段要遵守几个底线测试数据不要使用真实用户隐私生产环境数据库必须做备份涉及第三方图片、文本、接口素材要有版权或授权做登录注册功能时要参考个人信息保护和数据安全相关规范。这不是形式要求是项目上线前必须过的安全检查。3. 环境准备与前置条件Django 的安装门槛很低核心是 Python 环境。部署前先检查以下几点。3.1 环境检查清单PythonDjango 5.x 需要 Python 3.10 以上建议安装 Python 3.11 或 3.12兼容性更好。虚拟环境使用 venv 或 conda避免不同项目的依赖互相冲突。数据库开发阶段默认使用 SQLite零配置直接跑不需要额外安装数据库服务。编辑器VS Code 即可建议安装 Python 和 Django 扩展插件。Git配合版本管理强烈建议。网络需要执行 pip install 下载依赖可以使用国内镜像源加速。3.2 检查命令python --version pip --version如果 Python 版本低于 3.10建议先升级 Python。直接使用旧版本 Python 安装 Django 5.x很容易遇到安装失败或运行报错。3.3 全局依赖隔离不推荐全局安装 Django。一个常见场景是电脑上同时有多个 Django 项目分别依赖不同版本全局装会让版本互相覆盖。所以每一步新建项目时先创建虚拟环境这是最稳妥的做法。4. 安装部署与启动方式下面从零开始一路把 Django 项目跑起来。Windows、macOS、Linux 的命令差异很小主要是虚拟环境激活方式不同。4.1 创建虚拟环境mkdir django_demo cd django_demo python -m venv venv激活虚拟环境Windows PowerShellvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活后命令行前面会出现(venv)前缀说明已经进入虚拟环境。4.2 安装 Djangopip install django如果下载速度慢可以换用清华镜像源pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后验证版本python -m django --version如果输出版本号说明安装成功。4.3 创建 Django 项目django-admin startproject myproject进入项目目录查看结构myproject/ manage.py myproject/ __init__.py settings.py urls.py wsgi.py asgi.pymanage.py项目管理入口所有 Django 命令都通过它执行。myproject/settings.py全局配置包括数据库、应用注册、时区语言、静态文件等。myproject/urls.py根路由配置文件。myproject/wsgi.py和asgi.py生产部署时用的 WSGI/ASGI 入口。4.4 启动开发服务器cd myproject python manage.py runserver默认监听127.0.0.1:8000浏览器访问http://127.0.0.1:8000/如果看到 Django 默认欢迎页说明服务已经正常启动。端口被占用时可以手动指定端口python manage.py runserver 8080如果是在云服务器或 NAS 上测试需要绑定 IP 并放行端口python manage.py runserver 0.0.0.0:8000这里要强调runserver是 Django 的开发服务器只适合本地调试和功能验证不要直接暴露到公网环境作为生产服务。生产部署应该用 Gunicorn Nginx 或 Docker 方案这部分在第 7 节展开。5. 功能测试与效果验证项目启动成功只是第一步接下来验证 Django 真正的核心能力模型、迁移和 Admin 后台。5.1 创建应用Django 中“项目”和“应用”是分开的概念。一个项目可以包含多个应用比如用户应用、文章应用、订单应用。这里创建一个博客应用python manage.py startapp blog创建后生成如下结构blog/ migrations/ __init__.py __init__.py admin.py apps.py models.py tests.py views.py5.2 注册应用打开myproject/settings.py在INSTALLED_APPS列表中加入blogINSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, ]这一步新手经常跳过。创建应用后不注册Django 不会加载这个应用的模型和迁移文件后面很容易出现模板找不到、迁移不生效之类的问题。5.3 定义模型打开blog/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.title三个字段分别对应标题、正文、创建时间。auto_now_addTrue表示创建时自动写入当前时间。5.4 生成并执行迁移Django 的 ORM 不会直接改数据库而是先通过迁移文件记录模型变化再把变化同步到数据库。python manage.py makemigrations python manage.py migratemakemigrations根据模型生成迁移文件。migrate把迁移文件执行到数据库中。修改模型字段后必须重新执行这两条命令数据库才会更新。这是新手最容易忽略的环节。5.5 注册 Admin 后台打开blog/admin.py注册 Article 模型from django.contrib import admin from .models import Article admin.site.register(Article)5.6 创建超级管理员python manage.py createsuperuser按提示输入用户名、邮箱、密码。这里要注意密码输入时不会显示属于正常现象。启动服务后访问http://127.0.0.1:8000/admin/用刚创建的超级用户登录。登录后可以看到 Article 表的增删改查界面点击添加文章填入标题和内容保存。这一步的目的是验证 Django 的 Admin 后台是否能自动生成管理界面。5.7 验证预期结果访问/admin/可以正常登录并看到 Article 模型。在 Admin 后台添加一条文章记录保存成功。数据库中新增了一条数据这里不需要手动写 SQL。这一步通过说明模型、迁移、Admin 后台三条链路已经通了。6. 接口 API 与批量任务Django 自带的前端渲染能力适合做后台和内容网站。如果项目需要接口服务比如给 Vue、小程序或移动端提供数据官方推荐的方案是 Django REST FrameworkDRF。6.1 安装并配置 DRFpip install djangorestframework在settings.py的INSTALLED_APPS中加入INSTALLED_APPS [ ... rest_framework, blog, ]6.2 创建序列化器新建blog/serializers.pyfrom rest_framework import serializers from .models import Article class ArticleSerializer(serializers.ModelSerializer): class Meta: model Article fields [id, title, content, created_at]序列化器负责把模型对象转换成 JSON 数据DRF 的 ModelSerializer 是自动完成字段映射的简单直接。6.3 编写 ModelViewSet打开blog/views.py加入from rest_framework import viewsets from .models import Article from .serializers import ArticleSerializer class ArticleViewSet(viewsets.ModelViewSet): queryset Article.objects.all() serializer_class ArticleSerializerModelViewSet会自动提供 list、create、retrieve、update、delete 五个标准接口。6.4 配置路由新建blog/urls.pyfrom django.urls import path, include from rest_framework.routers import DefaultRouter from . import views router DefaultRouter() router.register(rarticles, views.ArticleViewSet) urlpatterns [ path(api/, include(router.urls)), ]在项目根路由myproject/urls.py中引入from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]6.5 接口调用测试重启服务后使用 curl 测试curl http://127.0.0.1:8000/api/articles/正常会返回 JSON 格式的文章列表[ { id: 1, title: 第一篇文章, content: Django 接口测试, created_at: 2025-01-01T10:00:00Z } ]Python 端调用示例import requests response requests.get(http://127.0.0.1:8000/api/articles/) print(response.status_code) print(response.json())新增一条数据的 POST 请求curl -X POST http://127.0.0.1:8000/api/articles/ \ -H Content-Type: application/json \ -d {title:第二篇,content:通过接口添加}6.6 批量任务思路Django 做批量任务时千万不要把耗时逻辑直接写在请求视图里否则接口会被一个任务拖住超时。推荐方案Django 自定义管理命令适合定时批量脚本。Celery Redis适合真正的异步任务队列。简单场景可以直接写脚本调用 ORM。自定义管理命令目录结构blog/ management/ __init__.py commands/ __init__.py import_data.py在import_data.py中定义 Command 类然后通过python manage.py import_data执行。这样可以复用 Django 的项目配置和 ORM同时不阻塞 Web 请求。7. 资源占用、性能观察与生产部署要点7.1 开发环境的资源占用Django 的开发服务器runserver是单进程多线程模式资源占用主要由 Python 解释器和当前请求决定。在只有少量并发访问的本地开发场景下CPU 和内存占用都不高一台普通的办公电脑就能跑。SQLite 作为开发数据库时没有独立的数据库进程数据文件直接落盘内存占用低适合快速验证。但如果写入量变大SQLite 会出现锁库问题生产环境建议更换 PostgreSQL 或 MySQL。观察占用时Windows 可以使用任务管理器Linux 使用top或htop重点看 python 进程的 CPU 和内存指标。7.2 影响性能的关键因素runserver不适合高并发生产环境要换 Gunicorn 或 uWSGI。模板渲染比 API 返回 JSON 更消耗 CPU静态资源不应由 Django 直接处理。数据库查询要加索引尽量用select_related和prefetch_related优化关联查询。频繁重复查询的接口要加缓存Django cache framework 支持 Redis 和内存缓存。7.3 生产部署基础示例安装 Gunicornpip install gunicorn启动命令gunicorn myproject.wsgi:application -w 4 -b 0.0.0.0:8000:8000前的地址需要根据实际服务器配置调整。前端再加一层 Nginx 做反向代理和静态文件服务静态文件通过collectstatic收集到一个目录python manage.py collectstatic这里不展开完整的服务器配置只需要知道 Django 生产部署的标准链路是“Nginx Gunicorn PostgreSQL”这样可以避免因为中间环节缺失导致的性能问题。8. 常见问题与排查方法问题现象可能原因排查方式解决方案pip install django 失败Python 版本过低或网络问题执行 python --version 检查版本升级 Python使用-i https://pypi.tuna.tsinghua.edu.cn/simple镜像源manage.py 命令不存在未激活虚拟环境检查命令行是否有 (venv) 前缀激活虚拟环境启动项目后打开 404URL 路由未配置检查 myproject/urls.py 和 blog/urls.py添加 path 和 include 配置新应用页面找不到模板应用未注册到 INSTALLED_APPS检查 settings.py注册应用模型改了但数据库没有变化未执行 makemigrations 和 migrate查看 blog/migrations 目录重新执行迁移命令Admin 后台显示英文LANGUAGE_CODE 未设置检查 settings.py设为zh-hansAdmin 登录时报 CSRF 错误页面缓存或请求头异常检查浏览器缓存清缓存后重试正常表单需要 csrf_token表单提交 CSRF 校验失败模板缺少{% csrf_token %}检查 HTML 表单在 form 中添加{% csrf_token %}接口返回 403认证和权限配置限制查看 DRF 权限设置根据需求调整 DEFAULT_PERMISSION_CLASSES端口 8000 被占用其他服务占用了端口Windows 用 netstatLinux 用 lsof换端口启动如python manage.py runserver 8080修改 model 后 migrate 报冲突迁移文件历史不一致查看 migrations 文件不要手动删除迁移文件保留迁移记录并按顺序迁移静态文件不显示STATIC_URL 或目录配置错误检查 settings.py合理配置 STATICFILES_DIRS 或执行 collectstatic生产环境页面无样式DEBUGFalse 后 Django 不再处理静态文件检查静态文件收集配置 Nginx 或使用白名单方式服务静态文件9. 最佳实践与使用建议9.1 先跑通最小案例再学进阶第一次学习 Django不要上来就研究 Channels、Celery、Docker 编排。先把“创建项目 - 创建应用 - 定义模型 - 迁移 - Admin 后台 - 写视图 - 配路由 - 渲染模板”这条链路跑通。这个最小闭环能覆盖 Django 80% 的核心概念之后学什么都有上下文。9.2 正确管理依赖项目依赖使用requirements.txt固定版本pip freeze requirements.txt其他人或新服务器部署时pip install -r requirements.txt不固定版本的话过几个月安装 Django 新版本很容易遇到接口变化导致代码报错。9.3 利用 Django 官方文档Django 官方文档质量很高而且有中文翻译。遇到问题先查文档比反复搜索零散博客更高效。官方教程的 Polls 应用示例非常适合新手作为第二练手项目。9.4 实用建议每个项目使用独立虚拟环境不要全局装依赖。数据库迁移文件提交到 Git方便团队同步。设置文件区分开发和生产敏感信息用环境变量管理。后台 Demo 和接口测试使用独立环境不要直接连生产数据库。定时备份数据库使用自动化脚本或 Django 管理命令触发。接口服务部署到服务器后限制访问范围不要用 runserver 直接暴露公网。涉及用户隐私数据、版权素材、人脸或个人信息的应用必须确认合法授权和使用边界。9.5 最容易踩的坑忘记迁移数据库模型一直不生效。创建应用后没有注册到 INSTALLED_APPS。修改 settings.py 后忘记重启服务。生产环境 DEBUGTrue导致安全风险。模型字段删除时没有确认关联数据导致数据丢失。总结与下一步Django 的学习主线其实很简单项目、应用、模型、迁移、Admin、视图、路由、模板。把这套链路跑通一次后面学 DRF 接口、用户认证、Docker 部署都有章可循。第一次接触 Django最先应该验证的是 Admin 后台和 ORM 迁移两个环节因为这两块是 Django 区别于轻量框架的核心优势也是新手最容易卡住的地方。最容易踩的坑来自两个习惯问题忘了迁移、忘了注册应用遇到类似报错时优先检查这两项。后续扩展方向我建议按这个顺序来第一学 Django 表单和用户认证做一个带注册登录的完整站点第二学 Django REST Framework把接口能力补上第三学 Docker 和 Gunicorn 部署把项目发布到服务器第四再考虑 Celery 异步任务、缓存优化和前后端分离架构。抓住主线比盲目堆概念更有效。