很多人第一次在 PyCharm 里折腾 Django都会遇到同一个状况按照教程创建了项目结果一运行就各种报错排查到最后往往只是一个解释器或者一个模板路径的问题。尤其那句“No module named django”几乎每星期都能看到有人截图问。其实这些坑大多不是 Django 难而是 PyCharm 的图形界面掩盖了环境细节让人产生“我明明点击了创建按钮为什么还是不行”的错觉。这篇我就以自己实际跑过的流程为主完整讲一遍在 PyCharm 里创建 Django 项目需要关心的所有东西环境准备、创建方式、跑通第一个页面、数据库操作、高频报错排查以及怎么装插件让 IDE 顺手。适合刚装好 PyCharm 还没正经做过 Web 项目的人也适合被各种报错折磨到怀疑人生的半新手。跟着走一遍你会理解 PyCharm 和 Django 到底是怎么配合工作的以后遇到问题也知道往哪个方向查。1. 动手前先决定三件事解释器、虚拟环境和 PyCharm 版本1.1 选 Python 解释器系统 Python、Anaconda 还是项目虚拟环境在 PyCharm 里创建 Django 项目之前第一件事不是创建项目而是想清楚用哪个 Python 解释器。很多新手一上来就点 New Project然后咔咔选一堆默认项结果装完 Django 找不到包项目跑不起来回头才发现解释器根本不对。常见的解释器选项有下面几种系统自带的 Python比如 macOS 上预装的 Python 2或者 Windows 上自己安装的 Python 3。它能用但也很危险尤其是当你用pip install --user往用户的 site-packages 里装包时PyCharm 里的解释器很可能指向系统的另一个目录两边完全对不上。Anaconda / Miniconda 创建的 conda 环境适合做数据分析、科学计算的同学。PyCharm 支持得很好可以在 Settings 里指定已有的 conda 环境作为解释器。项目虚拟环境virtualenv / venvPyCharm 创建项目时默认会帮你生成一个 venv 目录这个环境只服务当前项目。我个人在写 Django 项目时最推荐的就是项目虚拟环境。原因很简单不同 Django 项目的依赖版本经常冲突。今天这个项目用 Django 4.2明天接手一个老项目还在用 Django 2.2如果大家都装在一个全局环境里安装卸载起来就是一场灾难。而 venv 把每个项目的依赖隔离在项目内部互不干扰换电脑拉代码后只需要重新pip install -r requirements.txt就行。如果你已经装了 Anaconda也不用推翻重来。PyCharm 创建项目时在解释器下拉框选择 Existing environment找到你 conda 环境里的 python.exe 就行。但我不建议把好几个 Django 项目都塞到同一个 conda 环境里那样和用全局环境没有本质区别版本冲突照样会找你。我记得自己刚学 Django 那会儿图省事把所有包都装在全局。后来为了跑一个旧项目把 Django 降级结果新项目立刻报错连django.conf.urls.static都找不到了。从那以后我再也不嫌 venv 麻烦每个项目建一个独立环境才是正经答案。1.2 为什么 PyCharm 的虚拟环境里还要手动装 Django很多新手以为在 PyCharm 里勾选了虚拟环境Django 就已经装好了。实际上PyCharm 创建 venv 时只帮你创建了环境里面的包是空的。你需要再执行一次安装操作。最直接的方法是在项目底部的 Terminal 里输入pip install django如果你不想用命令行也可以在 PyCharm 左下角的 Python Packages 窗口里搜索 Django点击 Install。但我更建议新人学会在 Terminal 里用 pip因为以后部署、写脚本、排查问题都绕不开它。这里要强调一个容易混淆的点你在 PyCharm 的图形界面上看到的解释器下拉框和 Terminal 里实际使用的 Python可能是同一个也可能不是同一个。PyCharm 的 Terminal 默认是自动激活当前项目虚拟环境的但如果你之前手动切换过解释器或者打开了多个项目窗口Terminal 里的环境可能已经跑偏了。所以装包后最好先执行一次pip show django确认装到了哪个环境再运行项目。1.3 PyCharm 版本怎么选社区版还是专业版PyCharm 分社区版Community和专业版Professional。社区版免费但新建项目向导里没有 Django 模板专业版收费但提供 Django 模板、数据库工具、Web 调试面板等对 Web 开发体验提升很大。如果你是正式要用 Django 写项目预算也允许专业版是非常值得投入的。但如果你刚开始学或者只是应付课程作业社区版完全够用。社区版创建 Django 项目只比专业版多几步手动操作而已后面我会专门讲两种创建方式。需要注意的是我不建议去折腾各种“激活”手段一方面有版权风险另一方面也不稳定。PyCharm 社区版的许可证完全免费足够你跑通本教程。等你真的需要专业版功能了再考虑正式订阅即可。工具只是工具用什么版本不耽误你理解 Django 的原理。2. 在 PyCharm 里创建 Django 项目的两种姿势模板向导与手动搭建2.1 专业版创建用 Django 模板一步到位专业版的操作非常直观。打开 PyCharm点击 File → New Project左侧选择 Django。右侧的 Location 填项目路径Python Interpreter 建议选择 New environment using Virtualenv。下方 More Settings 里有一个 App name 输入框可以顺便创建你的第一个 app不过我一般先不填等项目骨架起来后再用命令创建这样目录结构更清晰也方便理解每层的作用。点击 Create 之后PyCharm 会自动完成这些事情创建虚拟环境、用django-admin startproject生成项目结构、在 Settings 里配置好 Django 支持。你打开项目就会看到 manage.py 和项目同名目录。这里有一个我很想吐槽的默认行为如果你在 Location 里填的路径最后已经带了一个新文件夹名PyCharm 有时候还会再拼一层同名目录进去。比如你填D:\Projects\myblog它可能生成D:\Projects\myblog\myblog这样的嵌套结构里面那层才是真正的项目配置目录。这种嵌套会让人一脸懵。我现在的习惯是创建后先看一眼 Project 树如果发现多了一层可以在本地文件管理器里调整目录位置或者干脆在创建时手动核对 Location 的最终路径。2.2 社区版创建从空项目手动搭建 Django社区版没有 Django 模板但流程也不复杂就是多几步手动操作。第一步New Project 选择 Pure Python解释器照样用虚拟环境。创建完成后打开 Terminal先确认当前解释器是项目的 venv然后安装 Djangopip install django第二步执行django-admin startproject。这里的关键是最后那个点django-admin startproject config .那个英文句号并不是符号而是告诉 Django “在当前目录下生成项目”。如果没有这个点Django 会在当前目录下再创建一个新的嵌套目录比如config/config目录结构瞬间乱掉。我见过太多人因为在教程里漏掉了这个点项目里莫名其妙多了一层文件夹然后怎么删都删不干净。第三步手动告诉 PyCharm 这是一个 Django 项目。打开 Settings → Languages Frameworks → Django勾选 Enable Django Support然后在 Configuration 里把 Django 项目的根目录指定为项目根目录Settings 文件指定为config/settings.pyManage 工作文件指定为manage.py。填完之后PyCharm 才能识别 Django 项目的结构提供模板补全、URL 跳转、runserver 配置等能力。如果不做这一步PyCharm 会把所有文件当成普通文本虽然项目也能跑但你会失去很多 Django 专属的开发便利。2.3 初始目录结构逐个看manage.py、settings.py、urls.py 都在干什么项目创建好以后不管用哪种方式你都会看到这几个初始文件。我建议在写任何代码之前先花十分钟把这些文件认一遍很多人后面踩坑就是不清楚它们的职责。manage.py项目命令行工具入口。几乎你所有跟项目交互的命令都要经过它比如python manage.py runserver、python manage.py startapp、python manage.py migrate。项目同名目录比如 config这是一个 Python 包承载整个项目的配置和根路由。重点看settings.py是全局配置包含数据库、安装的 app、中间件、静态文件路径、语言时区等。urls.py是根路由表浏览器请求进来后先到这里匹配。wsgi.py和asgi.py是部署时才用到的接口。后面你创建的 app 目录每个 app 有自己的models.py、views.py、migrations目录等业务代码基本都放在 app 里。理解这个结构你才会明白为什么创建 app 时 Django 会提示“项目”和“应用”是两个概念。项目是整个网站的容器应用是网站里具体的功能模块。一个博客项目里可以同时有 blog、users、comments 等多个 app。3. 跑通第一个 Django 页面从 runserver 到请求-响应流程3.1 启动服务Terminal 直接跑还是配置 Django Server写完代码第一步当然是启动开发服务器。PyCharm 里有两种常见方式。第一种在 Terminal 里执行python manage.py runserver如果一切正常会看到如下提示Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.然后浏览器打开这个地址就能看到默认的 Django 欢迎页。这种方式简单直接适合新手也适合给同事演示快速效果。第二种配置一个 Django Server 运行配置。打开 Run → Edit Configurations点击加号选择 Django ServerHost 填 127.0.0.1Port 填 8000确定后就能像运行普通脚本一样点绿色三角启动。这种方式的好处是你可以在代码中打断点在 PyCharm 的 Debug 模式下查看请求流程中每个变量的值也可以直接在 Run 面板看到输出比较适合正式开发。我个人日常都用第二种毕竟调试是 PyCharm 的看家本领。如果你是新手第一次跑项目建议先用 Terminal先看到运行起来的输出理解 Django 启动过程再切换到配置方式。3.2 创建 app 并注册startapp 之后别忘记 INSTALLED_APPSDjango 的一个规矩是业务代码要放在 app 里而不是堆在项目根目录。创建 app 的命令python manage.py startapp blog执行后项目里会多出一个 blog 目录里面包含models.py、views.py、admin.py、apps.py、tests.py和migrations/。这一步很简单但第二步很多人容易漏在settings.py的INSTALLED_APPS列表里加上blog。举个例子方便理解INSTALLED_APPS相当于网站的“已注册功能模块”名单。你建了 blog 这个模块但没写进名单里Django 就不会激活它。后面你会遇到“表好像建了但 admin 后台里看不到”“模板标签不能用”这种奇怪问题一查原因往往都是这里漏了注册。所以在创建完 app 后我建议立刻打开settings.py把 app 名加到INSTALLED_APPS里INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, ]3.3 手写第一个接口view urls template 三件套依次创建三个文件的内容就能看到第一个动态页面了。先在blog/views.py里写一个视图函数from django.shortcuts import render def home(request): return render(request, blog/home.html, {name: PyCharm 新人})接着在blog/urls.py里这个文件需要你自己新建配置路由from django.urls import path from . import views urlpatterns [ path(, views.home, namehome), ]最后在项目的根urls.py里把 blog 的 urls 挂进去from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]再创建模板文件blog/templates/blog/home.html里面写h1Hello, {{ name }}/h1启动服务打开 127.0.0.1:8000就能看到 “Hello, PyCharm 新人”。这里要解释一下模板目录为什么是blog/templates/blog/这种嵌套结构。Django 默认会到每个 app 的templates目录里找模板找的时候按照INSTALLED_APPS的顺序查找。如果你直接把模板放在blog/templates/home.html假设另一个 app 里也有同名home.htmlDjango 会先找到谁就渲染谁很容易出现“我的模板怎么被别人的盖掉了”这种灵异事件。所以模板里再加一层以 app 命名的子目录可以有效避免命名冲突。如果你有全局模板目录比如项目根目录下建了一个templates文件夹不想放在 app 里那就必须在settings.py的TEMPLATES配置里手动指定DIRS: [BASE_DIR / templates],不加这个配置Django 在全局模板目录里是找不到文件的这是TemplateDoesNotExist报案的常见来源之一。4. 数据库层的正餐模型定义、迁移和查询删除对象4.1 默认 SQLite 够用先别急着上 MySQLDjango 的settings.py里默认配置的是 SQLiteDATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } }SQLite 适合新手因为数据库就是项目目录下的一个文件不需要额外安装和启动数据库服务也不能更省事。你在 PyCharm 右侧的 Database 工具里可以直接把这个.sqlite3文件拖进去用图形界面查看表结构和数据调试非常方便。如果你以后要上正式服务器换成 MySQL 或 PostgreSQL 也很简单。settings.py里换掉ENGINE填写NAME、USER、PASSWORD、HOST、PORT然后记得在虚拟环境里装对应的驱动MySQL 常用mysqlclient或pymysql。但我不建议新手一开始就折腾数据库连接先用 SQLite 把整个项目流程跑通再来理解数据库切换的差异会平滑很多。4.2 从模型到数据库表makemigrations 和 migrate 的区别以博客文章为例在blog/models.py里定义一个最简单的模型from django.db import models class Article(models.Model): title models.CharField(max_length100) content models.TextField() created_at models.DateTimeField(auto_now_addTrue) def __str__(self): return self.title定义完模型后数据库里还不会自动创建表。你需要执行两条命令python manage.py makemigrations python manage.py migrate很多新手分不清这两个命令。我用大白话解释makemigrations是把你的模型改动生成一份“改造计划”文件记录要建什么表、加什么字段migrate才是拿着这份计划真正去数据库执行改造。如果只做makemigrations不执行migrate数据库里还是没有表如果直接改模型不执行makemigrationsDjango 甚至会提醒你先做迁移。执行成功后再打开 PyCharm 的 Database 工具就能看到blog_article表了。4.3 在 Django shell 里执行查询和删除get、filter、delete 的区别调试模型和数据比起在视图里写代码再页面刷新直接用 Django shell 更高效。在 Terminal 里执行python manage.py shell就会进入一个专门绑定项目配置的 Python 交互环境可以像普通 Python 一样操作模型。创建一条数据from blog.models import Article Article.objects.create(title第一条测试, content这是一段内容)查询所有对象Article.objects.all()如果要按条件筛选可以用filterArticle.objects.filter(title__contains测试)如果要取单个对象用getart Article.objects.get(id1)这里有一个我用无数次教训换来的提醒get在找不到数据时会抛DoesNotExist异常如果找到多条又会抛MultipleObjectsReturned异常而filter返回的是一个QuerySet对象即使没有数据也只是空列表不会报错。所以当你只想要第一条的时候我更推荐art Article.objects.filter(id1).first()删除对象就更直接了art Article.objects.get(id1) art.delete()或者按条件批量删除Article.objects.filter(title__contains测试).delete()这里顺带讲一个 QuerySet 的“惰性”特征你写Article.objects.all()的时候Django 并没有立刻执行数据库查询只有当你真正需要用到数据时比如遍历、取值、打印才真正触达数据库。所以在 PyCharm 的 Debug 模式里你可能会看到变量显示为QuerySet [...]你以为它里面已经有数据了其实可能还没有请求数据库你继续运行它才会展开。这也是调试时容易让人困惑的点。如果你想把这个查询结果导出成数据分析用的格式可以先pip install pandas然后在 shell 里执行import pandas as pd data pd.DataFrame(list(Article.objects.values()))随后就能用 pandas 做进一步分析或导出 CSV。这个场景在爬数据、做报表时会经常用到属于 Django 和数据分析结合的小技巧。5. 新手最容易踩的五个坑现象、原因和排查链路5.1 “No module named django”解释器和包安装位置不一致这个报错是所有 Django 新手共同的家。现象就是在 PyCharm 里运行项目时提示找不到 django 模块。排查链路我建议按顺序来打开 Terminal先执行pip show django看 Django 是否安装以及它装在了哪个环境。打开 Settings → Project → Python Interpreter确认当前解释器路径是不是你项目里的 venv。如果解释器是系统 Python而刚才pip show django显示的是另一个环境里的路径那就把解释器切换成项目虚拟环境或者在那虚拟环境里重新pip install django。我自己的习惯是每次创建完项目先到解释器设置里确认路径然后再装包。很多人一连报错好几天其实就是这个小事。5.2 “That port is already in use”端口被占用的根治办法起服务时忽然提示端口被占用大概率是之前的 runserver 进程没有完全退出或者系统里别的程序占用了 8000 端口。解决方式有两种临时换端口python manage.py runserver 8001。查找并结束占用进程。macOS/Linux 执行lsof -i :8000查到 PID然后kill -9 PIDWindows 执行netstat -ano | findstr :8000看 PID再taskkill /PID 你的PID /F。这个操作属于 Web 开发的生存技能任何人都躲不掉早学会早安心。5.3 “TemplateDoesNotExist”模板目录查找规则没搞清渲染模板时报找不到模板第一反应不要急着乱改路径先按顺序检查模板文件是否存在于app/templates/下文件名是否拼对。如果放在项目根目录的全局templates下那settings.py的TEMPLATES里DIRS有没有把路径加进去。如果多个 app 里有同名模板有没有因为名字冲突被别的 app 抢先命中。这个坑的本质是对 Django 模板查找规则不熟。记住每个 app 的templates目录是默认会搜索的但全局模板目录必须手动配置。5.4 “no such table”忘了执行迁移在 shell 或页面里操作模型时报OperationalError: no such table: blog_article十有八九是没执行migrate或者数据库文件选错了。处理办法先执行makemigrations再执行migrate。如果表依然不存在检查settings.py里的db.sqlite3路径和你在 PyCharm Database 工具里连接的 SQLite 文件路径是否一致。有时候项目根目录变了PyCharm 连接的是旧位置的文件看起来“明明有表却查不到”实际上你查的不是同一个库。5.5 PyCharm 里点运行报 import 错误Terminal 里却正常这种情况通常是运行配置的工作目录没设对。打开 Run → Edit Configurations把 Working directory 设置为项目根目录也就是manage.py所在的那一层。Python 跑起来后会把这个目录当作当前路径import 才能正确找到项目里的模块。如果还不放心可以在Settings里找到Project Structure把项目根目录标成Sources根。这样 PyCharm 就会把根目录加入模块搜索路径比在代码里sys.path.append硬来干净得多。6. 把 PyCharm 调教成趁手的 Django 开发工具插件与快捷键6.1 中文语言包新手降低门槛的最快方式如果你看英文菜单费劲可以在插件市场搜索Chinese (Simplified) Language Pack安装重启后界面就是中文的。这个插件对完全没接触过 IDE 的新手非常友好能减少很多“这个选项在哪”的焦虑。不过我也想说一句中文界面方便理解但看英文提示的能力还是得慢慢锻炼因为真正查报错、搜问答时你面对的大多数还是英文内容。把中文插件当成过渡而不是依赖。6.2 AI 插件Fitten Code、通义灵码这些值不值得装现在 AI 辅助编码的插件选择很多常见的有 GitHub Copilot、通义灵码、Fitten Code 等。如果你想在 PyCharm 里获得补全和问答能力这几个都可以在插件市场直接安装。Fitten Code 对中文场景比较友好免费且补全速度快通义灵码也是免费适合国内开发者团队如果统一用 GitHub Copilot体验同样很顺。不过我的真实体会是AI 补全在写 CRUD 代码、工具函数、正则表达式时确实能省时间但在理解 Django 的 ORM 行为、调试复杂逻辑时它帮不了太多。你还是要掌握前面那些基础概念不然 AI 生成的代码出错了你可能连错误在哪都看不懂。所以我的建议是插件可以装但重心永远放在自己理解框架上。6.3 我每天都会用到的 PyCharm 快捷键和 Django 配置不同系统按键有差异我说几个通用的高频操作Shift F10Windows/Linux/Control RmacOS运行当前配置文件。Shift F6重命名文件、变量或方法PyCharm 会同步更新所有引用比手动全局替换安全得多。双击 Shift全局搜索任何文件、类、命令。Ctrl Alt L格式化代码。Alt F12快速打开 Terminal。Django 专属技巧方面当你配置好 Django Support 后在urls.py的路由函数上右键选择 “Open URL in Browser”可以直接在默认浏览器打开对应地址省去手动敲 URL 的麻烦。模板里{{ }}中的变量也可以用 Ctrl左键跳转到 view 里对应的上下文来源方便梳理数据流向。最后补一句我个人的使用习惯我不太喜欢给 PyCharm 装一大堆管理manage.py的图形化工具反而觉得在 Terminal 里敲命令更直接、更不容易出错。PyCharm 自带的 Termimal 面板已经和项目环境绑定好了执行命令和 IDE 交互互不冲突这也是我不切换外部终端的原因。工具配置得再顺手最终还是要落到多跑、多试、多排查上。把这套流程从头到尾走通一遍你对 Django 项目的理解会上一个台阶以后看官方文档也能更加顺心。