根本原因是未激活对应虚拟环境，导致 python 解释器找不到 django；应先激活环境再运行 python manage.py runserver，而非 django-admin runserver。
django-admin runserver 命令为什么报错“no module named django”
根本原因不是 Django 没装，而是你没在正确的 Python 环境里运行命令。常见于用 pip install django 装在系统 Python，但项目用的是 venv 或 poetry 环境，却忘了先激活。
- 检查当前 Python 解释器路径：
which python（macOS/Linux）或where python（Windows），确认它指向你的虚拟环境目录 - 进项目根目录后，必须先运行
source venv/bin/activate（Linux/macOS）或venv\Scripts\activate（Windows） - 验证 Django 是否可用：
python -c "import django; print(django.__version__)" - 别用
django-admin runserver—— 它不读取当前项目的settings.py；一律用python manage.py runserver
manage.py runserver 启动失败：Address already in use
端口被占是本地开发最常卡住的点，runserver 默认绑定 127.0.0.1:8000，只要另一个进程（比如上次没关的服务器、VS Code 的 Live Server、甚至某个 Electron 应用）占了 8000，就会报这个错。
- 查谁占了端口：
lsof -i :8000（macOS/Linux）或netstat -ano | findstr :8000（Windows），然后kill -9 [PID]或任务管理器结束进程 - 换端口启动：
python manage.py runserver 8001或python manage.py runserver 0.0.0.0:8000（后者允许局域网访问，调试手机端时有用） - 注意
0.0.0.0:8000不等于“开放公网”，它只是监听所有本地网络接口，防火墙和路由器仍会拦截外部请求
修改代码后页面不更新？自动重载失效的几种情况
runserver 的自动重载（autoreload）默认只监控 .py 文件变化，对模板、静态文件、环境变量、settings.py 里的非模块级配置改动不敏感。
- 模板（
.html）改了不刷新？加--reload-extra参数：python manage.py runserver --reload-extra=*.html - 用了
os.environ动态读取配置？autoreload 不会重新加载环境变量，需手动重启 - 某些 IDE（如 PyCharm）自带文件监视器，可能和 Django 的 autoreload 冲突，建议关掉 IDE 的“auto-reload on save”选项
- Linux 下如果项目在 NFS 或 Docker volume 中，inotify 可能不可用，此时要加
--noreload并手动 Ctrl+C + 回车重启
Django 开发服务器能直接上线吗
不能。runserver 是纯 Python 实现的单线程、无连接池、无静态文件优化的简易服务器，只适合开发调试。
- 性能上：并发超过 3–5 个请求就明显变慢，不支持长连接、HTTP/2、gzip 压缩等生产必需特性
- 安全上：没有请求体大小限制、无防 DDoS 机制、错误页面暴露完整 traceback（含路径、变量名）
- 静态文件：开发时靠
django.contrib.staticfiles临时服务，生产必须由 Nginx/Apache 或 CDN 托管STATIC_ROOT - 部署时必须换成 Gunicorn/uWSGI + Nginx 组合，
runserver连测试环境都不该出现
最容易被忽略的是：很多人把 DEBUG=True 和 runserver 绑定在一起，误以为只要换服务器就能上线 —— 实际上 DEBUG=True 本身就会禁用缓存、暴露敏感信息，必须同步设为 False 并配好 ALLOWED_HOSTS。
