Django开发环境搭建全攻略：从Python配置到项目优化-代码聚汇网

Django开发环境搭建全攻略：从Python配置到项目优化

FFFire小火·2026-08-25·阅读 23 GEO检测（免费）

DjangoPython虚拟环境

|难度：普通|阅读约 23 分钟

1. 环境准备：从零开始搭建Django开发环境

作为一个使用Django多年的开发者，我深知环境配置这个看似简单的步骤实际上暗藏玄机。很多新手在第一步就踩坑，导致后续开发过程问题频出。今天我就带大家完整走一遍Django环境准备的正确姿势，包括那些官方文档不会告诉你的细节。

Django作为Python最流行的Web框架之一，环境准备涉及Python版本管理、虚拟环境隔离、依赖管理等多个环节。我会基于最新的Django 4.2 LTS版本进行说明，同时兼顾Python 3.8+的兼容性问题。无论你是完全的新手，还是从其他框架转过来的开发者，这套配置方案都能让你少走弯路。

提示：本文所有命令均在Linux/macOS终端和Windows PowerShell测试通过，遇到问题可以先检查终端类型和权限

1.1 Python版本选择与安装

Django 4.2官方支持Python 3.8、3.9、3.10和3.11。我强烈建议使用Python 3.10作为起点，它在性能和稳定性上达到了很好的平衡。以下是各平台的具体安装方法：

Windows系统：

访问Python官网下载3.10.x版本的安装包
安装时务必勾选"Add Python to PATH"选项
安装完成后，在PowerShell运行python --version验证

macOS系统：

bash复制# 推荐使用Homebrew安装
brew install python@3.10
echo 'export PATH="/usr/local/opt/python@3.10/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux系统(Ubuntu/Debian)：

bash复制sudo apt update
sudo apt install python3.10 python3.10-venv
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1

常见坑点：很多Linux发行版默认的python3命令指向的是较旧版本，必须手动更新alternatives配置

1.2 虚拟环境配置最佳实践

Python虚拟环境是项目隔离的基石。我见过太多人因为省略这一步，导致不同项目依赖冲突而抓狂。以下是经过实战检验的配置流程：

bash复制# 创建项目目录并进入
mkdir django_project && cd django_project

# 创建虚拟环境（推荐使用venv模块）
python3.10 -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Unix/macOS:
source venv/bin/activate

激活后，你的命令行提示符前应该显示(venv)，表示已处于虚拟环境中。我习惯在项目根目录下创建.env文件存放环境变量，这是比直接修改settings.py更安全的做法：

bash复制echo "DJANGO_SETTINGS_MODULE=config.settings.local" > .env
echo "PYTHONPATH=$PWD" >> .env

1.3 Django安装与验证

在虚拟环境中，使用pip安装Django：

bash复制pip install django==4.2.0

安装完成后，验证安装是否成功：

bash复制python -m django --version
# 应该输出4.2.x

我强烈建议同时安装这些开发必备工具：

bash复制pip install ipython black flake8 isort pylint-django

这些工具分别提供了：

IPython：增强的交互式Python shell
Black：自动代码格式化
Flake8：代码风格检查
isort：导入语句排序
pylint-django：Django专属的静态代码分析

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 项目骨架创建与基础配置

2.1 创建Django项目的正确姿势

很多教程会教你直接运行django-admin startproject projectname，但实际项目中我们需要更结构化的方式：

bash复制django-admin startproject config .

注意最后的点号表示在当前目录创建项目。这种结构将配置文件放在config目录中，更符合现代Django项目的实践。生成的文件结构应该是：

code复制.
├── config/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── manage.py

2.2 基础配置调优

打开config/settings.py，首先找到ALLOWED_HOSTS，开发阶段可以这样设置：

python复制ALLOWED_HOSTS = ["localhost", "127.0.0.1"]

然后是数据库配置，开发阶段使用SQLite即可：

python复制DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

我强烈建议添加这些基础配置：

python复制# 时区设置
TIME_ZONE = "Asia/Shanghai"
USE_TZ = True

# 静态文件配置
STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

# 媒体文件配置
MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"

2.3 创建第一个应用

Django的项目(project)和应用(app)概念需要明确区分。让我们创建一个名为"core"的基础应用：

bash复制python manage.py startapp core

创建后需要在settings.py的INSTALLED_APPS中添加：

python复制INSTALLED_APPS = [
    ...,
    "core.apps.CoreConfig",
]

专业建议：不要直接在项目根目录下创建应用，而是建立一个apps目录存放所有应用，这样结构更清晰。可以使用mkdir apps && cd apps && python ../manage.py startapp core实现

3. 开发工具链配置

3.1 配置VS Code开发环境

如果你使用VS Code，这些配置能极大提升开发体验：

安装官方Python扩展
创建.vscode/settings.json：

json复制{
    "python.pythonPath": "venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.languageServer": "Pylance",
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": true
    },
    "python.analysis.typeCheckingMode": "basic"
}

3.2 数据库可视化工具

虽然Django自带admin，但开发时使用DB Browser for SQLite或TablePlus等工具能更直观地查看数据。

3.3 必备的Django调试工具

安装这些调试工具能极大提升开发效率：

bash复制pip install django-debug-toolbar django-extensions

然后在settings.py中添加：

python复制INSTALLED_APPS += [
    "debug_toolbar",
    "django_extensions",
]

MIDDLEWARE = [
    "debug_toolbar.middleware.DebugToolbarMiddleware",
    ...
]

INTERNAL_IPS = ["127.0.0.1"]

配置完成后，访问任何页面都能看到调试工具栏，可以查看SQL查询、模板渲染等详细信息。

4. 项目结构优化与最佳实践

4.1 拆分settings.py

随着项目增长，单一的settings.py会变得难以维护。我推荐按环境拆分：

code复制config/
    settings/
        __init__.py
        base.py
        local.py
        production.py

拆分步骤：

创建config/settings目录
将原settings.py重命名为base.py并移入该目录
创建local.py和production.py
在manage.py和wsgi.py中修改DJANGO_SETTINGS_MODULE指向

4.2 自定义用户模型

如果你需要扩展用户模型，一定要在项目开始时就设置好：

python复制# core/models.py
from django.contrib.auth.models import AbstractUser

class User(AbstractUser):
    pass

然后在settings.py中配置：

python复制AUTH_USER_MODEL = "core.User"

重要：这个配置必须在第一次迁移之前完成，否则后期修改会非常麻烦

4.3 配置日志系统

合理的日志配置对调试和生产运维都至关重要：

python复制LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "verbose": {
            "format": "{levelname} {asctime} {module} {message}",
            "style": "{",
        },
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "verbose",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "INFO",
    },
}

5. 初始化项目与常见问题排查

5.1 执行初始迁移

配置完成后，运行以下命令初始化数据库：

bash复制python manage.py migrate
python manage.py createsuperuser

5.2 运行开发服务器

启动开发服务器：

bash复制python manage.py runserver

访问http://localhost:8000/admin 可以进入后台，http://localhost:8000 会看到Django欢迎页面。

5.3 常见问题解决方案

问题1：ModuleNotFoundError: No module named '...'

检查虚拟环境是否激活
检查PYTHONPATH是否包含项目根目录
确保在正确目录下运行命令

问题2：数据库表已存在错误

bash复制python manage.py migrate --fake

问题3：静态文件404

bash复制python manage.py collectstatic

问题4：端口被占用

bash复制python manage.py runserver 8001

6. 进阶准备：为生产环境打基础

虽然现在是开发环境，但提前考虑生产环境配置能避免后期大量重构工作。

6.1 配置requirements文件

创建requirements目录并拆分依赖：

code复制requirements/
    base.txt
    local.txt
    production.txt

base.txt包含所有环境共有的依赖：

code复制Django==4.2.0
psycopg2-binary==2.9.5  # PostgreSQL驱动

local.txt包含开发专用工具：

code复制-r base.txt
ipython==8.10.0
black==23.3.0
django-debug-toolbar==3.8.1

6.2 配置Docker开发环境

即使生产环境不用Docker，开发时使用Docker也能保证环境一致性。创建Dockerfile：

dockerfile复制FROM python:3.10-slim

WORKDIR /app

ENV PYTHONUNBUFFERED 1
ENV PYTHONPATH /app

RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

COPY requirements /requirements
RUN pip install --no-cache-dir -r /requirements/local.txt

COPY . /app

以及docker-compose.yml：

yaml复制version: "3.8"

services:
  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DJANGO_SETTINGS_MODULE=config.settings.local

6.3 配置Git忽略文件

合理的.gitignore能避免将不必要的文件纳入版本控制：

code复制# .gitignore
*.pyc
*~
__pycache__
db.sqlite3
/media
/staticfiles
.env
venv/
.idea/
.vscode/

7. 开发工作流优化建议

7.1 自动化代码格式化

在项目根目录创建.pre-commit-config.yaml：

yaml复制repos:
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        language_version: python3.10
  - repo: https://github.com/PyCQA/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

然后安装pre-commit：

bash复制pip install pre-commit
pre-commit install

7.2 自定义管理命令

创建自定义命令可以封装常用操作。例如创建core/management/commands/initproject.py：

python复制from django.core.management.base import BaseCommand

class Command(BaseCommand):
    help = "Initialize project with default data"

    def handle(self, *args, **options):
        # 初始化逻辑
        self.stdout.write(self.style.SUCCESS("Project initialized successfully"))

7.3 配置Django Shell增强

在settings.py中添加：

python复制SHELL_PLUS = "ipython"
SHELL_PLUS_PRINT_SQL = True

然后使用python manage.py shell_plus启动增强版shell，会自动加载所有模型并提供SQL打印功能。

经过以上步骤，你已经建立了一个专业级的Django开发环境。这套配置不仅适用于当前项目，也可以作为后续所有Django项目的模板。记住，好的开始是成功的一半，在环境准备阶段多花些时间，能避免后续开发中的许多麻烦。