作为一名常年跟 Python 打交道的人我太清楚新手在“环境搭建”这一步有多容易劝退了。可能你刚看完 Django 的官方文档兴冲冲地打开终端准备大干一场结果卡在“装完 Python 之后下一步干嘛”、“VS Code 里怎么打开终端”、“为什么 pip 命令提示不是内部或外部命令”这种问题上。今天这篇我就用最贴近实操的方式带你完整走一遍在 VS Code 里配置 Django 环境、创建第一个 Django 项目的全过程。整个过程我会把每一步背后的逻辑、踩过的坑、以及当前社区里最主流的做法都讲清楚保证你跟着做下来不仅能把项目跑起来还能顺手把“虚拟环境”“解释器选择”“调试配置”这些概念搞明白。这篇内容适合谁刚学 Python 不久、想用 Django 写 Web 后端的新手以及想从 PyCharm 转到 VS Code 的开发者。它解决什么问题解决“打开了编辑器却不知道从哪里下手”的尴尬给你一套可以照抄的、在 VS Code 里开发 Django 项目的基础配置流程。1. 项目整体设计与思路拆解先说整体思路。我们在 VS Code 里做 Django 开发本质上要搭建三层结构Python 解释器 → 虚拟环境 → Django 项目。大多数教程只会把命令给你但不会解释为什么要有虚拟环境、为什么要在 VS Code 里手动选解释器。如果你不懂这个后面一旦遇到报错就会整个人懵掉。1.1 为什么选 VS Code 而不是 PyCharmPyCharm 确实是个好工具开箱即用创建 Django 项目的时候界面化操作省心。但它有两个痛点一是专业版收费社区版虽然免费但有很多高级功能比如数据库工具、前端支持用不了二是 IDE 太重启动慢、占内存如果你的电脑配置一般开一个 PyCharm 再开一个浏览器风扇就开始转了。VS Code 的优势是轻量、插件生态丰富而且能通过插件把 Django 开发体验拉到和 IDE 差不多的水平。比如 Python 插件提供智能感知IntelliSense、调试、自动补全Django 插件提供模板语法高亮、快捷创建文件甚至还有数据库前端、REST Client 这类辅助工具。说白了VS Code 是一个高度可扩展的“编辑器骨架”你往它里面加什么功能取决于你装什么插件。这对长期做前后端分离开发的人来说特别舒服——一套编辑器搞定前后端。1.2 虚拟环境为什么是必需品很多新手跳过虚拟环境直接在全局环境里pip install django当时没事等项目多了就爆炸。举个真实例子你项目 A 用的是 Django 3.2项目 B 需要 Django 5.0如果都在全局环境里那么每次切换项目都要先卸载旧版本再装新版本装来装去可能某天就把环境搞坏了连 pip 都崩了。虚拟环境就是给每个项目独立开一个“专属的 Python 环境”互不干扰。项目 A 装了 3.2项目 B 装 5.0井水不犯河水。Python 自带的venv模块就是干这个事的不需要安装额外的东西官方也推荐。在 VS Code 里只要你先创建好虚拟环境然后用 VS Code 打开项目文件夹它通常会自动识别或者你手动选择一下解释器之后的操作全都是基于这个虚拟环境进行的。2. 环境准备Python、VS Code 与虚拟环境初始化在正式开始创建 Django 项目之前有两件事必须做安装 Python、安装 VS Code。别觉得这是废话我在社群里见过太多次因为 Python 没勾选“Add to PATH”导致后面 pip 全挂的案例。2.1 Python 安装与 PATH 问题去 Python 官网下载最新的稳定版建议 3.10 及以上Django 官方支持的版本也是这些。安装时有一个关键选项Add Python to PATH一定要勾上。这一步如果不勾后面你在命令行里敲python就会提示“不是内部或外部命令”本质是系统找不到 python.exe 的位置。装完之后怎么验证打开终端Windows 按Win R输入cmd或者直接用 VS Code 的终端输入python --version正常会输出类似Python 3.12.x。如果提示python不是内部命令那大概率是 PATH 没配好。我不建议新手手动去系统变量里折腾最快的方案是重装 Python然后勾上 PATH 选项省心省力。2.2 创建项目文件夹与虚拟环境假设你要创建一个名为myblog的项目用博客来练手是 Django 初学者最经典的路径。先在D:\dev或者你自己喜欢的目录下创建myblog文件夹然后用 VS Code 打开这个文件夹cd D:\dev mkdir myblog cd myblog code . # 这会在当前目录下打开 VS Code在 VS Code 里打开终端快捷键Ctrl 输入python -m venv venv这条命令的意思是用 Python 的venv模块在当前目录下创建一个虚拟环境环境名叫venv这是约定俗成的名字你也可以叫.venv效果一样。执行完你会发现文件夹里多了一个venv目录里面就是打包过来的 Python 解释器和 pip。注意这个venv目录千万不要删也不要手动去翻里边的文件。然后激活虚拟环境。Windows 系统输入venv\Scripts\activate终端提示符前面会多了一个(venv)说明现在已经在虚拟环境里了。这时候你执行pip install操作都是装在这个独立环境里的不会污染全局。macOS/Linux 系统略有不同用的是source venv/bin/activate但 Windows 用户按我上面来就好。提示如果激活之后pip命令报错先检查一下是不是因为终端当前目录不在项目根目录。另外VS Code 的终端默认会启动 PowerShell有些安全策略可能禁止执行脚本报错内容是无法加载文件 ... 因为在此系统上禁止运行脚本此时以管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned即可解决。2.3 VS Code 安装与必要插件VS Code 官网下载安装包一路 Next 安装。装完后左侧工具栏有一个“扩展”图标四个方格那个图标搜索并安装以下插件PythonMicrosoft 官方出品必装提供代码补全、语法检查、调试、Jupyter 支持等核心功能。Django开源社区维护模板语法高亮、内置代码片段、跳转到视图/模板定义等对 Django 开发体验提升很大。PylanceMicrosoft 官方一般随 Python 插件自动安装提供更强大的类型检查和智能提示。顺便说一个大家都关心的问题VS Code 怎么汉化扩展里搜Chinese (Simplified) (简体中文) Language Pack安装后右下角弹窗选“Change Language and Restart”重启后就变成中文界面了。这是官方插件放心装。安装完插件后必须做的一件事把刚才创建的虚拟环境选为解释器。回到 VS Code按Ctrl Shift P打开命令面板输入 “Python: Select Interpreter”选择venv环境一般会显示venv的路径。这一步是核心选错了后面打开项目的时候 VS Code 用的就不是你的虚拟环境装 Django 全装到全局里去了也会出现“明明装了 Django 但 import 报错”的奇怪问题。3. 创建 Django 项目与核心配置实操环境铺好了接下来就是重头戏创建 Django 项目。这里为了照顾到新手我会把每一个命令的作用、生成的文件结构、以及后续要手动改哪些配置都讲清楚。3.1 安装 Django 并创建项目确保终端里处于激活状态终端前缀有(venv)执行pip install django装的是最新稳定版当前是 5.x。装完之后别急着开始先用pip show django看一眼安装路径确认是装在了 venv 环境里而不是全局环境。这一步虽然不是必须的但能让你心里有个底。然后创建项目。Django 官网用一个mysite项目做例子但你最好取自己的名字。我在这里用myblogdjango-admin startproject config .注意末尾这个点.非常重要。它的意思是“在当前目录下创建项目配置”生成的config文件夹就是你的全局配置目录settings.py、urls.py、wsgi.py、asgi.py 都在这里面。如果忘了加点Django 会再创建一个myblog子目录项目结构就变成嵌套的后续跑起来容易混乱。创建完之后目录结构大概是这样myblog/ ├── venv/ ├── config/ │ ├── __init__.py │ ├── settings.py │ ├── urls.py │ ├── asgi.py │ └── wsgi.py └── manage.pymanage.py是 Django 给项目提供的一个管理工具入口以后运行服务器、迁移数据库、创建 app全都要通过它来执行。3.2 创建 App 并注册到 SettingsDjango 的架构是“项目 应用”模式。项目Project是全局的配置和调度应用App是具体的业务模块比如博客的posts、users、comments。继续在终端执行python manage.py startapp posts执行后会出现一个posts文件夹里面有models.py、views.py、admin.py、migrations/等。现在先不管里面代码第一件事是去config/settings.py里的INSTALLED_APPS列表里把posts注册进去不然后面数据库迁移和 Django 自己提供的后台管理页面都识别不到这个 App。打开config/settings.py找到INSTALLED_APPS在最后一行追加posts,记得带逗号。很多初学者会漏掉这一步结果创建完 app 之后执行迁移被告知 “No installed app with label posts”。3.3 配置语言、时区与静态文件settings.py里还有三个常见的要改的地方LANGUAGE_CODE、TIME_ZONE、STATIC_URL。Django 默认LANGUAGE_CODE是en-us时区是UTC。如果你想在页面里显示中文时间可以把它们改成LANGUAGE_CODE zh-hans TIME_ZONE Asia/ShanghaiUSE_TZ建议保持为True这是 Django 对时区感知的推荐做法。STATIC_URL static/默认就有做静态文件CSS/JS/图片的时候再用得上现在不用动。登录后管理后台创建超级用户那是下一步的事这里先不做先把项目跑起来验证环境没问题。3.4 首次启动 Django 开发服务器终端执行python manage.py runserver看到Starting development server at http://127.0.0.1:8000/就代表成功了。按住Ctrl键点击这个地址VS Code 终端里支持直接点击链接浏览器就会打开 Django 默认的欢迎页一个大火箭表示环境配置正确。如果端口被占用可以指定端口跑python manage.py runserver 8001提示开发服务器默认只监听本机调试足够了。如果后期要拿手机在同一局域网测试加0.0.0.0:8000即可不过那是有一定基础之后的事了。4. 调试验证与第一个自定义页面项目能启动只完成了环境配置的 70%接下来得写一个页面来验证“代码改了能生效”这个环节。不跑一次完整的请求-响应流程你根本不知道 VS Code 和 Django 结合是不是真的顺畅。4.1 配置视图与 URL 路由打开posts/views.py写一个最简单的视图from django.http import HttpResponse def index(request): return HttpResponse(Hello Django! 环境配置成功。)然后在posts文件夹里新建一个urls.pyDjango 不会自动给你这个文件要自己建输入from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]最后在config/urls.py里做一次转发把/路径的请求交给posts应用处理from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(posts.urls)), ]include函数就是把posts应用下的urls.py对应的路由都挂到项目根路径下。保存文件后开发服务器会自动重载不用手动重启。直接刷新浏览器你应该能看到 “Hello Django! 环境配置成功。” 这句话。4.2 VS Code 调试配置开发服务器虽然好用但真正 Debug 的时候还是得靠 VS Code 的调试器比如你在视图里打了breakpoint()或者设置了断点想看看变量值在 runserver 的终端里是没法做到图形化断点调试的。点击 VS Code 左侧的“运行和调试”图标创建一个launch.json文件选择 “Django” 模板VS Code 会自动生成一个配置。默认生成的配置大致长这样{ version: 0.2.0, configurations: [ { name: Django, type: debugpy, request: launch, program: ${workspaceFolder}/manage.py, args: [ runserver ], django: true } ] }切到“运行和调试”面板选择 “Django” 配置点绿色三角启动。之后在views.py的index函数里打个断点访问http://127.0.0.1:8000/VS Code 会停在断点处左侧可以看到变量值、调用栈非常方便。这是开发 Django 项目时最常用的调试图谱化操作建议一上手就养成用它的习惯。4.3 迁移数据库与超级用户页面能访问之后还有一个必做的验证步骤数据库迁移。Django 自带一套 ORM默认使用 SQLite 数据库。执行python manage.py makemigrations python manage.py migratemakemigrations会根据你models.py里的模型生成迁移文件注意要先写了模型才能生成目前我们还没写所以不会生成东西但它会检查所有 App 的状态migrate是把迁移实际同步到数据库中生成 Django 内置的数据表用户表、权限表等。执行完之后db.sqlite3文件会被创建出来这就是你的数据库。顺手再创建一个管理员账号登录后台用python manage.py createsuperuser依次输入用户名、邮箱可不填、密码输入时不显示正常现象完成。密码设置如果太简单Django 会提示你不安全但新手可以暂时忽略后期再改就行。5. 常见问题与排查技巧实录这部分是我个人觉得整篇文章里最值钱的。因为环境和项目创建的逻辑大多数教程都讲了但真正让新手崩溃的是各种莫名其妙的报错。我把这几年在社区里看到的高频问题还有我自己踩过的坑整理成一个速查表你遇到问题直接对号入座。问题现象可能原因解决方案pip不是内部或外部命令Python 未添加 PATH或 venv 未激活重新安装 Python 并勾选 Add to PATH激活 venv 后再执行 pip运行python manage.py runserver提示“No module named django”当前不是在虚拟环境中或解释器选错了venv\Scripts\activate激活VS Code 里 CtrlShiftP 重新选解释器启动服务器后浏览器打不开系统防火墙拦截或端口被占用用runserver 8001换端口检查 Windows 防火墙是否放行 PythonVS Code 终端写中文乱码Windows 控制台默认编码不是 UTF-8PowerShell 执行[Console]::OutputEncoding[Text.Encoding]::UTF8或在系统区域设置里勾选 Beta 版 UTF-8按住Ctrl点击函数名/变量名不跳转Pylance 服务未启动或工作区没有对应的 Python 索引打开输出面板看 Pylance 日志在命令面板执行Python: Clear Cache and Reload Window模板文件里 Django 语法{% for %}等没有高亮未安装 Django 插件或文件类型未识别安装 Django 插件把.html文件右下角语言模式改为Django HTMLmigrate报 “django.db.utils.OperationalError: unable to open database file”项目目录权限不足或者 db.sqlite3 被占用以管理员身份运行 VS Code检查是否用 Excel 等程序打开了 db.sqlite3Django Admin页面样式全丢失静态文件没配置或没收集开发环境运行runserver时通常不会丢如果丢了执行python manage.py collectstatic5.1 主题虚拟环境激活失败怎么办在 Windows 上最常见的是venv已经创建了但激活的时候 PowerShell 报错无法加载文件 ...\venv\Scripts\Activate.ps1因为在此系统上禁止运行脚本。原因很简单Windows 默认 PowerShell 的执行策略是禁运未签名脚本。不是在虚拟环境里是 PowerShell 连正常的.ps1脚本都不给跑。解决方式有两种一种是我上面提到的以管理员身份运行 PowerShell执行Set-ExecutionPolicy RemoteSigned然后输入Y确认另一种就是换种方式——在 VS Code 终端里把 PowerShell 切换到cmd点终端编辑框下拉菜单选 “Select Default Profile”选 “Command Prompt”然后在 cmd 里用venv\Scripts\activate.bat激活。两种方法我更倾向第一种因为改完之后不用老切终端用 PowerShell 操作也方便。5.2 主题解释器选错导致的连锁反应还有一个隐蔽问题虚拟环境激活了终端里也能看到(venv)前缀但 VS Code 右下角显示的 Python 版本还是全局那个。这种情况非常坑因为命令行跑python manage.py runserver用的是虚拟环境的 Python而 VS Code 里的 Python 插件做代码补全和类型检查时用的是全局的 Python两边不一致就会导致编辑器里import django显示红色波浪线提示找不到模块但命令行跑起来完全正常。断点调试时VS Code 启动调试用的解释器和 runserver 不一致也容易出诡异问题。解决办法很简单CtrlShiftP输入 “Python: Select Interpreter”在列表里选择带venv标签的那个。选完之后右下角会显示venv: venv之类的字样编辑器里import django就不会报错了。如果你打开 VS Code 时它没有自动列出 venv有可能是 VS Code 版本太老或者 Python 插件没装好升级重启一般能解决。5.3 主题数据库迁移时出现 “No migrations to apply”有时候python manage.py migrate执行完了但你以为没反应其实这是正常的。这里有一个细节migrate不会每次执行都打印一大堆东西如果没什么变化它可能只输出一行No migrations to apply.我见过有人把这句话当成错误其实它是正常的说明数据库和应用的状态是一致的。真正需要注意的是如果你改了models.py里的模型必须依次执行makemigrations和migrate两个缺一不可。makemigrations不会真的改数据库它只是生成一个“变更记录”migrate才会把变更记录执行到数据库里。新手容易只跑migrate然后奇怪为什么 models 改了但数据库还是老样子。6. 让 VS Code 更好用的一些配置细节项目跑起来了环境也验证了现在可以花几分钟让 VS Code 更贴合你的使用习惯。这一部分不算必需但能极大提升你写 Django 代码的舒适度。6.1 代码片段与自定义快捷键VS Code 的代码片段Snippet功能很强大。Python 插件自带的片段就不少比如你输入def会弹出函数模板输入clas会弹出类模板。Django 插件还会提供dj开头的模板片段比如view、model、urls等。如果你有自己的常用模板可以在首选项 配置用户代码片段里新建一个例如{ Django Model Import: { prefix: djimport, body: [ from django.db import models, from django.urls import reverse, ], description: Django model 文件常用的导入 } }以后输入djimport按 Tab 就会自动补全这两行导入省去手打的麻烦。这些小技巧可能看起来不起眼但积累多了写代码速度会快不少。6.2 工作区设置与格式化工具VS Code 的工作区设置.vscode/settings.json是跟着项目走的如果你把项目共享给别人或者换电脑这份配置也能带上。在项目根目录下按 CtrlShiftP 输入 “Preferences: Open Workspace Settings”追加这些{ python.defaultInterpreterPath: ${workspaceFolder}/venv/Scripts/python.exe, python.formatting.provider: black, editor.formatOnSave: true, [python]: { editor.defaultFormatter: ms-python.python }, python.analysis.typeCheckingMode: basic }formatOnSave保存时自动格式化配合 black 格式化库pip install black代码风格会很统一。typeCheckingMode调成basic能开着类型检查但不会太激进适合当成初级强化课。6.3 模板文件的语言模式如果你写 Django 模板HTML 文件里混着{% %}、{{ }}建议把.html文件的默认语言模式改一下。方法打开一个.html文件右下角找 “HTML”点击后搜索 “Django HTML”选中。之后这个文件会以 Django 模板语法高亮{% block %}、{% extends %}会显示不同的颜色定位标签结构会清晰很多。还有一个小技巧在settings.json里加下面这行能给所有.html文件强制关联到 Django HTMLfiles.associations: { *.html: django-html }这样就不用手动一个一个改了。7. 从零到一的完整流程速查可直接复制为了让你能照着今天的内容快速重建环境我把从零开始的命令整理成一段可以拿来当备忘。# 1. 创建项目目录并用 VS Code 打开 mkdir myblog cd myblog code . # 2. 在 VS Code 终端里创建虚拟环境 python -m venv venv # 3. 激活虚拟环境 venv\Scripts\activate # 4. 安装 Django pip install django # 5. 创建 Django 项目注意末尾的 . django-admin startproject config . # 6. 创建 App python manage.py startapp posts # 7. 在 settings.py 的 INSTALLED_APPS 里注册 posts # 8. 修改 LANGUAGE_CODE/TIME_ZONE # 9. 运行开发服务器 python manage.py runserver # 10. 迁移数据库、创建超级用户 python manage.py makemigrations python manage.py migrate python manage.py createsuperuser再到 VS Code 里做三件事选解释器、装 Python 和 Django 插件、创建 launch.json 调试配置。这一套走完一个能跑、能调试、能做后台管理的 Django 开发环境就算立住了。8. 一些建议和踩坑心得最后分享几个我自己总结的小建议。第一环境搭建时不要急着一口气跑完。每一步想清楚“这一步是为了什么”比如装 Python 是为了有解释器建 venv 是为了隔离依赖装 Django 是为了有框架代码启动 runserver 是为了验证链路通。链条逻辑理解了报错时排查起来也更快。第二当你遇到报错先去读那行英文。很多新手一看到报错就截图往群里丢其实 80% 的报错信息里都写清楚了原因。比如No module named django就是 Python 找不到模块那你肯定知道应该去检查装了没有、装到哪里去了。报错不可怕怕的是不看报错。第三保持 Django 版本与 Python 版本兼容。目前 Django 5.x 要求 Python 3.10 以上如果你还在用 Python 3.8/3.9它会直接报错不让你装。建议直接上 Python 3.10新项目没必要停留在老版本上。第四这个配置好之后后续扩展的空间非常大。比如你可以继续写博客的模型做分页加评论甚至部署到云服务器。很多人在“环境配置”这一步停滞太久其实真正应该多花时间的是理解 Django 的 MTV 架构、ORM 用法、路由和视图的逻辑。根据我自己的实践经验环境配置这事真不是“体力活”它就是你用 Django 之前必须打通的第一关。多花点时间把这关走扎实了后面学习曲线会平滑太多。我见过不少同事和同学环境配好之后当天就写出了第一个能提交表单的页面那种感觉真的很好。你现在跑的每一步都是在为后面更复杂的功能打地基别嫌它枯燥这份耐心以后一定会回报你。 VS Code配置Django开发环境：从虚拟环境到项目创建全流程
作为一名常年跟 Python 打交道的人我太清楚新手在“环境搭建”这一步有多容易劝退了。可能你刚看完 Django 的官方文档兴冲冲地打开终端准备大干一场结果卡在“装完 Python 之后下一步干嘛”、“VS Code 里怎么打开终端”、“为什么 pip 命令提示不是内部或外部命令”这种问题上。今天这篇我就用最贴近实操的方式带你完整走一遍在 VS Code 里配置 Django 环境、创建第一个 Django 项目的全过程。整个过程我会把每一步背后的逻辑、踩过的坑、以及当前社区里最主流的做法都讲清楚保证你跟着做下来不仅能把项目跑起来还能顺手把“虚拟环境”“解释器选择”“调试配置”这些概念搞明白。这篇内容适合谁刚学 Python 不久、想用 Django 写 Web 后端的新手以及想从 PyCharm 转到 VS Code 的开发者。它解决什么问题解决“打开了编辑器却不知道从哪里下手”的尴尬给你一套可以照抄的、在 VS Code 里开发 Django 项目的基础配置流程。1. 项目整体设计与思路拆解先说整体思路。我们在 VS Code 里做 Django 开发本质上要搭建三层结构Python 解释器 → 虚拟环境 → Django 项目。大多数教程只会把命令给你但不会解释为什么要有虚拟环境、为什么要在 VS Code 里手动选解释器。如果你不懂这个后面一旦遇到报错就会整个人懵掉。1.1 为什么选 VS Code 而不是 PyCharmPyCharm 确实是个好工具开箱即用创建 Django 项目的时候界面化操作省心。但它有两个痛点一是专业版收费社区版虽然免费但有很多高级功能比如数据库工具、前端支持用不了二是 IDE 太重启动慢、占内存如果你的电脑配置一般开一个 PyCharm 再开一个浏览器风扇就开始转了。VS Code 的优势是轻量、插件生态丰富而且能通过插件把 Django 开发体验拉到和 IDE 差不多的水平。比如 Python 插件提供智能感知IntelliSense、调试、自动补全Django 插件提供模板语法高亮、快捷创建文件甚至还有数据库前端、REST Client 这类辅助工具。说白了VS Code 是一个高度可扩展的“编辑器骨架”你往它里面加什么功能取决于你装什么插件。这对长期做前后端分离开发的人来说特别舒服——一套编辑器搞定前后端。1.2 虚拟环境为什么是必需品很多新手跳过虚拟环境直接在全局环境里pip install django当时没事等项目多了就爆炸。举个真实例子你项目 A 用的是 Django 3.2项目 B 需要 Django 5.0如果都在全局环境里那么每次切换项目都要先卸载旧版本再装新版本装来装去可能某天就把环境搞坏了连 pip 都崩了。虚拟环境就是给每个项目独立开一个“专属的 Python 环境”互不干扰。项目 A 装了 3.2项目 B 装 5.0井水不犯河水。Python 自带的venv模块就是干这个事的不需要安装额外的东西官方也推荐。在 VS Code 里只要你先创建好虚拟环境然后用 VS Code 打开项目文件夹它通常会自动识别或者你手动选择一下解释器之后的操作全都是基于这个虚拟环境进行的。2. 环境准备Python、VS Code 与虚拟环境初始化在正式开始创建 Django 项目之前有两件事必须做安装 Python、安装 VS Code。别觉得这是废话我在社群里见过太多次因为 Python 没勾选“Add to PATH”导致后面 pip 全挂的案例。2.1 Python 安装与 PATH 问题去 Python 官网下载最新的稳定版建议 3.10 及以上Django 官方支持的版本也是这些。安装时有一个关键选项Add Python to PATH一定要勾上。这一步如果不勾后面你在命令行里敲python就会提示“不是内部或外部命令”本质是系统找不到 python.exe 的位置。装完之后怎么验证打开终端Windows 按Win R输入cmd或者直接用 VS Code 的终端输入python --version正常会输出类似Python 3.12.x。如果提示python不是内部命令那大概率是 PATH 没配好。我不建议新手手动去系统变量里折腾最快的方案是重装 Python然后勾上 PATH 选项省心省力。2.2 创建项目文件夹与虚拟环境假设你要创建一个名为myblog的项目用博客来练手是 Django 初学者最经典的路径。先在D:\dev或者你自己喜欢的目录下创建myblog文件夹然后用 VS Code 打开这个文件夹cd D:\dev mkdir myblog cd myblog code . # 这会在当前目录下打开 VS Code在 VS Code 里打开终端快捷键Ctrl 输入python -m venv venv这条命令的意思是用 Python 的venv模块在当前目录下创建一个虚拟环境环境名叫venv这是约定俗成的名字你也可以叫.venv效果一样。执行完你会发现文件夹里多了一个venv目录里面就是打包过来的 Python 解释器和 pip。注意这个venv目录千万不要删也不要手动去翻里边的文件。然后激活虚拟环境。Windows 系统输入venv\Scripts\activate终端提示符前面会多了一个(venv)说明现在已经在虚拟环境里了。这时候你执行pip install操作都是装在这个独立环境里的不会污染全局。macOS/Linux 系统略有不同用的是source venv/bin/activate但 Windows 用户按我上面来就好。提示如果激活之后pip命令报错先检查一下是不是因为终端当前目录不在项目根目录。另外VS Code 的终端默认会启动 PowerShell有些安全策略可能禁止执行脚本报错内容是无法加载文件 ... 因为在此系统上禁止运行脚本此时以管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned即可解决。2.3 VS Code 安装与必要插件VS Code 官网下载安装包一路 Next 安装。装完后左侧工具栏有一个“扩展”图标四个方格那个图标搜索并安装以下插件PythonMicrosoft 官方出品必装提供代码补全、语法检查、调试、Jupyter 支持等核心功能。Django开源社区维护模板语法高亮、内置代码片段、跳转到视图/模板定义等对 Django 开发体验提升很大。PylanceMicrosoft 官方一般随 Python 插件自动安装提供更强大的类型检查和智能提示。顺便说一个大家都关心的问题VS Code 怎么汉化扩展里搜Chinese (Simplified) (简体中文) Language Pack安装后右下角弹窗选“Change Language and Restart”重启后就变成中文界面了。这是官方插件放心装。安装完插件后必须做的一件事把刚才创建的虚拟环境选为解释器。回到 VS Code按Ctrl Shift P打开命令面板输入 “Python: Select Interpreter”选择venv环境一般会显示venv的路径。这一步是核心选错了后面打开项目的时候 VS Code 用的就不是你的虚拟环境装 Django 全装到全局里去了也会出现“明明装了 Django 但 import 报错”的奇怪问题。3. 创建 Django 项目与核心配置实操环境铺好了接下来就是重头戏创建 Django 项目。这里为了照顾到新手我会把每一个命令的作用、生成的文件结构、以及后续要手动改哪些配置都讲清楚。3.1 安装 Django 并创建项目确保终端里处于激活状态终端前缀有(venv)执行pip install django装的是最新稳定版当前是 5.x。装完之后别急着开始先用pip show django看一眼安装路径确认是装在了 venv 环境里而不是全局环境。这一步虽然不是必须的但能让你心里有个底。然后创建项目。Django 官网用一个mysite项目做例子但你最好取自己的名字。我在这里用myblogdjango-admin startproject config .注意末尾这个点.非常重要。它的意思是“在当前目录下创建项目配置”生成的config文件夹就是你的全局配置目录settings.py、urls.py、wsgi.py、asgi.py 都在这里面。如果忘了加点Django 会再创建一个myblog子目录项目结构就变成嵌套的后续跑起来容易混乱。创建完之后目录结构大概是这样myblog/ ├── venv/ ├── config/ │ ├── __init__.py │ ├── settings.py │ ├── urls.py │ ├── asgi.py │ └── wsgi.py └── manage.pymanage.py是 Django 给项目提供的一个管理工具入口以后运行服务器、迁移数据库、创建 app全都要通过它来执行。3.2 创建 App 并注册到 SettingsDjango 的架构是“项目 应用”模式。项目Project是全局的配置和调度应用App是具体的业务模块比如博客的posts、users、comments。继续在终端执行python manage.py startapp posts执行后会出现一个posts文件夹里面有models.py、views.py、admin.py、migrations/等。现在先不管里面代码第一件事是去config/settings.py里的INSTALLED_APPS列表里把posts注册进去不然后面数据库迁移和 Django 自己提供的后台管理页面都识别不到这个 App。打开config/settings.py找到INSTALLED_APPS在最后一行追加posts,记得带逗号。很多初学者会漏掉这一步结果创建完 app 之后执行迁移被告知 “No installed app with label posts”。3.3 配置语言、时区与静态文件settings.py里还有三个常见的要改的地方LANGUAGE_CODE、TIME_ZONE、STATIC_URL。Django 默认LANGUAGE_CODE是en-us时区是UTC。如果你想在页面里显示中文时间可以把它们改成LANGUAGE_CODE zh-hans TIME_ZONE Asia/ShanghaiUSE_TZ建议保持为True这是 Django 对时区感知的推荐做法。STATIC_URL static/默认就有做静态文件CSS/JS/图片的时候再用得上现在不用动。登录后管理后台创建超级用户那是下一步的事这里先不做先把项目跑起来验证环境没问题。3.4 首次启动 Django 开发服务器终端执行python manage.py runserver看到Starting development server at http://127.0.0.1:8000/就代表成功了。按住Ctrl键点击这个地址VS Code 终端里支持直接点击链接浏览器就会打开 Django 默认的欢迎页一个大火箭表示环境配置正确。如果端口被占用可以指定端口跑python manage.py runserver 8001提示开发服务器默认只监听本机调试足够了。如果后期要拿手机在同一局域网测试加0.0.0.0:8000即可不过那是有一定基础之后的事了。4. 调试验证与第一个自定义页面项目能启动只完成了环境配置的 70%接下来得写一个页面来验证“代码改了能生效”这个环节。不跑一次完整的请求-响应流程你根本不知道 VS Code 和 Django 结合是不是真的顺畅。4.1 配置视图与 URL 路由打开posts/views.py写一个最简单的视图from django.http import HttpResponse def index(request): return HttpResponse(Hello Django! 环境配置成功。)然后在posts文件夹里新建一个urls.pyDjango 不会自动给你这个文件要自己建输入from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]最后在config/urls.py里做一次转发把/路径的请求交给posts应用处理from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(posts.urls)), ]include函数就是把posts应用下的urls.py对应的路由都挂到项目根路径下。保存文件后开发服务器会自动重载不用手动重启。直接刷新浏览器你应该能看到 “Hello Django! 环境配置成功。” 这句话。4.2 VS Code 调试配置开发服务器虽然好用但真正 Debug 的时候还是得靠 VS Code 的调试器比如你在视图里打了breakpoint()或者设置了断点想看看变量值在 runserver 的终端里是没法做到图形化断点调试的。点击 VS Code 左侧的“运行和调试”图标创建一个launch.json文件选择 “Django” 模板VS Code 会自动生成一个配置。默认生成的配置大致长这样{ version: 0.2.0, configurations: [ { name: Django, type: debugpy, request: launch, program: ${workspaceFolder}/manage.py, args: [ runserver ], django: true } ] }切到“运行和调试”面板选择 “Django” 配置点绿色三角启动。之后在views.py的index函数里打个断点访问http://127.0.0.1:8000/VS Code 会停在断点处左侧可以看到变量值、调用栈非常方便。这是开发 Django 项目时最常用的调试图谱化操作建议一上手就养成用它的习惯。4.3 迁移数据库与超级用户页面能访问之后还有一个必做的验证步骤数据库迁移。Django 自带一套 ORM默认使用 SQLite 数据库。执行python manage.py makemigrations python manage.py migratemakemigrations会根据你models.py里的模型生成迁移文件注意要先写了模型才能生成目前我们还没写所以不会生成东西但它会检查所有 App 的状态migrate是把迁移实际同步到数据库中生成 Django 内置的数据表用户表、权限表等。执行完之后db.sqlite3文件会被创建出来这就是你的数据库。顺手再创建一个管理员账号登录后台用python manage.py createsuperuser依次输入用户名、邮箱可不填、密码输入时不显示正常现象完成。密码设置如果太简单Django 会提示你不安全但新手可以暂时忽略后期再改就行。5. 常见问题与排查技巧实录这部分是我个人觉得整篇文章里最值钱的。因为环境和项目创建的逻辑大多数教程都讲了但真正让新手崩溃的是各种莫名其妙的报错。我把这几年在社区里看到的高频问题还有我自己踩过的坑整理成一个速查表你遇到问题直接对号入座。问题现象可能原因解决方案pip不是内部或外部命令Python 未添加 PATH或 venv 未激活重新安装 Python 并勾选 Add to PATH激活 venv 后再执行 pip运行python manage.py runserver提示“No module named django”当前不是在虚拟环境中或解释器选错了venv\Scripts\activate激活VS Code 里 CtrlShiftP 重新选解释器启动服务器后浏览器打不开系统防火墙拦截或端口被占用用runserver 8001换端口检查 Windows 防火墙是否放行 PythonVS Code 终端写中文乱码Windows 控制台默认编码不是 UTF-8PowerShell 执行[Console]::OutputEncoding[Text.Encoding]::UTF8或在系统区域设置里勾选 Beta 版 UTF-8按住Ctrl点击函数名/变量名不跳转Pylance 服务未启动或工作区没有对应的 Python 索引打开输出面板看 Pylance 日志在命令面板执行Python: Clear Cache and Reload Window模板文件里 Django 语法{% for %}等没有高亮未安装 Django 插件或文件类型未识别安装 Django 插件把.html文件右下角语言模式改为Django HTMLmigrate报 “django.db.utils.OperationalError: unable to open database file”项目目录权限不足或者 db.sqlite3 被占用以管理员身份运行 VS Code检查是否用 Excel 等程序打开了 db.sqlite3Django Admin页面样式全丢失静态文件没配置或没收集开发环境运行runserver时通常不会丢如果丢了执行python manage.py collectstatic5.1 主题虚拟环境激活失败怎么办在 Windows 上最常见的是venv已经创建了但激活的时候 PowerShell 报错无法加载文件 ...\venv\Scripts\Activate.ps1因为在此系统上禁止运行脚本。原因很简单Windows 默认 PowerShell 的执行策略是禁运未签名脚本。不是在虚拟环境里是 PowerShell 连正常的.ps1脚本都不给跑。解决方式有两种一种是我上面提到的以管理员身份运行 PowerShell执行Set-ExecutionPolicy RemoteSigned然后输入Y确认另一种就是换种方式——在 VS Code 终端里把 PowerShell 切换到cmd点终端编辑框下拉菜单选 “Select Default Profile”选 “Command Prompt”然后在 cmd 里用venv\Scripts\activate.bat激活。两种方法我更倾向第一种因为改完之后不用老切终端用 PowerShell 操作也方便。5.2 主题解释器选错导致的连锁反应还有一个隐蔽问题虚拟环境激活了终端里也能看到(venv)前缀但 VS Code 右下角显示的 Python 版本还是全局那个。这种情况非常坑因为命令行跑python manage.py runserver用的是虚拟环境的 Python而 VS Code 里的 Python 插件做代码补全和类型检查时用的是全局的 Python两边不一致就会导致编辑器里import django显示红色波浪线提示找不到模块但命令行跑起来完全正常。断点调试时VS Code 启动调试用的解释器和 runserver 不一致也容易出诡异问题。解决办法很简单CtrlShiftP输入 “Python: Select Interpreter”在列表里选择带venv标签的那个。选完之后右下角会显示venv: venv之类的字样编辑器里import django就不会报错了。如果你打开 VS Code 时它没有自动列出 venv有可能是 VS Code 版本太老或者 Python 插件没装好升级重启一般能解决。5.3 主题数据库迁移时出现 “No migrations to apply”有时候python manage.py migrate执行完了但你以为没反应其实这是正常的。这里有一个细节migrate不会每次执行都打印一大堆东西如果没什么变化它可能只输出一行No migrations to apply.我见过有人把这句话当成错误其实它是正常的说明数据库和应用的状态是一致的。真正需要注意的是如果你改了models.py里的模型必须依次执行makemigrations和migrate两个缺一不可。makemigrations不会真的改数据库它只是生成一个“变更记录”migrate才会把变更记录执行到数据库里。新手容易只跑migrate然后奇怪为什么 models 改了但数据库还是老样子。6. 让 VS Code 更好用的一些配置细节项目跑起来了环境也验证了现在可以花几分钟让 VS Code 更贴合你的使用习惯。这一部分不算必需但能极大提升你写 Django 代码的舒适度。6.1 代码片段与自定义快捷键VS Code 的代码片段Snippet功能很强大。Python 插件自带的片段就不少比如你输入def会弹出函数模板输入clas会弹出类模板。Django 插件还会提供dj开头的模板片段比如view、model、urls等。如果你有自己的常用模板可以在首选项 配置用户代码片段里新建一个例如{ Django Model Import: { prefix: djimport, body: [ from django.db import models, from django.urls import reverse, ], description: Django model 文件常用的导入 } }以后输入djimport按 Tab 就会自动补全这两行导入省去手打的麻烦。这些小技巧可能看起来不起眼但积累多了写代码速度会快不少。6.2 工作区设置与格式化工具VS Code 的工作区设置.vscode/settings.json是跟着项目走的如果你把项目共享给别人或者换电脑这份配置也能带上。在项目根目录下按 CtrlShiftP 输入 “Preferences: Open Workspace Settings”追加这些{ python.defaultInterpreterPath: ${workspaceFolder}/venv/Scripts/python.exe, python.formatting.provider: black, editor.formatOnSave: true, [python]: { editor.defaultFormatter: ms-python.python }, python.analysis.typeCheckingMode: basic }formatOnSave保存时自动格式化配合 black 格式化库pip install black代码风格会很统一。typeCheckingMode调成basic能开着类型检查但不会太激进适合当成初级强化课。6.3 模板文件的语言模式如果你写 Django 模板HTML 文件里混着{% %}、{{ }}建议把.html文件的默认语言模式改一下。方法打开一个.html文件右下角找 “HTML”点击后搜索 “Django HTML”选中。之后这个文件会以 Django 模板语法高亮{% block %}、{% extends %}会显示不同的颜色定位标签结构会清晰很多。还有一个小技巧在settings.json里加下面这行能给所有.html文件强制关联到 Django HTMLfiles.associations: { *.html: django-html }这样就不用手动一个一个改了。7. 从零到一的完整流程速查可直接复制为了让你能照着今天的内容快速重建环境我把从零开始的命令整理成一段可以拿来当备忘。# 1. 创建项目目录并用 VS Code 打开 mkdir myblog cd myblog code . # 2. 在 VS Code 终端里创建虚拟环境 python -m venv venv # 3. 激活虚拟环境 venv\Scripts\activate # 4. 安装 Django pip install django # 5. 创建 Django 项目注意末尾的 . django-admin startproject config . # 6. 创建 App python manage.py startapp posts # 7. 在 settings.py 的 INSTALLED_APPS 里注册 posts # 8. 修改 LANGUAGE_CODE/TIME_ZONE # 9. 运行开发服务器 python manage.py runserver # 10. 迁移数据库、创建超级用户 python manage.py makemigrations python manage.py migrate python manage.py createsuperuser再到 VS Code 里做三件事选解释器、装 Python 和 Django 插件、创建 launch.json 调试配置。这一套走完一个能跑、能调试、能做后台管理的 Django 开发环境就算立住了。8. 一些建议和踩坑心得最后分享几个我自己总结的小建议。第一环境搭建时不要急着一口气跑完。每一步想清楚“这一步是为了什么”比如装 Python 是为了有解释器建 venv 是为了隔离依赖装 Django 是为了有框架代码启动 runserver 是为了验证链路通。链条逻辑理解了报错时排查起来也更快。第二当你遇到报错先去读那行英文。很多新手一看到报错就截图往群里丢其实 80% 的报错信息里都写清楚了原因。比如No module named django就是 Python 找不到模块那你肯定知道应该去检查装了没有、装到哪里去了。报错不可怕怕的是不看报错。第三保持 Django 版本与 Python 版本兼容。目前 Django 5.x 要求 Python 3.10 以上如果你还在用 Python 3.8/3.9它会直接报错不让你装。建议直接上 Python 3.10新项目没必要停留在老版本上。第四这个配置好之后后续扩展的空间非常大。比如你可以继续写博客的模型做分页加评论甚至部署到云服务器。很多人在“环境配置”这一步停滞太久其实真正应该多花时间的是理解 Django 的 MTV 架构、ORM 用法、路由和视图的逻辑。根据我自己的实践经验环境配置这事真不是“体力活”它就是你用 Django 之前必须打通的第一关。多花点时间把这关走扎实了后面学习曲线会平滑太多。我见过不少同事和同学环境配好之后当天就写出了第一个能提交表单的页面那种感觉真的很好。你现在跑的每一步都是在为后面更复杂的功能打地基别嫌它枯燥这份耐心以后一定会回报你。