能跑起来且不踩坑的关键三步是：python 3.10+、隔离虚拟环境、明确安装 django 5.0.x；django 5.0 不兼容低于 python 3.10 的版本。
能跑起来，且不踩坑，关键就三步：Python 3.10+、隔离虚拟环境、明确装 Django 5.0.x。Django 5.0 不兼容 Python django-admin 命令可能调错版本，manage.py 启动直接报 ImportError: cannot import name 'setup' from 'django' (django/__init__.py) 这类错。
检查并确保 Python 版本 ≥3.10
Django 5.0 硬性要求 Python 3.10 或更新。低于这个版本，哪怕装上了也会在 import django 时崩溃。
- 运行
python --version或python3 --version确认输出是类似3.10.12、3.11.9或3.12.4 - 如果显示
3.9.x或更低，别硬扛——用pyenv（推荐）或系统包管理器升级，不是改 PATH 就能绕过 - Mac 用户注意：
brew install python默认装的是最新版，但系统自带的/usr/bin/python3仍是旧版，务必用which python3看清你实际调用的是哪个解释器
用 venv 创建干净虚拟环境
不用 conda、不用 poetry，venv 是 Python 内置方案，最轻量也最可控。它能彻底隔开不同项目的依赖，避免 pip list 里混着 Django 3.x 和 5.x。
- 命令统一用
python -m venv venv（Windows/macOS/Linux 都适用），不要写成python3 -m venv venv——除非你python指向的是 Python 2，而你现在根本不会用 Python 2 - 激活方式按系统区分：
• macOS/Linux：source venv/bin/activate
• Windows：venv\Scripts\activate（PowerShell 下需先执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser） - 激活后终端提示符应出现
(venv)，此时which python输出必须指向项目内venv/bin/python（Mac/Linux）或venv\Scripts\python.exe（Windows）
安装指定版本的 Django 5.0.x
别只敲 pip install django——它可能装上还没发布的 5.1a0，也可能因缓存装错旧版。生产级操作必须锁死小版本号。
- 执行
pip install django==5.0.4（当前稳定小版本，截至 2026 年 6 月） - 验证是否装对：
python -m django --version输出必须是5.0.4，不是5.0.0或5.1.dev0 - 如果遇到
OSError: [Errno 13] Permission denied，说明你没激活虚拟环境，或者误用了sudo pip——停手，重新激活再试 - 顺手跑
pip install -U pip，避免旧版 pip 解析依赖出错
初始化项目并确认可启动
环境搭完不等于项目能跑，最后一步必须实测 manage.py runserver 能否吐出 Django 欢迎页。
- 用
django-admin startproject config .（注意末尾的.）直接在当前目录生成项目，避免多一层嵌套文件夹 - 立刻执行
python manage.py runserver，不要跳过这步——很多问题（比如settings.py编码错误、SQLite 版本太低）只在这时暴露 - 浏览器打开
http://127.0.0.1:8000，看到 “The install worked successfully!” 页面才算真正通关 - 如果页面空白或报
ImproperlyConfigured: SQLite 3.9.0 or later is required，说明系统 SQLite 太旧（尤其老 Mac），得单独升级 SQLite 并重编译 Python，不是 pip 能解决的
真正容易被忽略的，是 SQLite 版本和虚拟环境激活状态这两个“隐形开关”——它们不出错时不显眼，一出错就卡死在第一步，连 startproject 都执行不了。动手前先敲两行命令确认，比后面花两小时查日志强得多。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
