Ubuntu上从零搭建Django开发环境：虚拟环境、项目初始化与配置实战

1. 项目背景与整体搭建思路1.1 为什么选择Ubuntu作为Django的开发环境Django作为Python生态中最成熟的全栈Web框架之一它的开发体验和部署体验高度依赖底层操作系统的包管理能力和Python环境管理能力。Ubuntu在服务器端的占有率长期领先绝大多数云主机默认提供的镜像就是Ubuntu LTS版本这意味着你在本地Ubuntu上跑通的项目迁移到线上服务器时几乎不需要做额外的适配工作。这一点在实际项目交付中非常关键我见过太多团队在本地用某个小众发行版开发结果部署到线上时因为系统库版本差异导致各种编译错误白白浪费一两天时间。Ubuntu的apt包管理系统对Python相关的依赖支持非常完善像psycopg2、Pillow、lxml这类需要编译C扩展的库在Ubuntu上安装系统级依赖只需要一条apt命令就能搞定。另外Ubuntu的社区文档丰富遇到问题搜索时命中率高这对新手来说能省下大量排查时间。1.2 整体搭建流程拆解一个完整的Django项目搭建从零到能跑起来大致需要经过以下几个阶段系统基础环境准备更新系统包、安装Python、pip、虚拟环境工具数据库选型与安装开发阶段通常用SQLite快速起步正式项目建议PostgreSQL或MySQL虚拟环境创建与依赖管理隔离项目依赖避免不同项目之间的版本冲突Django项目初始化创建项目骨架、创建应用、配置settings开发服务器验证runserver跑通确认基础环境无误静态文件与媒体文件配置为后续前端资源管理打基础版本控制初始化git初始化配置.gitignore这个顺序不是随便定的。先搞系统环境再搞Python环境是因为很多Python库的安装依赖系统级的开发工具链先建虚拟环境再装Django是为了避免污染系统Python先跑通runserver再配置静态文件是因为静态文件配置涉及settings改动如果基础环境没跑通就改配置出了问题很难定位是哪一步引入的。1.3 常见误区与方案取舍很多新手一上来就装最新版的Python和Django这其实有风险。Django的每个大版本对Python版本有明确的支持范围比如Django 5.x要求Python 3.10以上Django 4.2 LTS支持Python 3.8到3.12。如果你用的Ubuntu 22.04系统自带的Python是3.10直接装Django 5.x没问题但如果你用的是Ubuntu 20.04系统Python是3.8装Django 5.x就会报错。我的建议是优先选择Django的LTS版本。LTS版本有三年以上的安全更新支持社区生态兼容性最好第三方库的适配也最完善。截至我写这篇内容时Django 4.2 LTS是一个很稳妥的选择它支持Python 3.8到3.12覆盖了绝大多数Ubuntu LTS版本的默认Python。另一个常见误区是直接用系统Python安装Django。Ubuntu的很多系统工具依赖系统Python的特定包版本你如果直接用pip往系统Python里装东西轻则导致系统工具异常重则把系统包管理搞崩。所以虚拟环境不是可选项是必选项。2. 系统环境准备与Python工具链配置2.1 系统更新与基础依赖安装拿到一台全新的Ubuntu机器第一件事永远是更新包索引并升级已有包。这一步看起来简单但跳过它直接装东西后面大概率会遇到依赖版本冲突。sudo apt update sudo apt upgrade -y更新完成后安装Python开发所需的基础工具链。这里列出的包各有用途我逐个说明sudo apt install -y python3 python3-pip python3-venv python3-dev \ build-essential libpq-dev libssl-dev libffi-dev \ zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \ git curl vimpython3-devPython的头文件和静态库编译C扩展时必须build-essential包含gcc、g、make等编译工具libpq-devPostgreSQL的客户端开发库用psycopg2连接PG时必须libssl-dev、libffi-devcryptography等加密库的编译依赖zlib1g-dev、libbz2-dev、libreadline-dev、libsqlite3-devPython源码编译时的可选依赖虽然用apt装的Python不需要但后续如果用pyenv编译Python就会用到注意如果你用的是Ubuntu最小化安装镜像build-essential可能没预装一定要手动装上否则pip安装任何需要编译的包都会失败。2.2 确认Python版本与pip配置装完之后确认一下版本python3 --version pip3 --versionUbuntu 22.04默认是Python 3.10.xUbuntu 24.04默认是Python 3.12.x这两个版本跑Django 4.2 LTS和5.x都没问题。pip建议配置国内镜像源否则安装Django和后续依赖时速度会很慢。创建配置文件mkdir -p ~/.pip cat ~/.pip/pip.conf EOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn timeout 120 EOF这个配置对当前用户全局生效后续在虚拟环境里pip install也会读取这个配置。timeout设成120秒是为了应对网络波动时大包下载中断的问题。2.3 虚拟环境工具的选型对比Python虚拟环境有好几种方案我列个表对比一下工具安装方式优势适用场景venvPython内置零依赖标准库自带大多数项目首选virtualenvpip安装支持更老的Python版本需要兼容Python2时conda独立安装能管理非Python依赖数据科学项目pipenvpip安装整合了pip和venv小型项目快速起步poetry独立安装依赖解析和打包一体中大型项目对于Django Web开发我强烈建议用venv。它是Python 3.3以后内置的不需要额外安装行为稳定可预期和pip配合使用最直接。conda虽然强大但太重poetry学习曲线陡峭pipenv曾经流行但现在社区活跃度下降。创建虚拟环境的命令cd ~ mkdir -p projects cd projects python3 -m venv django_env source django_env/bin/activate激活后命令行提示符前面会出现(django_env)表示当前处于虚拟环境中。这时候which python应该指向~/projects/django_env/bin/python。实操心得我习惯把虚拟环境放在项目目录外面比如~/projects/django_env而不是放在项目根目录下。这样做的好处是项目目录更干净git提交时不用担心误提交虚拟环境文件。当然你也可以放在项目内只要.gitignore写对就行。3. Django项目初始化与核心配置3.1 安装Django与版本锁定虚拟环境激活状态下安装Djangopip install django4.2.*这里指定了4.2系列pip会自动选择4.2系列中最新的补丁版本。安装完成后验证python -m django --version应该输出类似4.2.16的版本号。安装完成后把当前环境的依赖导出到requirements.txtpip freeze requirements.txt这个文件要提交到git仓库团队成员克隆项目后执行pip install -r requirements.txt就能还原完全一致的依赖环境。注意pip freeze会导出所有包包括间接依赖这样能保证环境完全可复现。3.2 创建项目骨架与应用Django的项目结构分两层项目project和应用app。项目是配置容器应用是功能模块。一个项目可以包含多个应用。创建项目django-admin startproject mysite .注意最后那个.它表示在当前目录创建项目而不是再套一层目录。这样项目结构是~/projects/mysite/ ├── manage.py ├── mysite/ │ ├── __init__.py │ ├── settings.py │ ├── urls.py │ ├── asgi.py │ └── wsgi.py └── requirements.txt如果不加.会变成mysite/mysite/manage.py多一层嵌套后续操作路径都要多写一层很别扭。创建第一个应用python manage.py startapp blog应用目录结构blog/ ├── __init__.py ├── admin.py ├── apps.py ├── migrations/ ├── models.py ├── tests.py └── views.py创建完应用后必须在settings.py的INSTALLED_APPS里注册INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, # 新增 ]不注册的话Django不会加载这个应用的models迁移时也不会创建对应的数据库表。3.3 settings.py关键配置逐项说明settings.py是Django项目的核心配置文件几个关键项必须理解清楚DEBUG开发阶段设为True方便看到详细错误页面。上线必须改成False否则会泄露源码和配置信息。ALLOWED_HOSTSDEBUG为True时可以是空列表Django默认允许localhost。DEBUG为False时必须填写允许访问的域名或IP否则所有请求都会被拒绝。DATABASES默认是SQLite配置如下DATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } }如果换成PostgreSQLDATABASES { default: { ENGINE: django.db.backends.postgresql, NAME: mydb, USER: myuser, PASSWORD: mypassword, HOST: 127.0.0.1, PORT: 5432, } }LANGUAGE_CODE和TIME_ZONE中文项目建议改成LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai USE_I18N True USE_TZ FalseUSE_TZ设为False表示使用naive datetime数据库里存的就是本地时间。设为True则存UTC时间Django在模板渲染时自动转换。两种方案各有优劣我个人的习惯是小型项目用False省事大型跨国项目用True。STATIC_URL和STATICFILES_DIRSSTATIC_URL /static/ STATICFILES_DIRS [BASE_DIR / static] STATIC_ROOT BASE_DIR / staticfilesSTATICFILES_DIRS是开发时额外查找静态文件的目录STATIC_ROOT是collectstatic命令收集静态文件的目标目录部署时用。3.4 数据库迁移与超级用户创建配置好数据库后执行迁移python manage.py migrate这个命令会读取所有已注册应用的migrations目录在数据库中创建对应的表。Django自带的admin、auth、sessions等应用的表都会在这一步创建。创建后台管理超级用户python manage.py createsuperuser按提示输入用户名、邮箱、密码。密码有强度校验太简单的会被拒绝。启动开发服务器python manage.py runserver 0.0.0.0:80000.0.0.0表示监听所有网卡这样局域网内其他机器也能访问。如果只想本机访问用默认的127.0.0.1:8000即可。浏览器打开http://127.0.0.1:8000/admin/用刚才创建的超级用户登录能看到Django admin后台界面说明基础环境完全跑通了。4. 实操过程中的常见问题与排查技巧4.1 环境类问题速查表问题现象可能原因解决方法pip install报SSL错误系统CA证书过期或缺失sudo apt install ca-certificatespsycopg2安装失败缺少libpq-devsudo apt install libpq-devPillow安装失败缺少图像库开发包sudo apt install libjpeg-dev zlib1g-devmysqlclient安装失败缺少MySQL开发库sudo apt install default-libmysqlclient-dev虚拟环境激活后pip仍指向系统PATH顺序问题重新source bin/activate检查which piprunserver启动报端口占用8000端口被其他进程占用lsof -i:8000找到进程kill掉或换端口migrate报数据库连接失败数据库服务未启动或配置错误sudo systemctl status postgresql检查服务状态静态文件404STATICFILES_DIRS配置错误检查路径是否存在DEBUG是否为True4.2 几个我踩过的坑坑一虚拟环境忘记激活就装包。这个错误太常见了你在终端里敲pip install xxx装完发现项目里import还是报错一看which pip指向的是/usr/bin/pip。养成习惯每次打开新终端第一件事就是source ~/projects/django_env/bin/activate看到提示符前面的(django_env)再操作。坑二改了models.py忘记makemigrations。Django不会自动检测模型变化你必须手动执行python manage.py makemigrations生成迁移文件再执行migrate应用到数据库。我建议每次改完models就立刻执行这两条命令不要攒着一起做否则迁移文件冲突时很难处理。坑三ALLOWED_HOSTS配置遗漏。开发时DEBUGTrue一切正常部署时改成DEBUGFalse后所有请求返回400。原因就是ALLOWED_HOSTS没填。记住DEBUGFalse时ALLOWED_HOSTS必须包含实际访问的域名或IP。坑四SQLite数据库文件权限问题。如果你用root创建了项目后来用普通用户跑runserverSQLite文件可能没有写权限导致写入失败。解决办法是确保项目目录的属主和运行用户一致sudo chown -R $USER:$USER ~/projects/mysite。坑五pip freeze导出的依赖包含本地路径包。如果你用pip install -e .安装过本地包pip freeze会导出类似-e /path/to/package的行这个在别的机器上无法使用。导出前先检查requirements.txt内容把这类行手动删掉或替换成包名。4.3 开发效率提升技巧使用django-extensions这个第三方包提供了runserver_plus命令带自动重载和调试器还提供shell_plus命令自动加载所有模型省去手动import。pip install django-extensions werkzeug在INSTALLED_APPS里加上django_extensions然后python manage.py shell_plus所有models自动可用调试时非常方便。配置日志输出到控制台在settings.py里加日志配置开发时能看到SQL执行情况LOGGING { version: 1, disable_existing_loggers: False, handlers: { console: {class: logging.StreamHandler}, }, loggers: { django.db.backends: { handlers: [console], level: DEBUG, }, }, }这样每次ORM查询都会在控制台打印实际执行的SQL排查性能问题时很有用。上线前记得把level改成INFO或删掉这段配置。使用.env文件管理敏感配置不要把SECRET_KEY、数据库密码硬编码在settings.py里。用python-dotenv读取环境变量pip install python-dotenv在settings.py顶部from dotenv import load_dotenv load_dotenv() SECRET_KEY os.getenv(SECRET_KEY)项目根目录创建.env文件存放实际值.gitignore里排除.env提交一个.env.example作为模板。4.4 项目结构进阶建议当项目变大时建议按以下结构组织mysite/ ├── manage.py ├── requirements/ │ ├── base.txt │ ├── dev.txt │ └── prod.txt ├── config/ │ ├── settings/ │ │ ├── base.py │ │ ├── dev.py │ │ └── prod.py │ ├── urls.py │ └── wsgi.py ├── apps/ │ ├── blog/ │ └── users/ ├── static/ ├── media/ └── templates/把settings拆成base/dev/prod三个文件不同环境用不同配置。应用统一放在apps目录下通过sys.path调整导入路径。这种结构在团队协作时优势明显每个人负责的应用边界清晰配置变更也不会互相干扰。创建项目时可以用django-admin startproject config .把项目配置目录命名为config避免和项目名混淆。应用创建后移动到apps目录在settings里用完整路径注册比如apps.blog。最后分享一个我常用的alias放在~/.bashrc里alias actsource ~/projects/django_env/bin/activate alias runpython manage.py runserver 0.0.0.0:8000 alias mmpython manage.py makemigrations python manage.py migrate这样每次打开终端敲act激活环境run启动服务mm执行迁移省去大量重复输入。这些alias看起来不起眼但日积月累能省下不少时间而且能减少手误敲错命令的概率。