跳到主要内容

安装配置

本节介绍如何在不同的操作系统上安装和配置 Django 开发环境。

系统要求​

Django 对运行环境有以下要求：

  • Python 版本：Django 5.0 需要 Python 3.10 或更高版本
  • 数据库：PostgreSQL、MySQL、SQLite、Oracle 等（开发阶段可使用 SQLite）
  • 操作系统：Windows、macOS、Linux 均可

安装 Python​

Windows​

  1. 访问 Python 官网 下载安装包
  2. 运行安装程序，务必勾选 "Add Python to PATH"
  3. 打开命令提示符验证安装：
python --version
pip --version

macOS​

macOS 通常预装 Python，但建议使用 Homebrew 安装最新版本：

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install python

# 验证安装
python3 --version
pip3 --version

Linux (Ubuntu/Debian)​

# 更新包列表
sudo apt update

# 安装 Python 和 pip
sudo apt install python3 python3-pip python3-venv

# 验证安装
python3 --version
pip3 --version

创建虚拟环境​

虚拟环境是 Python 项目管理的最佳实践，它可以为每个项目创建独立的 Python 环境，避免不同项目之间的依赖冲突。

为什么需要虚拟环境？​

假设你有两个项目：

  • 项目 A 需要 Django 4.2
  • 项目 B 需要 Django 5.0

如果没有虚拟环境，这两个项目的 Django 版本会冲突。使用虚拟环境后，每个项目可以有自己独立的 Django 版本。

创建虚拟环境​

# 创建虚拟环境（推荐命名为 venv 或 .venv）
python -m venv venv

# Windows 激活虚拟环境
venv\Scripts\activate

# macOS/Linux 激活虚拟环境
source venv/bin/activate

激活后，命令行前面会显示虚拟环境名称：

(venv) $

退出虚拟环境​

deactivate

安装 Django​

在虚拟环境激活的状态下安装 Django：

# 安装最新版本
pip install django

# 安装指定版本
pip install django==5.0

# 安装开发版本
pip install django@git+https://github.com/django/django.git#egg=django

验证安装：

python -m django --version
# 或
django-admin --version

项目结构最佳实践​

推荐的项目目录结构：

myproject/
├── venv/                   # 虚拟环境（不提交到版本控制）
├── .gitignore              # Git 忽略文件
├── requirements.txt        # 项目依赖
├── README.md               # 项目说明
├── myproject/              # 项目配置目录
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── manage.py               # 管理脚本
└── apps/                   # 应用目录
    ├── __init__.py
    └── myapp/
        ├── __init__.py
        ├── admin.py
        ├── apps.py
        ├── models.py
        ├── views.py
        └── migrations/

requirements.txt 管理​

使用 requirements.txt 文件记录项目依赖：

# 导出当前环境的所有依赖
pip freeze > requirements.txt

# 从 requirements.txt 安装依赖
pip install -r requirements.txt

一个典型的 requirements.txt 文件：

Django==5.0
Pillow==10.2.0
django-crispy-forms==2.1
python-dotenv==1.0.0

配置开发工具​

VS Code 配置​

安装 Python 扩展后，创建 .vscode/settings.json：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/Scripts/python.exe",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "editor.formatOnSave": true
}

PyCharm 配置​

  1. 打开项目设置（Settings/Preferences）
  2. 进入 Project: xxx > Python Interpreter
  3. 点击齿轮图标 > Add
  4. 选择 Existing environment，指定虚拟环境中的 Python 解释器

常见问题​

1. pip 安装速度慢​

使用国内镜像源加速：

# 临时使用
pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

常用国内镜像：

2. Windows 上脚本执行权限问题​

如果遇到 "无法加载文件，因为在此系统上禁止运行脚本" 错误：

# 以管理员身份运行 PowerShell，执行：
Set-ExecutionPolicy RemoteSigned

3. 虚拟环境激活后 pip 仍然使用系统 Python​

确保使用虚拟环境中的 pip：

# 检查 pip 路径
which pip    # macOS/Linux
where pip    # Windows

# 应该指向虚拟环境目录
# 例如：/path/to/venv/bin/pip

4. Python 版本管理​

如果需要在同一系统上管理多个 Python 版本，可以使用：

  • pyenv（macOS/Linux）：管理多个 Python 版本
  • pyenv-win（Windows）：Windows 版 pyenv
  • conda：Anaconda/Miniconda 提供的环境管理工具
# 使用 pyenv 安装 Python
pyenv install 3.12.0
pyenv local 3.12.0

下一步​

环境配置完成后，接下来学习如何创建第一个 Django 项目。