1. 环境准备Python、PyCharm 与 Django 的三方关系如果你刚接触 Python Web 开发PyCharm 和 Django 几乎是绕不开的组合。PyCharm 是目前最主流的 Python IDE而 Django 是 Python 生态里最成熟的全栈 Web 框架。把这两个放在一起最大的好处不是替你省下几条命令而是让代码补全、语法提示、调试器、数据库工具全部集中在同一个界面里。项目跑到哪一步、哪个变量是什么值、异常抛出在哪一行你都能看得明明白白。这篇内容我按平时自己搭项目的习惯来写从装环境讲到跑通第一个页面再聊一聊模型、后台、模板和常见的排查方法。没有 Django 项目经验的新手可以用来照着做跟教程做了一半卡住的人也可以拿来做对照。1.1 选择 Python 版本和 PyCharm 版本开始之前先把底层的软件版本定下来。Django 对 Python 版本有明确要求目前主流的 Django 4.2 LTS 和 Django 5.x 都要求 Python 3.8 以上我建议直接装 Python 3.10 或 3.11兼容性比较稳。Python 3.12 和 3.13 也能跑但有些第三方库可能还没跟上新手没必要一上来就追最新。装 Python 的时候记得勾选“Add Python to PATH”这步很多人会漏掉漏掉之后在终端里敲python会直接提示命令不存在后面每一步都会变麻烦。PyCharm 分社区版和专业版。社区版免费支持 Python 开发和调试足够用来学习 Django专业版是收费的额外提供 Django 项目的可视化创建方式、数据库工具和前端框架支持。我个人的看法是新手先用社区版完全没问题等真的需要专业版的功能了再说。PyCharm 都可以在官网下载安装过程没什么难点安装时注意选择关联.py文件、添加“Open Folder as Project”这类选项能省不少事。还有个容易被忽略的点PyCharm 里的“New Project”界面会让你选择解释器这里一定要选对 Python 环境否则后面会出现“No module named django”之类的报错。解释器不是说你系统里装了 Python 就行PyCharm 需要明确知道该用哪一份 Python 来运行项目。通常我们会在创建项目时顺便建立一个独立的虚拟环境把 Django 装进这个虚拟环境里而不是直接装到系统 Python 里。1.2 创建虚拟环境为什么不用全局环境很多新手一上来就会问我直接pip install django装到全局不行吗能用但不推荐。你电脑上可能有多个 Python 项目每个项目依赖的 Django 版本、第三方库版本不一定相同。今天项目 A 需要 Django 4.2明天项目 B 需要 Django 5.0如果都装在全局版本冲突很快就会爆发。虚拟环境就像给每个项目开一间独立的小房间房间里的 Python 版本、pip 包列表互不干扰。创建虚拟环境的方式有两种一是用 Python 自带的venv二是用 Anaconda 的conda。绝大多数情况下venv就够了。在 PyCharm 里新建项目时它会默认帮你创建好venv你只需要在解释器设置里确认一下路径和 Python 版本。如果项目是别人给的打开之后发现没有虚拟环境可以通过 PyCharm 右下角的解释器设置手动添加选择“Virtualenv Environment”再点“New”指定 Python 路径即可。虚拟环境有一个很直观的判断方法在 PyCharm 自带终端中命令提示符前面会出现(venv)字样。看到它就说明当前命令行使用的是项目专用的虚拟环境。如果你发现敲pip install安装的包在项目里找不到多半就是终端没有激活虚拟环境。PyCharm 的终端通常会自动激活但如果你自己另开了一个终端窗口就需要手动执行激活命令Windows 下是venv\Scripts\activatemacOS 和 Linux 下是source venv/bin/activate。1.3 安装 Django从 pip 到验证版本进入虚拟环境之后安装 Django 就很直接了。在 PyCharm 终端里执行pip install django这个命令会安装当前 PyCharm 使用的 Python 环境里最新且兼容的 Django 版本。如果想指定版本可以写成pip install django4.2.7在需要和其他项目保持一致的场景下更稳妥。安装时如果下载速度比较慢可以考虑配置 pip 镜像源这里就不展开讲具体地址了搜索一下“pip 国内镜像”就能找到很多。安装完成后用python -m django --version验证。用python -m django而不是直接敲django是为了确保使用的是当前虚拟环境里的 Django而不是系统里其他可能存在的版本。如果输出类似5.0.6的版本号说明安装成功如果提示 No module named django就先检查 pip 安装到了哪个环境再看 PyCharm 的解释器是不是指向了同一个环境。这两者的对应关系是新手最容易踩的第一个坑。2. 把 Django 项目放进 PyCharm两种创建方式环境准备好了接下来就是创建项目本体。这里有两种主流做法第一种是用 PyCharm 专业版的可视化模板第二种是先用命令行创建再用 PyCharm 打开。社区版用户大概率只能用第二种但第二种其实更接近团队协作时的真实操作习惯所以我建议不管是什么版本都认真看一下。2.1 方式一PyCharm 专业版内置模板创建如果你用 PyCharm 专业版创建流程会非常省事。打开 PyCharm点击 New Project左侧选择 Django然后设置项目名称、项目目录和解释器。专业版会自动生成一个带基础结构和管理后台的 Django 项目同时为你配置好运行模板创建完成之后可以直接点绿色三角运行。这个模板还有个好处它会自动在settings.py里把项目关键配置都处理好比如INSTALLED_APPS、TEMPLATES、默认数据库等对于刚接触框架的人来说能少写很多初始化代码。不过我不建议依赖这个可视化工具到“完全不了解底层命令”的程度。因为它把很多步骤都隐藏了你点一下按钮它就在背后执行了django-admin startproject和startapp。一旦哪天需要脱离 PyCharm、在服务器上部署项目或者接手一个用命令行创建的项目你会发现自己好像什么都不会。更好的做法是用可视化模板创建完项目后再手动在终端里跑一下python manage.py runserver看看它到底做了什么这样才能真正理解框架的工作方式。2.2 方式二命令行创建 打开项目社区版通用这种方式对我来说是最可控的。先打开 PyCharm选择“Open”打开一个空目录或者直接在系统终端里进入你想放项目的目录然后执行django-admin startproject mysite .注意命令最后的点号。它表示在当前目录下生成manage.py和mysite配置包而不是额外多套一层同名目录。很多教程会省略这个点写成django-admin startproject mysite结果你会发现多了一层mysite/mysite后续运行时经常出现路径错乱。用点号创建的好处是项目根目录直接就是 PyCharm 的项目根目录manage.py 就在眼前各种运行配置也更好设置。创建完成之后目录结构大致是这样的mysite/ ├── manage.py └── mysite/ ├── __init__.py ├── settings.py ├── urls.py └── wsgi.pymanage.py是项目管理和运行的入口所有常用命令都要通过它来执行。内层mysite是项目的配置包settings.py保存配置urls.py保存根路由。PyCharm 打开这个目录后可能会提示你选择解释器把刚才建好的虚拟环境选上就行。选好之后在终端执行python manage.py runserver如果看到 “Starting development server” 和http://127.0.0.1:8000/说明项目已经启动成功。2.3 用 PyCharm 打开项目后还要检查什么用命令行创建完再用 PyCharm 打开通常还需要检查两件事。第一PyCharm 是否正确识别了项目根目录。打开项目后左侧 Project 窗口应该能看到manage.py文件。如果它被折叠在很深的目录里说明你打开的层级不对需要重新打开正确目录。第二解释器是否正确。打开设置Settings/Preferences找到 Project: mysite - Python Interpreter确认指向的是刚才的虚拟环境。完成后建议先手动 Run 一次项目确保环境没有问题再配置 PyCharm 的启动按钮。这一步还有个小技巧settings.py里有一个ALLOWED_HOSTS默认是空列表。如果你只用http://127.0.0.1:8000/访问不需要动它。但如果你想用局域网 IP 访问开发服务器或者以后计划调试移动端页面可以把本机 IP 或域名加进去否则会提示Invalid HTTP_HOST。新手阶段不动它就行等真遇到这个报错再回来改也不迟。3. 创建第一个 App 并让它跑起来Django 项目里有一个核心概念项目project和应用app。可以这样理解项目是一个装应用的大盒子应用是这个盒子里负责具体业务的功能模块。刚创建的mysite项目本身没有一个真正的业务页面接下来我们来创建第一个 app实现一个最简单的投票功能雏形从路由走到页面。3.1 项目与 App什么是 App为什么需要它很多新手刚接触 Django 时会混淆“项目”和“应用”。startproject创建的是项目配置startapp创建的是业务应用。一个项目可以包含多个应用比如一个电商项目可以有用户应用、商品应用、订单应用。把小功能按应用拆分代码更容易维护以后某个应用要复用到另一个项目时也可以直接拷贝相关目录。Django 的哲学是“可复用”它希望你把功能模块做成独立的应用而不是把所有逻辑堆在一个文件里。创建 app 的命令很简单python manage.py startapp home这里我起了个名字叫home你可以按自己的业务场景起。创建之后项目根目录会多一个home文件夹里面有views.py、models.py、admin.py、migrations/等重要文件。views.py用来写业务视图函数models.py用来定义数据表模型admin.py用来注册后台管理migrations/用来记录数据库迁移过程。这些文件一开始都是空的或近乎空的马上我们就要往里填内容。3.2 注册 App为什么会报“Unknown command”创建完 app 之后很多新手会直接写代码然后发现运行完全正常但要使用 Django 的某些功能时却报错。原因在于任何自定义 app 都要先注册到项目的settings.py的INSTALLED_APPS列表里Django 才会把它当作项目的一部分来管理。打开mysite/settings.py你大概会看到这样一段INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, home, ]注意我在末尾加了home。有些教程会写成home.apps.HomeConfig这是 Django 3.2 之后推荐的方式作用一样但直接写home在绝大多数项目里已经够用。注册完 app 后Django 才能找到你写的模型、迁移、后台、模板等文件。如果不注册后面执行makemigrations时会提示没有检测到模型变化因为 Django 压根没去读这个 app。3.3 写第一个视图从 URL 到页面现在开始写第一个页面。打开home/views.py改成下面这样from django.shortcuts import render from django.http import HttpResponse def index(request): return HttpResponse(Hello, Django from PyCharm!)这个视图函数接收一个request参数返回一段简单的字符串。它不是最终形态但足够让你理解“视图返回响应”这条链路。下一步是把视图和 URL 绑定。Django 处理请求的流程是浏览器发来请求Django 根据urls.py里的规则找到对应的视图函数执行视图并返回响应。因此我们需要先在home应用里创建一个urls.py文件from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]然后在根配置mysite/urls.py里把home的 URL 配置包含进来from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(home.urls)), ]这里的关键是include。它的意思是当请求匹配到空路径时交给home.urls去继续匹配。如果你希望首页路径是/home/可以把第二个path改成path(home/, include(home.urls))。改完保存重新运行python manage.py runserver浏览器打开http://127.0.0.1:8000/就能看到刚刚写的那段字符串了。这就是一个最简单的、从浏览器到服务器再到视图函数的完整请求链路。3.4 配置 PyCharm 的一键启动按钮每次都用终端敲runserver当然可以但 PyCharm 的启动按钮能让效率更高。点击右上角的下拉菜单选择“Edit Configurations”然后添加一个 Django Server 配置。如果你用的是专业版新建项目时它可能已经帮你配置好了社区版就需要手动填一下。主要填写两个地方Name 可以写runserverHost 填127.0.0.1或省略Port 填8000。然后确认 Python Interpreter 指向虚拟环境Working directory 指向项目根目录也就是有manage.py的那一层。配置好之后每次点击绿色三角就能启动开发服务器点击旁边的虫子图标就能进入调试模式。调试模式下所有请求都会经过断点暂停你能看到每个变量的当前值比在代码里乱写print要舒服得多。我建议从一开始就养成用 Run Configuration 的习惯后面项目变大、启动参数变复杂时会很有帮助。4. 模型、数据库迁移与 Admin 后台页面能访问之后下一步是让它和数据产生关系。Django 最方便的一点是它自带一套 ORM可以直接用 Python 类来描述数据库表再通过迁移命令同步到数据库。默认情况下Django 使用 SQLite 数据库它只是一个本地文件不需要额外安装数据库服务非常适合学习和前期开发。4.1 在 App 里定义模型我们还是用投票功能的例子。打开home/models.py定义一个简单的问题模型from django.db import models class Question(models.Model): question_text models.CharField(max_length200) pub_date models.DateTimeField(发布日期)这里每一个类属性都对应数据库表中的一个字段。CharField对应字符串字段max_length一定要设置DateTimeField对应日期时间字段。Django 会自动为表创建自增主键id不需要手动定义。定义完模型数据库里其实还没有这张表下一步需要生成迁移文件并执行迁移。4.2 生成并执行迁移makemigrations 和 migrate在终端运行这两条命令python manage.py makemigrations home python manage.py migratemakemigrations会根据models.py的变化生成一个描述“我要在哪张表里增加哪些字段”的迁移文件存在home/migrations/目录下。migrate才是真正把这些迁移应用到数据库。很多新手会问为什么不能一条命令直接建表因为生成迁移文件这个步骤让你在真正改数据库之前可以再检查一遍字段定义是否正确也给团队协作提供了版本记录。如果makemigrations提示No changes detected通常有几种原因模型没有变化、app 没有注册或者你指定的 app 名称写错了。执行完迁移可以打开 PyCharm 的 Database 工具面板连接项目里的db.sqlite3文件刷新一下就能看到 Django 帮你创建的十几张表其中包括刚刚的home_question表。Django 的表名规则是“app名小写_模型名小写”比如home_question。用工具直接看数据很方便但要注意不要手动乱改表中的数据尤其是用 SQL 直接删改Django 有自己的一套缓存机制手动改容易引发莫名的数据问题。4.3 用 Django Admin 管理数据Django 自带一个很强大的后台管理系统之前我们在根路由里已经配了admin/。要想进入后台首先得创建一个超级管理员账号python manage.py createsuperuser命令会依次提示输入用户名、邮箱可选和密码。注意密码要求不少于 8 位且不能太简单。创建完成后刷新http://127.0.0.1:8000/admin/用刚才的账号登录就能看到 Django 自带的管理界面。不过此时Question表还没有出现在后台里需要在home/admin.py里注册一下from django.contrib import admin from .models import Question admin.site.register(Question)注册后重新进入后台就能看到 Question 的管理入口可以新增、编辑、删除数据非常直观。对于学习阶段来说用后台往数据库里塞几条测试数据比手动写 SQL 方便多了。4.4 数据库迁移出现冲突怎么办迁移是 Django 项目里很容易出问题的环节尤其是多人协作或者自己反复修改模型时。一个非常常见的场景是你在模型里加了字段执行了迁移后来又改了再执行迁移时报错说“It is impossible to add a non-nullable field ... because it needs a default value”。意思是新增的字段非空但表里已经有数据Django 不知道给旧数据填什么值。解决办法是在迁移命令的交互提示里给一个默认值或者先删除数据库里已有的测试数据再重新迁移。如果是自己本地学习用的项目最简单的方式是直接删除db.sqlite3文件删掉migrations目录下除了__init__.py之外的文件然后重新执行makemigrations和migrate。这个方法很暴力但确实能解决绝大多数本地开发的迁移困局。5. 让页面更完整模板、静态文件与表单只返回一段普通字符串的页面显然不够用。接下来我们把视图改成渲染 HTML 模板加入静态文件支持再做一个小表单这部分是最能体现 Django 开发体验的地方。5.1 模板目录和渲染变量在home应用下创建templates/home/index.html目录结构注意 Django 默认的模板查找规则是“应用名/templates/应用名/模板名”这样设计是为了避免多个应用里的同名模板互相覆盖。比如home/ ├── templates/ │ └── home/ │ └── index.html在index.html里写点基本 HTML 结构!DOCTYPE html html langzh-cn head meta charsetUTF-8 title首页/title /head body h1{{ welcome_text }}/h1 p当前时间{{ current_time }}/p /body /html双花括号{{ }}是 Django 模板的变量占位符。在视图里我们用字典把变量传给模板from django.shortcuts import render from django.utils import timezone def index(request): context { welcome_text: 欢迎来到 Django 项目, current_time: timezone.now(), } return render(request, home/index.html, context)render函数会加载指定的模板文件用context里的数据填充模板中的变量再把渲染后的 HTML 返回给浏览器。这是 Django 模板系统最基础也最常用的用法。模板里除了变量还有{% if %}、{% for %}这类模板标签可以在 HTML 里写简单的逻辑但不要把复杂的业务逻辑堆在模板里模板的核心是展示数据不是处理数据。5.2 静态文件CSS 和图片为了让页面稍微好看一点我们需要引入 CSS。Django 通过static目录来管理静态文件。在home应用下新建static/home/style.css例如body { font-family: Microsoft YaHei, sans-serif; background-color: #f5f5f5; padding: 40px; }然后在模板开头加载静态文件并引入 CSS{% load static %} !DOCTYPE html html langzh-cn head meta charsetUTF-8 link relstylesheet href{% static home/style.css %} title首页/title /head{% load static %}告诉模板文件需要使用静态文件功能{% static home/style.css %}会生成实际的文件 URL。在开发阶段Django 会自动处理静态文件不需要额外配置但到部署阶段静态文件的收集和托管是一个重点话题那时候会用到python manage.py collectstatic。学习阶段只要记住静态文件要放在 app 下的static目录里就行。5.3 让页面接收表单数据POST 与 CSRF很多 Web 应用都需要用户输入比如投票选择、评论留言。Django 对表单提交有严格的安全要求其中一个绕不开的概念是 CSRF 防护。简单说CSRF 是一种攻击方式它让受害者在不知情的情况下向某个已登录网站发送恶意请求。Django 的解决办法是要求所有 POST 表单都携带一个随机 token用于验证请求确实来自当前站点。模板里的表单可以这样写form action{% url vote %} methodpost {% csrf_token %} label input typeradio namechoice value1选项一 /label label input typeradio namechoice value2选项二 /label button typesubmit提交/button /form注意{% csrf_token %}一定不能删否则提交时会得到 403 错误。视图里处理 POST 请求时需要区分请求方法from django.shortcuts import render, redirect from django.http import HttpResponse def vote(request): if request.method POST: choice request.POST.get(choice) # 这里可以执行数据保存逻辑 return HttpResponse(f你选择了 {choice}) return redirect(index)用request.POST.get(choice)获取表单提交的数据。这只是最基础的处理方式真正的项目里还会有表单验证、幂等处理、错误提示等内容但核心链路已经通了模板展示表单浏览器提交 POSTDjango 根据 URL 找到vote视图视图处理请求并返回响应。到了这一步你已经不是一个只会“看教程”的人了而是实实在在地理解了 Django 的请求处理流程。6. 运行、调试与常见问题排查做到这里项目已经完整跑起来了。但在实际开发中遇到问题几乎是必然的所以我整理了一份自己的排查经验。这些经验不是从官方文档里抄来的而是在一次次踩坑之后总结出来的。6.1 用 PyCharm Debug 按钮定位问题很多同学遇到报错第一反应是看最下面几行红色日志然后到处复制错误信息搜索。这样做当然有用但调试复杂逻辑时PyCharm 的断点调试效率更高。在代码行号后面点一下会出现红色圆点这就是断点。启动调试模式后请求走到这一行会暂停此时你可以查看当前函数里所有变量的值也可以按“Step Over”一步步执行观察代码分支走向。举个例子视图里拿到一个request.POST你不确定里面有没有某个字段直接在断点上查看request.POST的字典内容比盲猜快得多。调试还有一个好处不会像print那样污染代码你不需要在调试完后再到处删打印语句。DEBUG 模式下 Django 会自动关闭模板缓存改完模板文件刷新浏览器就能看到新效果这一点比普通运行模式更舒服。6.2 常见问题速查表这里把我遇到最多的几类问题整理成一个表格方便大家直接对照。问题现象可能原因解决办法No module named django当前环境没有安装 Django或 PyCharm 解释器选错检查 PyCharm 的解释器路径进入项目虚拟环境后执行pip install djangoError: That port is already in use8000 端口被另一个进程占用更换端口运行python manage.py runserver 8001TemplateDoesNotExist模板目录位置不对或应用未注册确认模板放在templates/应用名/模板名并在INSTALLED_APPS注册应用NameError: name redirect is not defined视图文件里没有导入该函数在文件头部加上对应的import语句Unknown command: startapp命令敲错或没有在项目根目录执行先确认终端位置在manage.py同目录再执行python manage.py startapp 应用名提交表单返回 403模板缺少{% csrf_token %}在表单中加入{% csrf_token %}页面修改后没生效开发服务器未自动重启或浏览器缓存重启服务器刷新页面或更换浏览器测试数据库新增字段后迁移失败旧表已有数据非空字段无法直接添加给新字段设置默认值或删除本地测试数据重新迁移这个表格对应的是新手阶段最常见的八类问题。其中TemplateDoesNotExist是出现频率最高的一类几乎每个人都会遇到。核心原因往往不是模板文件不存在而是 Django 在配置的模板查找路径里没找到它。只要确认模板放在templates目录下的正确层级并且在INSTALLED_APPS里注册了对应应用这个问题基本能解决。6.3 开发服务器的自动刷新机制Django 开发服务器自带热重载auto-reload当你修改.py文件时它会自动重启所以大多数时候改完代码直接刷新浏览器即可。但要注意几个例外新增了文件比如新建了urls.py、模板文件、静态文件有时需要手动重启服务器如果使用了 PyCharm 的 “Safe Write” 功能在某些操作系统上可能会触发多次重启这个问题可以通过关闭 Safe Write 来缓解。另外调试模式下改动模型后不要指望服务器自动替你迁移数据迁移命令仍然需要手动执行。runserver还有一个用途比较冷门但它很适合新手踩坑时绕过浏览器限制。你可以用python manage.py runserver 0.0.0.0:8000让服务器监听所有网络接口这样同一局域网里的手机或另一台电脑也能访问。这个操作在调试移动端页面时很方便但要注意开发服务器不应该直接暴露到公网它没有并发处理能力和安全防护只适合在受信任的内网环境里使用。6.4 我的个人实操笔记最后分享几个我自己的习惯不算什么高深技巧但确实帮我省了很多时间。第一创建新项目时我不会只用 PyCharm 的模板而是先在终端里django-admin startproject创建好目录再用 PyCharm 打开。这样我能清楚每一步发生了什么出现问题也知道去哪排查。第二每次写模型前我会先在纸上画出字段和表关系确认后再写进models.py这能大幅减少后面返工修改模型的次数。第三定期备份db.sqlite3数据库文件因为本地开发时经常要折腾迁移一个操作失误可能把所有测试数据清空有备份就能退回上一步。我还习惯在项目里顺手配置一个.gitignore文件至少把venv、__pycache__、db.sqlite3排除掉避免把虚拟环境和本地数据库提交到代码仓库。这样别人 clone 项目后只需要pip install -r requirements.txt并执行migrate就能把项目跑起来。等你有机会接触真实团队项目时会发现这些都是再普通不过的基本功。从创建虚拟环境到写第一个视图从定义模型到完成后台管理再到模板渲染、表单提交和调试排查你已经把 Django 项目从零到一完整跑通了。剩下的路就是在项目里加入更复杂的业务逻辑、更完善的分层结构以及读一读 Django 官方文档里关于 ORM、认证、部署这些更深入的内容。如果你在练习过程中遇到了今天没列出来的报错先别急着到处问把错误信息完整读一遍再对着路径、环境、版本这三个方向排查大部分问题都能自己解决。