如果你正打算学习 Django或者已经在网上零零散散看过一些教程那么你很可能遇到过下面这些情况跟着教程敲完pip install django结果一运行django-admin就提示“不是内部或外部命令”明明下载了最新版 Python却因为没装 pip 导致依赖装不上项目创建成功了访问127.0.0.1:8000却一直转圈打不开页面。这些问题的根源通常不是 Django 本身有多难而是安装和测试这条“进门第一步”没有走扎实。很多人学 Django 时会直接跳过安装细节直奔路由、模型、视图去抄代码。这种做法的风险在于一旦本地环境与教程环境不一致你会同时面对“环境问题”和“代码问题”根本分不清该从哪里排查。作为一门实战性极强的 Web 框架Django 的学习路径应该是“先跑通、再理解、后深入”。而“跑通”的第一步就是安装、创建项目、启动开发服务器、跑一次测试。这正是这篇文章要帮你解决的问题。这篇文章会带着你从零开始完成 Django 的安装与测试。整个流程会覆盖环境准备、虚拟环境、安装命令、创建项目、启动服务、写一个最小测试用例、以及常见报错的排查思路。文章末尾还会给出一套适合新手和团队协作的工程建议。读完以后你可以把本文当作一份“安装排错清单”收藏使用后续每次换电脑或换项目都可以按同样的步骤复现环境。1. 这篇文章真正要解决的问题先聊一个比较现实的痛点Django 的安装和测试看起来只是两行命令的事但实际执行时却存在不少隐性门槛。第一层门槛是环境差异。Django 运行在 Python 之上而 Python 的安装方式五花八门官方安装包、Anaconda、系统自带的 Python、包管理器安装的 Python……不同来源的 Python 版本、pip 指向、命令行环境都不一样。如果你电脑上同时存在多个 Python 版本python和pip指向的可能是不同的解释器这时候安装的 Django 并不会自动出现在你期望的那个环境里。第二层门槛是依赖管理。Django 是一个非常完整的框架它的依赖相对保守但如果你直接用系统级 Python 安装各种包很容易把环境弄乱今天装一个包明天升级另一个包最后发现某个项目跑不起来了。这种“依赖地狱”在 Web 开发里非常常见。解决方式就是使用虚拟环境项目之间互不干扰。第三层门槛是“安装成功”和“项目可运行”之间还隔着几步。很多人以为pip install django跑完就算成功其实安装完成只是第一步。你还需要创建项目、创建应用、启动开发服务器甚至跑一个测试用例来证明链路是通的。只有这些步骤全部走通Django 才真正能用起来。先说判断Django 的安装与测试并没有想象中的那么简单但也并不复杂。它的关键点在于理解“Python 环境”和“Django 项目”之间的关系。只要环境隔离做好了后面的开发会顺畅很多。这篇文章适合三类读者刚入门 Django 的新手、需要在本地搭建 Django 开发环境的开发者、以及准备写自动化测试但还不熟悉 Django 测试框架的同学。2. Django 的核心概念与适用场景在开始安装之前有必要先搞清楚你装的到底是什么以及它适合做什么。2.1 Django 是什么Django 是一个基于 Python 的高层 Web 框架官方有一句很经典的口号The web framework for perfectionists with deadlines。翻译过来就是“为追求完美的开发者准备的、带截止日期的 Web 框架”。这句话其实点出了 Django 的两个特性一是设计理念上追求规范和完整二是它的目标之一是让开发者更快完成任务。Django 采用 MTV 架构也就是 Model-Template-View它和传统 MVC 有点类似但职责划分略有不同。Model 负责数据层Template 负责页面表现层View 负责业务逻辑层。这种分层让代码组织变得清晰但也意味着初学者需要理解一定的抽象概念。2.2 Django 内置了什么为什么说 Django 是“全家桶”式框架因为它把网站开发中很多高频需求都内置了ORM对象关系映射可以用 Python 代码操作数据库不必直接写 SQL。Admin 后台自动生成数据管理后台只需少量配置。模板引擎支持继承、过滤、循环等逻辑方便渲染 HTML。表单系统负责表单校验和渲染。认证系统内置用户、登录、权限、会话机制。中间件机制在请求和响应之间插入处理逻辑。自动化测试框架基于 Python 的 unittest可以编写和运行测试用例。这一点是 Django 和 Flask、FastAPI 这类轻量框架的主要区别。Flask 只提供核心 Web 能力其余要靠扩展Django 则直接给你一套完整的开发体系。对初学者来说Django 的学习曲线更陡一些但一旦掌握了它能帮你减少很多选型和技术组合的成本。2.3 适合什么场景从实际项目来看Django 在很多领域都有稳定应用内容管理系统CMS官方就有 Django CMS 方案。电商平台ORM 和 Admin 对商品、订单、用户管理非常友好。数据可视化平台可以和 Pandas、Celery 等数据工具协同。企业内部系统需求通常是增删改查、权限管理、报表展示Django 开发效率很高。快速原型产品因为内置功能多团队可以快速做出可演示的版本。如果你要做的是简单的 API 接口服务FastAPI 或 Flask 可能更轻但如果是一个包含后台管理、用户认证、数据库表和页面渲染的完整 Web 应用Django 的优势非常明显。2.4 新手最容易误解什么一个常见误解是Django 就是 MVC所以必须先学会数据库才能用。其实 Django 的 ORM 层已经帮你屏蔽了很多 SQL 细节你只需要定义好模型类Django 会负责建表和查询。另一个误解是Django 只适合大项目不适合小项目。这个说法不完全准确。Django 确实内置了很多功能但对于中小型项目你可以只用其中一部分能力并不需要全部启用。还有一个容易混淆的概念是“创建项目”和“创建应用”。Django 项目是你整个服务的入口包含全局配置和 URL 路由而应用是项目下负责具体业务模块的代码包。一个项目可以包含多个应用。例如一个博客项目下面可以有blog、comments、users等应用。这个关系一定要在动手前理解否则后续创建各种文件和目录时容易迷失。3. 环境准备与前置条件安装 Django 之前我们先把环境准备好。环境准备的目标是形成一套干净的、可复现的开发环境。这里会涉及操作系统、Python 版本、虚拟环境工具和 pip 几个概念。3.1 操作系统与终端Django 官方支持 Windows、macOS 和主流 Linux 发行版。不同操作系统在命令行操作上略有差异但核心逻辑是一样的。本文示例命令以 Windows 为主同时会标注 macOS/Linux 对应的差异。如果你使用的是 macOS 或 Linux操作逻辑完全一致只是把激活虚拟环境的命令换成 source 方式。3.2 Python 版本选择Django 对 Python 版本有明确要求。目前 Django 稳定版本要求 Python 3.8 及以上。因为版本更新较快这里不写死具体版本号建议你安装尽量新的 Python 3 稳定版本。注意Django 不支持 Python 2还在用 Python 2 的机器需要先升级 Python。检查 Python 是否安装python --version如果是 Windows 且命令提示符输入python --version没有反应可以尝试py --version这是因为 Windows 上有时会通过py启动器来调用 Python。如果两条命令都不识别说明 Python 还没有正确安装需要先安装 Python 并勾选“Add Python to PATH”。3.3 pip 与依赖管理pip 是 Python 官方的包管理工具。新版 Python 安装包大多自带 pip。检查 pip 是否可用pip --version如果提示找不到 pip可以用 Python 的模块方式执行python -m pip --version这里需要理解一个细节pip命令有时候可能指向的是系统级环境而python -m pip一定指向当前python解释器对应的 pip。所以当你的系统存在多个 Python 版本时建议统一使用python -m pip来保证安装目标与解释器一致。3.4 虚拟环境为什么必须用虚拟环境virtual environment是 Python 项目隔离依赖的通用方案。它的核心作用是为每个项目创建一个独立的 Python 运行环境项目 A 装 Django 3.x项目 B 装 Django 5.x两者互不影响。Django 官方推荐的虚拟环境方式就是 Python 自带的venv模块。它不需要额外安装创建命令也简单。后面所有内容都会基于虚拟环境展开这也是目前最稳妥、最适合新手的方式。4. Django 安装与项目创建这一节是核心操作区。所有命令我都会提供可复制的完整版本并解释每一步的作用。建议你一次性顺序执行不要跳跃。4.1 创建并激活虚拟环境先在某个目录下创建一个项目文件夹例如django_startmkdir django_start cd django_start然后创建虚拟环境。Windows、macOS、Linux 命令基本一致python -m venv venv这条命令会在当前目录下生成一个venv文件夹里面装着一个独立的 Python 环境。激活方式Windowsvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活成功后命令行前面一般会出现(venv)标识。此时再执行python --version和pip --version指向的都是虚拟环境内的工具。4.2 使用 pip 安装 Django激活虚拟环境后安装 Django 就非常安全了pip install django如果你想让操作更精确可以使用python -m pip install django这会从 PyPI 官方源下载 Django 最新稳定版并安装。安装完成后查看版本python -m django --version如果输出类似5.x.x的版本号说明安装成功。注意这里用的是python -m django它可以确保 Django 与当前 Python 解释器绑定避免因为 PATH 顺序问题导致找不到命令。4.3 创建 Django 项目Django 安装后会提供django-admin命令行工具。通过它创建项目django-admin startproject mysite执行后当前目录下会生成一个mysite文件夹。进入该文件夹查看目录结构cd mysite dir或者用更直观的树形命令tree在 Linux/macOS 下如果没有 tree可以暂时用ls -R。项目目录大致如下mysite/ manage.py mysite/ __init__.py settings.py urls.py asgi.py wsgi.py这里简单解释几个关键文件的作用。manage.py是项目的主要命令行入口后续很多操作都要通过它完成。settings.py是项目的全局配置数据库、应用注册、静态文件路径都在这里。urls.py是 URL 路由配置入口决定哪个地址对应哪个视图。wsgi.py和asgi.py是部署时使用的服务器入口文件。4.4 启动开发服务器Django 自带一个轻量开发服务器用于本地调试。启动方式很简单python manage.py runserver启动成功后命令行会输出类似下面的信息Watching for file changes with StatReloader Performing system checks... System check identified no issues (0 silenced). You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions. Run python manage.py migrate to apply them. Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.这个输出很关键说明三件事第一项目结构正确系统检查通过第二有些默认应用的数据库迁移还没有执行第三服务器已经在8000端口运行。关于迁移新手可以先记下结论后续运行python manage.py migrate可以应用这些默认迁移创建数据库表。此时即使不迁移开发服务器也能启动但进入 Admin 后台会报错。4.5 浏览器访问验证打开浏览器访问http://127.0.0.1:8000/。如果看到 Django 的默认欢迎页面出现一个火箭图标和 It worked! 提示说明项目已经成功运行。这是 Django 安装与项目创建全流程是否走通的最直观验证。4.6 停止服务器在终端按CtrlC即可停止开发服务器。开发服务器默认开启了自动重载你修改 Python 代码后服务器会自动重启无需手动干预。5. 创建应用并编写一个最小测试用例安装和项目创建只是第一步。如果你想真正验证 Django 是否完全可用最有效的方式是创建一个业务应用并利用 Django 自带的测试框架跑一次测试。这样不仅能说明安装没问题也能证明整个开发链路是通的。5.1 创建应用在项目根目录mysite下执行python manage.py startapp polls这里的polls是应用名称你可以理解为“投票应用”。Django 会在当前目录下生成polls文件夹里面包含polls/ __init__.py admin.py apps.py migrations/ __init__.py models.py tests.py views.py初学者经常会混淆mysite文件夹和polls文件夹的关系。简单来说mysite是项目配置层polls是业务代码层。你写的视图、模型、表单、测试代码大部分放在polls应用目录里。5.2 在 settings.py 中注册应用新建的应用需要注册到项目中Django 才知道要管理它。打开mysite/settings.py找到INSTALLED_APPS列表把polls加进去INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, polls, ]这一步是新手经常跳过的。如果你创建了应用却不注册很多功能比如自动生成数据表、Admin 后台显示模型会找不到应用数据排查起来很诡异。5.3 写一个简单视图打开polls/views.py写一个最简单的视图函数from django.http import HttpResponse def index(request): return HttpResponse(Hello, Django! This is the polls index.)这个视图做的事情很简单接收一个请求返回一个文本响应。它的作用是验证 URL 路由、视图函数和响应链路是否畅通。5.4 配置 URL 路由Django 的 URL 映射需要两级配置。先在polls应用目录下新建一个urls.py文件内容如下from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]然后在项目配置层的mysite/urls.py中引入应用的路由from django.contrib import admin from django.urls import include, path urlpatterns [ path(admin/, admin.site.urls), path(polls/, include(polls.urls)), ]这里的逻辑是浏览器访问/polls/时Django 会把请求转交给polls.urls然后匹配到views.index最终返回页面内容。这就是 Django 处理请求的完整链路。5.5 编写测试用例Django 的测试框架基于 Python 标准库 unittest但又做了一些增强。比如你可以在测试代码中直接调用测试数据库可以模拟客户端请求等。下面是一个最小测试用例用来测试首页视图的返回内容from django.test import TestCase class PollsIndexViewTests(TestCase): def test_index_returns_hello_message(self): response self.client.get(/polls/) self.assertEqual(response.status_code, 200) self.assertContains(response, Hello, Django!)这个测试做了两件事第一用测试客户端请求/polls/地址第二断言返回的状态码是 200并且响应内容包含Hello, Django!。如果这两条都通过说明视图和路由配置正确。5.6 运行测试在项目根目录执行python manage.py test polls运行后预期输出类似Found 1 test(s). Creating test database for alias default... System check identified no issues (0 silenced). . ---------------------------------------------------------------------- Ran 1 test in 0.023s OK看到OK就说明测试通过。这一步的意义比较重要Django 的测试框架会自动创建一个独立的测试数据库测试结束后自动销毁不会影响真实的开发数据库。因此你可以放心地写测试、跑测试不用担心污染环境。5.7 把测试融入日常开发很多初学者把测试当成项目后期才做的事这是一个比较大的误区。测试的价值在于防范回归。当你修改了某个视图逻辑后跑一次已有测试就能快速发现是否破坏了原有功能。在 Django 项目里比较好的节奏是“每写一个功能就配套写一组简单测试”。不要求一开始就做到 TDD但至少要保证核心路径有测试覆盖。6. 验证安装与测试效果这一节把前面所有命令整理成一个“验证清单”方便你按顺序检查环境是否完全就绪。步骤命令预期结果失败时的检查点检查 Pythonpython --version输出 Python 3.8 版本号检查 PATH 配置检查 pippython -m pip --version输出 pip 版本号确认 Python 安装完整创建虚拟环境python -m venv venv目录下生成 venv 文件夹检查 Python 是否支持 venv激活虚拟环境venv\Scripts\activate或source venv/bin/activate命令行出现(venv)前缀命令位置是否正确安装 Djangopython -m pip install django显示安装成功检查网络源查看 Django 版本python -m django --version输出版本号安装是否成功创建项目django-admin startproject mysite生成 mysite 目录django-admin 是否可用启动服务器python manage.py runserver日志提示正在运行端口是否被占用浏览器访问打开http://127.0.0.1:8000/显示 Django 欢迎页服务器是否还开着创建应用python manage.py startapp polls生成 polls 目录当前目录是否正确运行测试python manage.py test pollsOK测试通过测试代码是否有语法错误这个清单可以作为你的“安装测试自检表”。如果每一步都通过说明本机的 Django 开发环境已经完整可用可以进入下一步深入学习。如果中途某一步失败不要急着跳过先看对应的“失败时的检查点”再结合下一节的排查思路定位问题。7. 常见问题与排查思路Django 安装与测试过程中新手最容易踩到的坑集中在几个方面命令找不到、端口占用、数据库迁移未执行、中文编码问题。下面用表格整理常见问题、可能原因和解决办法。问题现象可能原因排查方式解决方案django-admin不是内部或外部命令未使用虚拟环境或 PATH 未配置执行python -m django --version检查 Django 是否可用激活虚拟环境后再执行或改用python -m djangopip install django很慢或超时默认源在国外网络不稳定查看 pip 下载日志临时换用国内镜像源pip install django -i https://pypi.tuna.tsinghua.edu.cn/simplepython manage.py runserver提示端口被占用8000 端口已开启其他程序执行netstat -ano | findstr 8000查看占用进程换端口python manage.py runserver 8080浏览器访问欢迎页样式丢失开发服务器静态文件未加载浏览器控制台查看 404 资源等待服务器完整启动或确认staticfiles应用启用进入 Admin 后台报数据库错误默认迁移未执行提示 “unapplied migration”执行python manage.py migratepython manage.py test报数据库权限错误测试数据库创建失败查看数据库配置和当前用户权限确认本地数据库账号有创建数据库权限中文内容在页面显示乱码文件编码不是 UTF-8检查文件头部编码文件统一保存为 UTF-8 格式修改代码后服务器不自动重启使用了非默认监听模式检查终端日志是否提示自动重载按CtrlC后重新runserver7.1 关于镜像源的使用说明提到换源这里有必要多说一句。在使用 pip 安装时如果网络比较慢可以临时指定国内镜像源。除了清华源还有阿里云、中科大等镜像源。但要注意不要为了省事把镜像地址永久写死在全局配置里因为不同镜像源的同步更新速度不同长期固定在一个镜像源可能导致安装不到某些刚发布的新版本。更好的方式是在项目虚拟环境里按需使用临时参数或者通过项目级pip.conf配置。7.2 关于数据库迁移的提醒Django 项目默认启用了几个内置应用包括admin、auth、contenttypes、sessions。这些应用需要数据库表才能正常工作。很多新手在启动服务器时看到欢迎页以为一切正常结果点进 Admin 后台就报错原因就是没有执行migrate。所以创建一个新项目的标准流程应该是创建项目、创建应用、注册应用、执行migrate、再启动服务器。8. 最佳实践与工程建议安装与测试跑通之后建议你从第一天开始就养成一些工程习惯。这些习惯短期内看不出区别等项目和团队规模变大后能省下大量的排错时间。8.1 永远使用虚拟环境不管你是在自己的电脑上开发还是在服务器上部署只要你直接往系统 Python 里安装 Django就已经埋下了隐患。系统 Python 往往被多个工具和项目共享如果你安装或升级了某个包可能导致其他依赖它的程序无法启动。使用虚拟环境后每个项目都有一套独立的依赖删除项目时直接删掉虚拟环境目录即可干净利落。8.2 固定依赖版本当你完成环境安装后建议把当前环境里的依赖包版本记录下来pip freeze requirements.txt这个文件会记录当前虚拟环境所有依赖包的精确版本号。别人拿到你的项目后可以这样复现环境pip install -r requirements.txt这一步很重要。Django 的版本升级有时会带来迁移命令变化、配置项调整。如果项目没有版本记录过几个月后重新部署可能因为 Django 版本变化导致莫名其妙的兼容问题。8.3 把 manage.py 作为唯一命令入口Django 项目里很多操作都要通过manage.py完成比如启动服务器、执行迁移、创建应用、运行测试。建议你记住这个感知Django 项目的日常操作基本都从manage.py开始。不要试图绕过它直接运行某个 Python 文件因为manage.py会加载项目的配置、注册应用、设置环境变量这些都依赖它。8.4 尽早引入测试Django 自带的测试框架足够强大不需要在初期引入第三方测试工具。你可以从最基础的功能测试开始比如某个 URL 返回 200、某个响应中包含关键字段、某个模型对象的字符串表示正确。随着业务逻辑增加再逐渐补充模型层和视图层的测试。写测试的时候注意几点测试用例之间应该相互独立不要依赖某些测试运行后才创建的数据不要用真实的生产数据库做测试因为 Django 会在测试时自动创建独立测试数据库如果某个测试需要登录状态可以借助 Django 提供的Client类和force_login方法模拟登录。8.5 注意安全边界如果你是照着教程做本地学习默认设置问题不大。但如果有一天你把项目部署到公网或者用 Django 做真实业务有几个安全点需要提前了解DEBUG True时Django 会把详细的错误堆栈抛给访问者生产环境必须关闭。SECRET_KEY不能硬编码在代码里也不要提交到代码仓库。本地开发服务器是单进程的不适合对外提供正式服务生产环境需要配合 WSGI/ASGI 服务器和反向代理。数据库连接信息、API 密钥属于敏感配置建议通过环境变量管理。8.6 目录结构建议Django 项目成熟后代码量会增长很快。建议在项目根目录下按功能划分应用而不是把多个业务模块堆在同一个应用里。一个常见做法是mysite/ manage.py mysite/ settings/ base.py development.py production.py urls.py apps/ blog/ users/ comments/ requirements/ base.txt development.txt production.txt .gitignore这种划分方式适合中大型项目。对于刚开始学习的新手官方默认的目录结构已经够用不必过早追求复杂分层。但一个原则可以从第一天开始遵守每个业务模块对应一个独立应用保持代码的模块化。9. 总结与后续学习方向至此你已经完成了 Django 从安装、创建项目、启动服务器、创建应用到编写并运行测试的完整流程。这篇文章想让你记住的几件事是Django 是一个功能完整的 Web 框架适合构建包含数据管理和后台功能的 Web 应用安装 Django 必须使用虚拟环境避免污染系统 Python安装之后要走通创建项目、启动服务器、创建应用三个步骤才算真正可用Django 自带测试框架写测试不应是项目后期的补丁而是开发过程中的标配动作。如果你现在是初学者下一步推荐按这个顺序学习学会 Admin 后台的自动管理功能在polls应用里定义一个简单模型后开启后台管理理解 Django 的自动管理思路。学习 URL 路由的更多写法包含路径参数、命名空间、重定向等。学习 Django ORM 的基本操作重点理解增删改查、过滤条件和关联查询。学习模板引擎的基本语法模板继承、循环、过滤器。再进阶一点可以学习 Django 的表单、认证、中间件以及 Django REST Framework 的 API 开发。如果你已经有一定基础这篇安装与测试内容更多起到的是“环境校准”作用。换个新电脑、加入新项目、或者接手一套老代码时按照文中的验证清单逐项检查能帮你快速定位环境问题节省不少排查时间。最后再给一个实用性建议把python manage.py test纳入你的日常开发循环。每改动一次核心逻辑就顺手跑一遍测试。初期这会显得有点慢但当你开始重构代码、调整路由、新增数据库字段时会发现有测试兜底是一种非常大的安全感。Django 的世界很大ORM、Admin、模板、REST API、部署、性能优化都值得慢慢钻研而这一切的起点就是你刚刚跑通的这套安装与测试流程。 Django安装与测试全流程指南：从环境配置到跑通测试
如果你正打算学习 Django或者已经在网上零零散散看过一些教程那么你很可能遇到过下面这些情况跟着教程敲完pip install django结果一运行django-admin就提示“不是内部或外部命令”明明下载了最新版 Python却因为没装 pip 导致依赖装不上项目创建成功了访问127.0.0.1:8000却一直转圈打不开页面。这些问题的根源通常不是 Django 本身有多难而是安装和测试这条“进门第一步”没有走扎实。很多人学 Django 时会直接跳过安装细节直奔路由、模型、视图去抄代码。这种做法的风险在于一旦本地环境与教程环境不一致你会同时面对“环境问题”和“代码问题”根本分不清该从哪里排查。作为一门实战性极强的 Web 框架Django 的学习路径应该是“先跑通、再理解、后深入”。而“跑通”的第一步就是安装、创建项目、启动开发服务器、跑一次测试。这正是这篇文章要帮你解决的问题。这篇文章会带着你从零开始完成 Django 的安装与测试。整个流程会覆盖环境准备、虚拟环境、安装命令、创建项目、启动服务、写一个最小测试用例、以及常见报错的排查思路。文章末尾还会给出一套适合新手和团队协作的工程建议。读完以后你可以把本文当作一份“安装排错清单”收藏使用后续每次换电脑或换项目都可以按同样的步骤复现环境。1. 这篇文章真正要解决的问题先聊一个比较现实的痛点Django 的安装和测试看起来只是两行命令的事但实际执行时却存在不少隐性门槛。第一层门槛是环境差异。Django 运行在 Python 之上而 Python 的安装方式五花八门官方安装包、Anaconda、系统自带的 Python、包管理器安装的 Python……不同来源的 Python 版本、pip 指向、命令行环境都不一样。如果你电脑上同时存在多个 Python 版本python和pip指向的可能是不同的解释器这时候安装的 Django 并不会自动出现在你期望的那个环境里。第二层门槛是依赖管理。Django 是一个非常完整的框架它的依赖相对保守但如果你直接用系统级 Python 安装各种包很容易把环境弄乱今天装一个包明天升级另一个包最后发现某个项目跑不起来了。这种“依赖地狱”在 Web 开发里非常常见。解决方式就是使用虚拟环境项目之间互不干扰。第三层门槛是“安装成功”和“项目可运行”之间还隔着几步。很多人以为pip install django跑完就算成功其实安装完成只是第一步。你还需要创建项目、创建应用、启动开发服务器甚至跑一个测试用例来证明链路是通的。只有这些步骤全部走通Django 才真正能用起来。先说判断Django 的安装与测试并没有想象中的那么简单但也并不复杂。它的关键点在于理解“Python 环境”和“Django 项目”之间的关系。只要环境隔离做好了后面的开发会顺畅很多。这篇文章适合三类读者刚入门 Django 的新手、需要在本地搭建 Django 开发环境的开发者、以及准备写自动化测试但还不熟悉 Django 测试框架的同学。2. Django 的核心概念与适用场景在开始安装之前有必要先搞清楚你装的到底是什么以及它适合做什么。2.1 Django 是什么Django 是一个基于 Python 的高层 Web 框架官方有一句很经典的口号The web framework for perfectionists with deadlines。翻译过来就是“为追求完美的开发者准备的、带截止日期的 Web 框架”。这句话其实点出了 Django 的两个特性一是设计理念上追求规范和完整二是它的目标之一是让开发者更快完成任务。Django 采用 MTV 架构也就是 Model-Template-View它和传统 MVC 有点类似但职责划分略有不同。Model 负责数据层Template 负责页面表现层View 负责业务逻辑层。这种分层让代码组织变得清晰但也意味着初学者需要理解一定的抽象概念。2.2 Django 内置了什么为什么说 Django 是“全家桶”式框架因为它把网站开发中很多高频需求都内置了ORM对象关系映射可以用 Python 代码操作数据库不必直接写 SQL。Admin 后台自动生成数据管理后台只需少量配置。模板引擎支持继承、过滤、循环等逻辑方便渲染 HTML。表单系统负责表单校验和渲染。认证系统内置用户、登录、权限、会话机制。中间件机制在请求和响应之间插入处理逻辑。自动化测试框架基于 Python 的 unittest可以编写和运行测试用例。这一点是 Django 和 Flask、FastAPI 这类轻量框架的主要区别。Flask 只提供核心 Web 能力其余要靠扩展Django 则直接给你一套完整的开发体系。对初学者来说Django 的学习曲线更陡一些但一旦掌握了它能帮你减少很多选型和技术组合的成本。2.3 适合什么场景从实际项目来看Django 在很多领域都有稳定应用内容管理系统CMS官方就有 Django CMS 方案。电商平台ORM 和 Admin 对商品、订单、用户管理非常友好。数据可视化平台可以和 Pandas、Celery 等数据工具协同。企业内部系统需求通常是增删改查、权限管理、报表展示Django 开发效率很高。快速原型产品因为内置功能多团队可以快速做出可演示的版本。如果你要做的是简单的 API 接口服务FastAPI 或 Flask 可能更轻但如果是一个包含后台管理、用户认证、数据库表和页面渲染的完整 Web 应用Django 的优势非常明显。2.4 新手最容易误解什么一个常见误解是Django 就是 MVC所以必须先学会数据库才能用。其实 Django 的 ORM 层已经帮你屏蔽了很多 SQL 细节你只需要定义好模型类Django 会负责建表和查询。另一个误解是Django 只适合大项目不适合小项目。这个说法不完全准确。Django 确实内置了很多功能但对于中小型项目你可以只用其中一部分能力并不需要全部启用。还有一个容易混淆的概念是“创建项目”和“创建应用”。Django 项目是你整个服务的入口包含全局配置和 URL 路由而应用是项目下负责具体业务模块的代码包。一个项目可以包含多个应用。例如一个博客项目下面可以有blog、comments、users等应用。这个关系一定要在动手前理解否则后续创建各种文件和目录时容易迷失。3. 环境准备与前置条件安装 Django 之前我们先把环境准备好。环境准备的目标是形成一套干净的、可复现的开发环境。这里会涉及操作系统、Python 版本、虚拟环境工具和 pip 几个概念。3.1 操作系统与终端Django 官方支持 Windows、macOS 和主流 Linux 发行版。不同操作系统在命令行操作上略有差异但核心逻辑是一样的。本文示例命令以 Windows 为主同时会标注 macOS/Linux 对应的差异。如果你使用的是 macOS 或 Linux操作逻辑完全一致只是把激活虚拟环境的命令换成 source 方式。3.2 Python 版本选择Django 对 Python 版本有明确要求。目前 Django 稳定版本要求 Python 3.8 及以上。因为版本更新较快这里不写死具体版本号建议你安装尽量新的 Python 3 稳定版本。注意Django 不支持 Python 2还在用 Python 2 的机器需要先升级 Python。检查 Python 是否安装python --version如果是 Windows 且命令提示符输入python --version没有反应可以尝试py --version这是因为 Windows 上有时会通过py启动器来调用 Python。如果两条命令都不识别说明 Python 还没有正确安装需要先安装 Python 并勾选“Add Python to PATH”。3.3 pip 与依赖管理pip 是 Python 官方的包管理工具。新版 Python 安装包大多自带 pip。检查 pip 是否可用pip --version如果提示找不到 pip可以用 Python 的模块方式执行python -m pip --version这里需要理解一个细节pip命令有时候可能指向的是系统级环境而python -m pip一定指向当前python解释器对应的 pip。所以当你的系统存在多个 Python 版本时建议统一使用python -m pip来保证安装目标与解释器一致。3.4 虚拟环境为什么必须用虚拟环境virtual environment是 Python 项目隔离依赖的通用方案。它的核心作用是为每个项目创建一个独立的 Python 运行环境项目 A 装 Django 3.x项目 B 装 Django 5.x两者互不影响。Django 官方推荐的虚拟环境方式就是 Python 自带的venv模块。它不需要额外安装创建命令也简单。后面所有内容都会基于虚拟环境展开这也是目前最稳妥、最适合新手的方式。4. Django 安装与项目创建这一节是核心操作区。所有命令我都会提供可复制的完整版本并解释每一步的作用。建议你一次性顺序执行不要跳跃。4.1 创建并激活虚拟环境先在某个目录下创建一个项目文件夹例如django_startmkdir django_start cd django_start然后创建虚拟环境。Windows、macOS、Linux 命令基本一致python -m venv venv这条命令会在当前目录下生成一个venv文件夹里面装着一个独立的 Python 环境。激活方式Windowsvenv\Scripts\activatemacOS / Linuxsource venv/bin/activate激活成功后命令行前面一般会出现(venv)标识。此时再执行python --version和pip --version指向的都是虚拟环境内的工具。4.2 使用 pip 安装 Django激活虚拟环境后安装 Django 就非常安全了pip install django如果你想让操作更精确可以使用python -m pip install django这会从 PyPI 官方源下载 Django 最新稳定版并安装。安装完成后查看版本python -m django --version如果输出类似5.x.x的版本号说明安装成功。注意这里用的是python -m django它可以确保 Django 与当前 Python 解释器绑定避免因为 PATH 顺序问题导致找不到命令。4.3 创建 Django 项目Django 安装后会提供django-admin命令行工具。通过它创建项目django-admin startproject mysite执行后当前目录下会生成一个mysite文件夹。进入该文件夹查看目录结构cd mysite dir或者用更直观的树形命令tree在 Linux/macOS 下如果没有 tree可以暂时用ls -R。项目目录大致如下mysite/ manage.py mysite/ __init__.py settings.py urls.py asgi.py wsgi.py这里简单解释几个关键文件的作用。manage.py是项目的主要命令行入口后续很多操作都要通过它完成。settings.py是项目的全局配置数据库、应用注册、静态文件路径都在这里。urls.py是 URL 路由配置入口决定哪个地址对应哪个视图。wsgi.py和asgi.py是部署时使用的服务器入口文件。4.4 启动开发服务器Django 自带一个轻量开发服务器用于本地调试。启动方式很简单python manage.py runserver启动成功后命令行会输出类似下面的信息Watching for file changes with StatReloader Performing system checks... System check identified no issues (0 silenced). You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions. Run python manage.py migrate to apply them. Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.这个输出很关键说明三件事第一项目结构正确系统检查通过第二有些默认应用的数据库迁移还没有执行第三服务器已经在8000端口运行。关于迁移新手可以先记下结论后续运行python manage.py migrate可以应用这些默认迁移创建数据库表。此时即使不迁移开发服务器也能启动但进入 Admin 后台会报错。4.5 浏览器访问验证打开浏览器访问http://127.0.0.1:8000/。如果看到 Django 的默认欢迎页面出现一个火箭图标和 It worked! 提示说明项目已经成功运行。这是 Django 安装与项目创建全流程是否走通的最直观验证。4.6 停止服务器在终端按CtrlC即可停止开发服务器。开发服务器默认开启了自动重载你修改 Python 代码后服务器会自动重启无需手动干预。5. 创建应用并编写一个最小测试用例安装和项目创建只是第一步。如果你想真正验证 Django 是否完全可用最有效的方式是创建一个业务应用并利用 Django 自带的测试框架跑一次测试。这样不仅能说明安装没问题也能证明整个开发链路是通的。5.1 创建应用在项目根目录mysite下执行python manage.py startapp polls这里的polls是应用名称你可以理解为“投票应用”。Django 会在当前目录下生成polls文件夹里面包含polls/ __init__.py admin.py apps.py migrations/ __init__.py models.py tests.py views.py初学者经常会混淆mysite文件夹和polls文件夹的关系。简单来说mysite是项目配置层polls是业务代码层。你写的视图、模型、表单、测试代码大部分放在polls应用目录里。5.2 在 settings.py 中注册应用新建的应用需要注册到项目中Django 才知道要管理它。打开mysite/settings.py找到INSTALLED_APPS列表把polls加进去INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, polls, ]这一步是新手经常跳过的。如果你创建了应用却不注册很多功能比如自动生成数据表、Admin 后台显示模型会找不到应用数据排查起来很诡异。5.3 写一个简单视图打开polls/views.py写一个最简单的视图函数from django.http import HttpResponse def index(request): return HttpResponse(Hello, Django! This is the polls index.)这个视图做的事情很简单接收一个请求返回一个文本响应。它的作用是验证 URL 路由、视图函数和响应链路是否畅通。5.4 配置 URL 路由Django 的 URL 映射需要两级配置。先在polls应用目录下新建一个urls.py文件内容如下from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]然后在项目配置层的mysite/urls.py中引入应用的路由from django.contrib import admin from django.urls import include, path urlpatterns [ path(admin/, admin.site.urls), path(polls/, include(polls.urls)), ]这里的逻辑是浏览器访问/polls/时Django 会把请求转交给polls.urls然后匹配到views.index最终返回页面内容。这就是 Django 处理请求的完整链路。5.5 编写测试用例Django 的测试框架基于 Python 标准库 unittest但又做了一些增强。比如你可以在测试代码中直接调用测试数据库可以模拟客户端请求等。下面是一个最小测试用例用来测试首页视图的返回内容from django.test import TestCase class PollsIndexViewTests(TestCase): def test_index_returns_hello_message(self): response self.client.get(/polls/) self.assertEqual(response.status_code, 200) self.assertContains(response, Hello, Django!)这个测试做了两件事第一用测试客户端请求/polls/地址第二断言返回的状态码是 200并且响应内容包含Hello, Django!。如果这两条都通过说明视图和路由配置正确。5.6 运行测试在项目根目录执行python manage.py test polls运行后预期输出类似Found 1 test(s). Creating test database for alias default... System check identified no issues (0 silenced). . ---------------------------------------------------------------------- Ran 1 test in 0.023s OK看到OK就说明测试通过。这一步的意义比较重要Django 的测试框架会自动创建一个独立的测试数据库测试结束后自动销毁不会影响真实的开发数据库。因此你可以放心地写测试、跑测试不用担心污染环境。5.7 把测试融入日常开发很多初学者把测试当成项目后期才做的事这是一个比较大的误区。测试的价值在于防范回归。当你修改了某个视图逻辑后跑一次已有测试就能快速发现是否破坏了原有功能。在 Django 项目里比较好的节奏是“每写一个功能就配套写一组简单测试”。不要求一开始就做到 TDD但至少要保证核心路径有测试覆盖。6. 验证安装与测试效果这一节把前面所有命令整理成一个“验证清单”方便你按顺序检查环境是否完全就绪。步骤命令预期结果失败时的检查点检查 Pythonpython --version输出 Python 3.8 版本号检查 PATH 配置检查 pippython -m pip --version输出 pip 版本号确认 Python 安装完整创建虚拟环境python -m venv venv目录下生成 venv 文件夹检查 Python 是否支持 venv激活虚拟环境venv\Scripts\activate或source venv/bin/activate命令行出现(venv)前缀命令位置是否正确安装 Djangopython -m pip install django显示安装成功检查网络源查看 Django 版本python -m django --version输出版本号安装是否成功创建项目django-admin startproject mysite生成 mysite 目录django-admin 是否可用启动服务器python manage.py runserver日志提示正在运行端口是否被占用浏览器访问打开http://127.0.0.1:8000/显示 Django 欢迎页服务器是否还开着创建应用python manage.py startapp polls生成 polls 目录当前目录是否正确运行测试python manage.py test pollsOK测试通过测试代码是否有语法错误这个清单可以作为你的“安装测试自检表”。如果每一步都通过说明本机的 Django 开发环境已经完整可用可以进入下一步深入学习。如果中途某一步失败不要急着跳过先看对应的“失败时的检查点”再结合下一节的排查思路定位问题。7. 常见问题与排查思路Django 安装与测试过程中新手最容易踩到的坑集中在几个方面命令找不到、端口占用、数据库迁移未执行、中文编码问题。下面用表格整理常见问题、可能原因和解决办法。问题现象可能原因排查方式解决方案django-admin不是内部或外部命令未使用虚拟环境或 PATH 未配置执行python -m django --version检查 Django 是否可用激活虚拟环境后再执行或改用python -m djangopip install django很慢或超时默认源在国外网络不稳定查看 pip 下载日志临时换用国内镜像源pip install django -i https://pypi.tuna.tsinghua.edu.cn/simplepython manage.py runserver提示端口被占用8000 端口已开启其他程序执行netstat -ano | findstr 8000查看占用进程换端口python manage.py runserver 8080浏览器访问欢迎页样式丢失开发服务器静态文件未加载浏览器控制台查看 404 资源等待服务器完整启动或确认staticfiles应用启用进入 Admin 后台报数据库错误默认迁移未执行提示 “unapplied migration”执行python manage.py migratepython manage.py test报数据库权限错误测试数据库创建失败查看数据库配置和当前用户权限确认本地数据库账号有创建数据库权限中文内容在页面显示乱码文件编码不是 UTF-8检查文件头部编码文件统一保存为 UTF-8 格式修改代码后服务器不自动重启使用了非默认监听模式检查终端日志是否提示自动重载按CtrlC后重新runserver7.1 关于镜像源的使用说明提到换源这里有必要多说一句。在使用 pip 安装时如果网络比较慢可以临时指定国内镜像源。除了清华源还有阿里云、中科大等镜像源。但要注意不要为了省事把镜像地址永久写死在全局配置里因为不同镜像源的同步更新速度不同长期固定在一个镜像源可能导致安装不到某些刚发布的新版本。更好的方式是在项目虚拟环境里按需使用临时参数或者通过项目级pip.conf配置。7.2 关于数据库迁移的提醒Django 项目默认启用了几个内置应用包括admin、auth、contenttypes、sessions。这些应用需要数据库表才能正常工作。很多新手在启动服务器时看到欢迎页以为一切正常结果点进 Admin 后台就报错原因就是没有执行migrate。所以创建一个新项目的标准流程应该是创建项目、创建应用、注册应用、执行migrate、再启动服务器。8. 最佳实践与工程建议安装与测试跑通之后建议你从第一天开始就养成一些工程习惯。这些习惯短期内看不出区别等项目和团队规模变大后能省下大量的排错时间。8.1 永远使用虚拟环境不管你是在自己的电脑上开发还是在服务器上部署只要你直接往系统 Python 里安装 Django就已经埋下了隐患。系统 Python 往往被多个工具和项目共享如果你安装或升级了某个包可能导致其他依赖它的程序无法启动。使用虚拟环境后每个项目都有一套独立的依赖删除项目时直接删掉虚拟环境目录即可干净利落。8.2 固定依赖版本当你完成环境安装后建议把当前环境里的依赖包版本记录下来pip freeze requirements.txt这个文件会记录当前虚拟环境所有依赖包的精确版本号。别人拿到你的项目后可以这样复现环境pip install -r requirements.txt这一步很重要。Django 的版本升级有时会带来迁移命令变化、配置项调整。如果项目没有版本记录过几个月后重新部署可能因为 Django 版本变化导致莫名其妙的兼容问题。8.3 把 manage.py 作为唯一命令入口Django 项目里很多操作都要通过manage.py完成比如启动服务器、执行迁移、创建应用、运行测试。建议你记住这个感知Django 项目的日常操作基本都从manage.py开始。不要试图绕过它直接运行某个 Python 文件因为manage.py会加载项目的配置、注册应用、设置环境变量这些都依赖它。8.4 尽早引入测试Django 自带的测试框架足够强大不需要在初期引入第三方测试工具。你可以从最基础的功能测试开始比如某个 URL 返回 200、某个响应中包含关键字段、某个模型对象的字符串表示正确。随着业务逻辑增加再逐渐补充模型层和视图层的测试。写测试的时候注意几点测试用例之间应该相互独立不要依赖某些测试运行后才创建的数据不要用真实的生产数据库做测试因为 Django 会在测试时自动创建独立测试数据库如果某个测试需要登录状态可以借助 Django 提供的Client类和force_login方法模拟登录。8.5 注意安全边界如果你是照着教程做本地学习默认设置问题不大。但如果有一天你把项目部署到公网或者用 Django 做真实业务有几个安全点需要提前了解DEBUG True时Django 会把详细的错误堆栈抛给访问者生产环境必须关闭。SECRET_KEY不能硬编码在代码里也不要提交到代码仓库。本地开发服务器是单进程的不适合对外提供正式服务生产环境需要配合 WSGI/ASGI 服务器和反向代理。数据库连接信息、API 密钥属于敏感配置建议通过环境变量管理。8.6 目录结构建议Django 项目成熟后代码量会增长很快。建议在项目根目录下按功能划分应用而不是把多个业务模块堆在同一个应用里。一个常见做法是mysite/ manage.py mysite/ settings/ base.py development.py production.py urls.py apps/ blog/ users/ comments/ requirements/ base.txt development.txt production.txt .gitignore这种划分方式适合中大型项目。对于刚开始学习的新手官方默认的目录结构已经够用不必过早追求复杂分层。但一个原则可以从第一天开始遵守每个业务模块对应一个独立应用保持代码的模块化。9. 总结与后续学习方向至此你已经完成了 Django 从安装、创建项目、启动服务器、创建应用到编写并运行测试的完整流程。这篇文章想让你记住的几件事是Django 是一个功能完整的 Web 框架适合构建包含数据管理和后台功能的 Web 应用安装 Django 必须使用虚拟环境避免污染系统 Python安装之后要走通创建项目、启动服务器、创建应用三个步骤才算真正可用Django 自带测试框架写测试不应是项目后期的补丁而是开发过程中的标配动作。如果你现在是初学者下一步推荐按这个顺序学习学会 Admin 后台的自动管理功能在polls应用里定义一个简单模型后开启后台管理理解 Django 的自动管理思路。学习 URL 路由的更多写法包含路径参数、命名空间、重定向等。学习 Django ORM 的基本操作重点理解增删改查、过滤条件和关联查询。学习模板引擎的基本语法模板继承、循环、过滤器。再进阶一点可以学习 Django 的表单、认证、中间件以及 Django REST Framework 的 API 开发。如果你已经有一定基础这篇安装与测试内容更多起到的是“环境校准”作用。换个新电脑、加入新项目、或者接手一套老代码时按照文中的验证清单逐项检查能帮你快速定位环境问题节省不少排查时间。最后再给一个实用性建议把python manage.py test纳入你的日常开发循环。每改动一次核心逻辑就顺手跑一遍测试。初期这会显得有点慢但当你开始重构代码、调整路由、新增数据库字段时会发现有测试兜底是一种非常大的安全感。Django 的世界很大ORM、Admin、模板、REST API、部署、性能优化都值得慢慢钻研而这一切的起点就是你刚刚跑通的这套安装与测试流程。