Django快速入门(1)Django安装与测试这次我们来看一个 Web 开发绕不开的框架Django。不管你是刚开始学 Python 后端还是想把一个想法快速落地成网站Django 几乎都是最合适的第一选择。它自带 Admin 后台、ORM 数据库操作、用户认证、路由系统很多东西不用自己造轮子。这篇文章会带你把 Django 从安装到项目创建、再到开发服务器启动测试完整跑通一遍。动手之前先说清楚Django 的安装门槛很低普通电脑、Windows / macOS / Linux 都能装不需要独立显卡也不需要昂贵的服务器本地开发环境足够跑起来。整篇内容我会按“环境准备 — 安装 — 创建项目 — 启动测试 — 排查问题”的顺序来写跟着操作一遍你就能有一个可以继续往后学的 Django 基础项目。很多人在学习 Django 时遇到的首要问题不是框架本身难而是环境没配好、依赖没装上、服务器起不来。这篇文章就是来解决这几个痛点的。我会把 Python 虚拟环境、pip 安装、django-admin 创建项目、manage.py 启动服务这些步骤逐一拆开每一步都给出可复制的命令并解释运行结果和常见报错。文章末尾还会给出一个高频问题排查表方便你在实际部署时快速定位问题。1. 核心能力速览能力项说明项目类型Python Web 后端框架核心定位快速构建数据库驱动的 Web 应用安装方式pip 安装命令pip install django创建项目django-admin startproject project_name创建应用python manage.py startapp app_name启动方式python manage.py runserver自带功能Admin 后台、ORM、认证、表单、路由、模板引擎数据库支持SQLite默认、MySQL、PostgreSQL、Oracle硬件门槛无独立显卡要求2 核 CPU / 4G 内存即可流畅开发支持平台Windows、macOS、Linux、WSL接口能力原生视图函数 / DRFDjango REST Framework扩展适合场景Web 应用、API 服务、内容管理后台、自动化运维平台Django 不是一个“能跑就行”的玩具框架它适合从个人项目到企业级系统的多种场景。它的设计理念是“batteries included”——把开发 Web 应用最常用到的组件都集成好让你专注于业务逻辑而不是反复造轮子。2. 适用场景与使用边界Django 适合哪类场景我可以直接说结论任何一个需要数据库、需要用户管理、需要后台管理界面的 Web 应用Django 都非常合适。比如博客系统、企业官网、内部管理系统、数据可视化平台、接口服务后端都是它的典型应用场景。Django 的自带 Admin 后台对开发效率的提升非常明显。你只要定义好数据模型后台管理页面就能自动生成对内部管理系统来说这几乎是“白嫖”了一个管理界面。再加上自带的 ORM你可以用 Python 代码操作数据库而不用手写大量 SQL。用户认证、密码加密、登录会话这些东西 Django 也默认帮你处理好了安全性有保障。但 Django 也有一些边界需要提前知道。第一开发服务器runserver只适合本地开发不适合直接部署到生产环境。它没有经过高并发优化也没有自动处理静态文件的性能方案。正式上线时需要用 Gunicorn / uWSGI 配合 Nginx 部署。第二Django 偏向“全家桶”模式如果你只是想做一个小型 API 服务Flask 或 FastAPI 会更轻量。Django 的学习曲线相对陡一些但换来的是更完整的功能集。第三使用 Django 开发 Web 应用时涉及用户数据、数据库内容、内部接口时必须注意数据隐私和访问控制。开发阶段就要明确哪些数据不能公开、哪些接口需要登录鉴权避免把敏感信息暴露出去。在自己本机学习测试没问题但一旦部署到公网服务器就要认真配置安全设置。如果你是在企业内部做工具平台还要注意授权边界只能使用已授权的数据源和素材不要将未公开的数据随意接入自己的 Web 应用中。这一点在做技术验证时尤其重要。3. 环境准备与前置条件开始安装 Django 之前先把基础环境检查一遍。3.1 操作系统要求Django 是纯 Python 框架跨平台支持做得很好Windows 10 / 11macOS 10.15 及以上Ubuntu / CentOS / Debian 等主流 Linux 发行版WSLWindows Subsystem for Linux你不需要因为 Django 而去重装系统。我见过很多人在 Windows 上直接用命令行开发 Django 项目完全没问题。3.2 Python 版本检查Django 对 Python 版本有要求各版本的兼容范围不同。更稳妥的判断是当前主流 Django LTS 版本都要求 Python 3.10 以上建议安装 Python 3.10 到 3.12 之间的版本。先打开终端检查 Python 是否已经安装python --version如果你安装了 Python 3可能是python3命令python3 --version输出类似Python 3.11.5就说明 Python 已就绪。如果提示命令不存在需要先到 Python 官网下载安装包安装时勾选“Add Python to PATH”。3.3 pip 包管理器pip 是 Python 的包管理器安装 Django 要用它。检查 pip 是否可用pip --version或者pip3 --version如果 pip 版本较旧可以先升级一下python -m pip install --upgrade pip3.4 虚拟环境强烈建议这里要认真说不要全局安装 Django一定要用虚拟环境。虚拟环境的作用是隔离不同项目的依赖避免项目 A 需要 Django 4.2、项目 B 需要 Django 5.0 时互相冲突。创建虚拟环境# 在项目根目录下执行 python -m venv venv激活虚拟环境WindowsCMDvenv\Scripts\activateWindowsPowerShellvenv\Scripts\Activate.ps1如果 PowerShell 提示执行策略不允许运行脚本可以用管理员身份执行Set-ExecutionPolicy RemoteSignedmacOS / Linuxsource venv/bin/activate激活成功后终端命令行前面会出现(venv)标识说明当前已在虚拟环境中。3.5 数据库选择Django 默认使用 SQLite零配置文件适合学习和快速开发。SQLite 的数据存储在本地一个文件里不需要单独安装数据库服务。如果你想用 MySQL 或 PostgreSQL也可以后续再配置连接不影响当前安装测试。4. 安装部署与启动方式4.1 pip 安装 Django激活虚拟环境后执行pip install django如果你希望安装指定版本比如当前 LTS 版本pip install django4.2.*说明具体可用版本以 PyPI 上的发布情况为准。安装完成后检查版本python -m django --version能看到4.2.x或5.x这类版本号说明安装成功。4.2 创建 Django 项目Django 安装好之后会在虚拟环境中生成django-admin命令。用它来创建项目django-admin startproject myproject这条命令会生成一个名为myproject的目录目录结构如下myproject/ manage.py myproject/ __init__.py settings.py urls.py asgi.py wsgi.py各文件的作用文件作用manage.py项目管理入口启动服务器、执行迁移、创建应用都用它settings.py项目配置文件数据库、应用注册、语言时区都在这里urls.pyURL 路由配置决定访问哪个地址进入哪个视图asgi.py/wsgi.py部署时使用的服务入口文件__init__.py标识目录为 Python 包4.3 创建应用AppDjango 项目由多个“应用”组成。一个项目好比一个站点一个应用就是站点里的一个功能模块比如“用户模块”“文章模块”“订单模块”。进入项目目录并创建应用cd myproject python manage.py startapp blog这样你就创建了一个名为blog的应用。创建完成后需要把应用注册到settings.py的INSTALLED_APPS中。用编辑器打开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, # 新增应用 ]4.4 数据库迁移Django 自带的用户认证、Admin 后台等功能需要数据表第一次使用时要执行迁移命令python manage.py migrate执行后你会看到类似输出Operations to perform: Apply all migrations: admin, auth, contenttypes, sessions Running migrations: Applying contenttypes.0001_initial... OK Applying auth.0001_initial... OK Applying admin.0001_initial... OK Applying sessions.0001_initial... OK看到OK就说明数据库初始化完成默认会在项目目录下生成一个db.sqlite3文件。4.5 启动开发服务器安装测试的核心目标就是把开发服务器跑起来。执行python manage.py runserver默认监听8000端口启动成功后会看到Watching for file changes with StatReloader Performing system checks... System check identified no issues (0 silenced). May 20, 2025 - 10:00:00 Django version 5.0, using settings myproject.settings Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.然后在浏览器中访问http://127.0.0.1:8000/如果看到 Django 的默认欢迎页火箭图标说明整个安装到启动流程已经跑通。如果你需要让局域网内其他设备访问可以指定 IPpython manage.py runserver 0.0.0.0:8000如果 8000 端口被占用可以换一个端口python manage.py runserver 80805. 功能测试与效果验证Django 安装完成、服务器能启动这只是第一步。接下来我们要验证框架的“主链路”是否正常URL 路由 → 视图函数 → HTTP 响应。5.1 编写第一个视图函数在blog应用下的views.py中写一个最简单的视图from django.http import HttpResponse def index(request): return HttpResponse(Hello, Django!)5.2 配置 URL 路由Django 的路由入口在myproject/urls.py需要把blog应用的路由引入进来。先创建blog/urls.pyfrom django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]然后在myproject/urls.py中引入from django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]5.3 重启服务器并验证响应修改代码后开发服务器会自动重载。回到浏览器访问http://127.0.0.1:8000/页面上会显示Hello, Django!。这个测试的意义在于它验证了“请求 → 路由匹配 → 视图处理 → 响应返回”这一整条 Web 链路是通的。以后写任何功能都是在这个基础上扩展。5.4 测试 Admin 后台Django 自带 Admin 后台这是它的招牌功能之一。先创建超级管理员账号python manage.py createsuperuser按照提示输入用户名、邮箱可留空、密码然后访问http://127.0.0.1:8000/admin/用刚才创建的账号登录就能进入后台管理界面。Admin 后台默认有“用户”“组”的管理功能。如果你在blog/models.py中定义了自定义模型还可以通过注册让模型也出现在后台里实现数据管理。5.5 测试 url 路径的“可寻址性”Django 自带一个 URL 检查工具能帮你验证所有路由有没有冲突python manage.py check输出System check identified no issues.说明路由配置正常。6. settings.py 核心配置与 manage.py 常用命令6.1 settings.py 中值得关注的配置项settings.py是 Django 项目的中枢配置文件。这里说明几个最常用、最常见的配置项开发阶段建议把注意力放在这几个上面配置项作用开发建议INSTALLED_APPS注册应用新建的应用必须加进来DATABASES数据库连接配置默认 SQLite切换 MySQL 时改这里LANGUAGE_CODE语言设置设为zh-hans启用中文后台TIME_ZONE时区设置设为Asia/ShanghaiSTATIC_URL静态文件 URL 前缀默认/static/ALLOWED_HOSTS允许访问的主机名部署时必填开发时可为空设置语言和时区LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai修改后重启服务器Admin 后台会变成中文界面。6.2 manage.py 常用命令速查命令作用python manage.py runserver启动开发服务器python manage.py startapp app_name创建新应用python manage.py migrate执行数据库迁移python manage.py makemigrations根据模型变更生成迁移文件python manage.py createsuperuser创建管理员账号python manage.py check检查项目配置是否有问题python manage.py collectstatic收集静态文件部署时使用python manage.py shell进入 Django 交互式 Python 环境shell命令非常实用你可以在里面直接操作 ORM 和数据模型调试数据逻辑比写测试脚本快得多。6.3 用 ORM 做一次数据读写验证在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然后执行迁移python manage.py makemigrations blog python manage.py migrate再进入交互式环境验证数据读写python manage.py shellfrom blog.models import Article # 写入一条数据 article Article.objects.create(titleDjango 入门, content第一篇文章) print(article.id) # 查询数据 articles Article.objects.all() for a in articles: print(a.id, a.title)能打印出刚写入的数据说明 ORM 链路完全正常。这样以后操作数据库就不用直接写 SQL而是通过 Python 对象来完成。7. 资源占用与性能观察开发阶段你会经常用runserver启动服务。这个服务器是 Django 自带的轻量级服务器有几个特点需要了解。7.1 开发服务器的资源占用runserver默认开启自动重载Auto Reload代码文件变化时会自动重启。它还会启动一个 StatReloader 进程来监听文件变化。这意味着普通开发场景下CPU 占用很低几乎可以忽略。内存占用通常在 100MB 到 300MB 之间具体数值取决于项目规模和已加载的模块。如果本机运行多个服务比如数据库、Redis、Node 等注意观察整体内存情况。想查看实际占用Windows 打开任务管理器找到python.exe进程查看内存。macOS / Linux 执行top或ps aux | grep python。7.2 开发服务器 vs 生产服务器runserver是单进程服务器不能处理高并发请求也不推荐在生产环境使用。生产环境部署 Django 的常见方案Nginx → Gunicorn → DjangoGunicorn 是多进程的 WSGI 服务器可以配置并发数。启动方式类似gunicorn myproject.wsgi:application --bind 0.0.0.0:8000 --workers 3需要注意的是学习阶段不要纠结性能调优先把功能跑通。性能问题通常发生在项目有真实用户访问之后。7.3 如何观察请求日志和性能runserver启动后每次请求都会在终端打印日志[20/May/2025 10:00:00] GET / HTTP/1.1 200 27日志里的200表示请求成功404表示地址未找到500表示服务器内部错误。开发时多留意这些状态码能帮你快速定位问题。另外Django 自带的django-debug-toolbar是查看 SQL 查询次数和页面性能的利器安装后可以在浏览器侧边栏看到每次请求执行了哪些 SQL、用了多长时间。pip install django-debug-toolbar8. 常见问题与排查方法下面是 Django 安装和启动阶段最常遇到的问题我按“问题现象 — 可能原因 — 排查方式 — 解决方案”的顺序整理成表格方便直接对照。问题现象可能原因排查方式解决方案pip提示无法安装 Django虚拟环境未激活或 pip 源不稳定检查命令行是否有(venv)标识激活虚拟环境可切换国内镜像源执行django-admin提示命令不存在当前不在虚拟环境中或未安装 Django执行pip list查看是否有 Django安装 Django 并激活虚拟环境python manage.py runserver提示ModuleNotFoundError: No module named djangoPython 解释器与虚拟环境不一致which python/where python查看路径重新激活虚拟环境确保使用虚拟环境的 Python浏览器访问8000端口打不开服务器未启动或端口被占用看终端是否显示Starting development server先启动服务器端口被占用则换端口页面提示DisallowedHostALLOWED_HOSTS未配置查看错误页显示的 Host 信息在settings.py的ALLOWED_HOSTS中加入域名或 IP修改代码后页面不刷新服务器未开启自动重载看终端是否有Watching for file changes手动重启服务器或检查代码语法错误执行migrate报错数据库文件损坏或路径不正确查看错误堆栈中的数据库路径删除问题数据库文件重新迁移或检查数据库配置PowerShell 无法激活虚拟环境执行策略限制查看错误提示是否涉及ExecutionPolicy以管理员执行Set-ExecutionPolicy RemoteSigned服务器启动后内存占用持续增长开启了多个并行进程使用任务管理器查看 Python 进程数量杀掉多余进程保留一个开发服务器即可python manage.py shell无法导入自定义应用应用未注册到INSTALLED_APPS查看settings.py中是否有该应用在INSTALLED_APPS中注册应用除了表格里的问题还有两个值得注意的点。一个是终端编码问题。在 Windows CMD 中如果遇到中文乱码可以执行chcp 65001另一个是依赖版本冲突。如果你同时在用多个 Python 项目建议严格使用虚拟环境不要把 Django 装到全局环境。全局环境下安装的包版本相互影响排查起来非常痛苦。9. 最佳实践与使用建议经过前面的安装和测试你的 Django 基础环境已经搭好了。接下来这些工程化习惯建议从第一天就养成。9.1 项目目录与虚拟环境分离不要执行python -m venv venv把虚拟环境放在项目内部吗从隔离角度看没问题但如果后期使用 Docker 部署或者用 CI/CD 流水线虚拟环境目录在项目内部会增加镜像大小和部署复杂度。更推荐的做法是代码仓库里不包含 venv 目录部署时在服务器上重新创建虚拟环境。这时用requirements.txt管理依赖pip freeze requirements.txt其他环境安装依赖pip install -r requirements.txt9.2 保留一套最小可运行配置刚学 Django 时不要急着加很多第三方库。先保证“Django 原生全家桶”能跑通再逐步引入 DRF、django-cors-headers、django-environ 等扩展。最小可运行配置很重要它让你在出现问题时能最快判断是框架本身的问题还是第三方库的问题。9.3 开发时开启 Debug部署前一定关闭settings.py中的DEBUG True便于开发时查看错误页面。但部署到公网时必须改为DEBUG False ALLOWED_HOSTS [your-domain.com]如果DEBUG False时页面还是一堆报错信息确认是不是ALLOWED_HOSTS没有包含正确的域名。9.4 数据备份与合规使用Django 项目的核心资产是数据库。开发阶段就要养成备份意识# SQLite 备份直接复制文件 cp db.sqlite3 db.sqlite3.bak # 使用 dumpdata 导出 JSON python manage.py dumpdata data.json另外在开发涉及用户信息、上传文件、日志记录的功能时要明确权限和数据边界。不要把用户密码明文存储Django 自带的用户系统已经做了密码哈希直接用它的User模型不要自己造轮子。涉及第三方素材、版权内容、人脸或声音数据的功能必须确认来源合法、使用已授权并在项目中留下授权记录。9.5 日志习惯不要只在终端看输出。给项目配置日志文件会让你排查线上问题时省很多时间。Django 的LOGGING配置支持文件输出一个最简单的方式是在settings.py中增加目录配置并用文件方式记录import os LOG_DIR os.path.join(BASE_DIR, logs) if not os.path.exists(LOG_DIR): os.makedirs(LOG_DIR) LOGGING { version: 1, disable_existing_loggers: False, handlers: { file: { level: INFO, class: logging.FileHandler, filename: os.path.join(LOG_DIR, django.log), }, }, loggers: { django: { handlers: [file], level: INFO, propagate: True, }, }, }10. 总结与下一步Django 安装与测试的完整流程到这里就走通了。整套过程可以概括成一条主线Python 虚拟环境 → pip 安装 Django → django-admin 创建项目 → manage.py 启动开发服务器 → 浏览器访问默认页 → 注册应用 → 配置路由 → 编写视图 → 验证数据链路。这条主线做完你已经具备继续深入学习 Django 的基础。这篇文章里最值得先动手验证的三个功能一是runserver开发服务器能正常启动并访问默认页二是自己写一个视图函数并通过 URL 路由访问到它三是 Admin 后台能登录并使用。这三个功能全部跑通说明你的 Django 环境没有根本性问题可以放心往后学模型、模板、表单和 DRF 接口开发。最容易踩的坑主要在环境层面没有激活虚拟环境导致 Django 命令找不到、Python 解释器选错导致模块导入失败、端口被占用导致服务器起不来。这些问题在 Windows、macOS、Linux 上都可能出现排查思路一致先看终端错误信息再检查虚拟环境是否激活最后确认端口和配置文件。接下来的学习方向建议按这个顺序模型Model与 ORM → 模板Template与页面渲染 → 表单Form与数据验证 → Admin 后台自定义 → Django REST Framework 接口开发。每学一个模块就在你当前项目里实际写一遍代码不要只看文档。Django 的学习曲线在 Web 框架里不算平缓但只要你把环境安装、项目结构、请求响应链路这三点理解透后续所有功能都是在这条主链上不断添加新节点。建议把本文收藏备用。下次遇到环境问题直接翻到“常见问题与排查方法”那一节对照处理。