Django从零开始（一）：环境搭建与第一个项目

Django 4 小时前 0 2

一、Django简介

Django是一个开源的Python Web框架，遵循MVT（Model-View-Template）架构模式，由Django Software Foundation维护。它以"快速开发"和"不重复造轮子（DRY）"为设计哲学，帮助开发者在短时间内构建高质量的Web应用。

Django的核心特点

强大的ORM：无需手写SQL，通过Python对象操作数据库，支持PostgreSQL、MySQL、SQLite、Oracle等多种数据库
自带Admin后台：开箱即用的管理后台，几行代码即可生成数据管理界面
安全性高：内置防护XSS、CSRF、SQL注入、点击劫持等常见Web攻击
URL路由系统：优雅的URL设计，支持正则表达式和路径转换器
模板引擎：内置模板系统，支持继承、标签、过滤器
中间件机制：灵活的请求/响应处理管道
缓存框架：支持多种缓存后端（Redis、Memcached等）
国际化支持：内置多语言、时区处理

Django适用场景

内容管理系统（CMS）
社交网络平台
数据分析和可视化平台
电商平台
RESTful API后端服务
企业内部管理系统

二、Python环境准备

2.1 Python版本选择

Django 5.x 需要 Python 3.10 及以上版本。建议使用最新的 Python 3.12 稳定版：

# 检查Python版本
python3 --version
# Python 3.12.x

2.2 创建虚拟环境

虚拟环境可以隔离项目依赖，避免不同项目之间的包版本冲突。推荐使用 venv（Python内置）：

# 创建项目目录
mkdir myproject && cd myproject

# 创建虚拟环境
python3 -m venv venv

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

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

# 激活后终端会显示虚拟环境名称
# (venv) user@host:~/myproject$

如果你的项目较多，也可以使用 virtualenvwrapper 来统一管理：

# 安装 virtualenvwrapper
pip install virtualenvwrapper

# 配置环境变量（添加到 ~/.bashrc）
export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
source /usr/local/bin/virtualenvwrapper.sh

# 创建虚拟环境
mkvirtualenv myproject

# 切换虚拟环境
workon myproject

# 退出虚拟环境
deactivate

三、安装Django

# 安装最新版Django
pip install django

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

# 验证安装
python -m django --version
# 5.1

# 查看已安装的Django信息
pip show django

建议使用国内镜像加速安装：

# 使用清华镜像
pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple

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

四、创建第一个Django项目

4.1 使用django-admin创建项目

# 创建项目
django-admin startproject mysite

# 进入项目目录
cd mysite

# 查看项目结构
tree
.
├── manage.py          # Django命令行工具
└── mysite/            # 项目配置目录
    ├── __init__.py    # Python包标识
    ├── settings.py    # 项目配置文件
    ├── urls.py        # 根URL路由配置
    ├── asgi.py        # ASGI配置（异步服务器）
    └── wsgi.py        # WSGI配置（同步服务器）

4.2 项目文件详解

manage.py：Django的命令行管理工具，常用命令包括：

# 运行开发服务器
python manage.py runserver

# 创建数据库迁移文件
python manage.py makemigrations

# 执行数据库迁移
python manage.py migrate

# 创建超级管理员
python manage.py createsuperuser

# 进入Django Shell
python manage.py shell

# 收集静态文件
python manage.py collectstatic

settings.py：项目的核心配置文件，包含数据库、中间件、模板、静态文件等所有配置。

urls.py：项目的URL路由入口，定义URL与视图函数的映射关系。

wsgi.py / asgi.py：分别用于同步和异步部署的入口文件。

五、创建第一个App

Django项目中，App 是功能模块的集合。一个项目可以包含多个App，每个App负责一个独立的功能模块。

# 创建名为blog的App
python manage.py startapp blog

# 查看App结构
tree blog/
blog/
├── __init__.py        # Python包标识
├── admin.py           # Admin后台注册配置
├── apps.py            # App配置类
├── migrations/        # 数据库迁移文件目录
│   └── __init__.py
├── models.py          # 数据模型定义
├── tests.py           # 测试文件
└── views.py           # 视图函数

5.1 注册App到项目

创建App后，需要在 settings.py 中注册：

# mysite/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'blog',  # 添加我们创建的blog应用
]

六、运行开发服务器

# 运行开发服务器（默认8000端口）
python manage.py runserver

# 指定端口
python manage.py runserver 8080

# 指定IP和端口（允许外部访问）
python manage.py runserver 0.0.0.0:8000

# 输出信息
# Watching for file changes with StatReloader
# Performing system checks...
# System check identified no issues (0 silenced).
# April 24, 2026 - 18:00:00
# Django version 5.1, using settings 'mysite.settings'
# Starting development server at http://127.0.0.1:8000/
# Quit the server with CONTROL-C.

打开浏览器访问 http://127.0.0.1:8000/，你将看到Django的欢迎页面，上面有一行火箭发射的动画，说明项目创建成功！

七、编写第一个视图（Hello World）

打开 blog/views.py，编写第一个视图函数：

# blog/views.py

from django.http import HttpResponse, JsonResponse
from datetime import datetime


def index(request):
    """首页视图 - 返回简单的Hello World"""
    return HttpResponse("<h1>Hello, Django!</h1><p>欢迎来到Django的世界！</p>")


def about(request):
    """关于页面"""
    content = """
    <html>
    <head><title>关于我们</title></head>
    <body>
        <h1>关于我们</h1>
        <p>这是一个Django学习项目</p>
        <p>当前时间: {}</p>
    </body>
    </html>
    """.format(datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
    return HttpResponse(content)


def api_info(request):
    """返回JSON格式的API响应"""
    data = {
        "name": "Django学习项目",
        "version": "1.0",
        "description": "从零开始学习Django",
        "time": datetime.now().isoformat()
    }
    return JsonResponse(data)

八、配置URL路由

8.1 创建App级别的URL配置

在blog目录下创建 urls.py：

# blog/urls.py

from django.urls import path
from . import views

# app_name定义应用的命名空间，方便模板中反向解析URL
app_name = 'blog'

urlpatterns = [
    path('', views.index, name='index'),
    path('about/', views.about, name='about'),
    path('api/info/', views.api_info, name='api_info'),
]

8.2 在项目URL中包含App路由

# mysite/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('blog/', include('blog.urls')),  # 包含blog应用的URL配置
]

现在访问以下URL可以看到效果：

http://127.0.0.1:8000/blog/ - Hello World页面
http://127.0.0.1:8000/blog/about/ - 关于页面
http://127.0.0.1:8000/blog/api/info/ - JSON API

九、settings.py核心配置详解

9.1 基础配置

# mysite/settings.py

# SECRET_KEY：密钥，用于加密签名，生产环境务必保密
SECRET_KEY = 'django-insecure-your-secret-key-here'

# DEBUG：调试模式，生产环境必须设为False
DEBUG = True

# ALLOWED_HOSTS：允许访问的主机名/域名
# 生产环境需要添加实际域名
ALLOWED_HOSTS = ['localhost', '127.0.0.1', 'yourdomain.com']

9.2 数据库配置

# 默认SQLite配置
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

# MySQL配置（需要安装 mysqlclient）
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'mydatabase',
        'USER': 'myuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
        }
    }
}

# PostgreSQL配置（需要安装 psycopg2）
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydatabase',
        'USER': 'myuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

9.3 国际化和时区配置

# 语言设置
LANGUAGE_CODE = 'zh-hans'  # 简体中文

# 时区设置
TIME_ZONE = 'Asia/Shanghai'  # 中国标准时间

# 是否启用时区支持
USE_I18N = True  # 国际化
USE_L10N = True  # 本地化
USE_TZ = True    # 启用时区（推荐开启）

9.4 静态文件配置

# 静态文件URL前缀
STATIC_URL = '/static/'

# 静态文件收集目录（collectstatic命令的目标目录）
STATIC_ROOT = BASE_DIR / 'staticfiles'

# 额外的静态文件目录
STATICFILES_DIRS = [
    BASE_DIR / 'static',
]

# 媒体文件配置（用户上传文件）
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

十、Django开发工具推荐

10.1 VSCode插件

Django：Django语法高亮和代码补全
Python：Microsoft官方Python插件
Pylance：类型检查和智能提示
Django Snippets：常用代码片段快捷输入
SQLite Viewer：直接查看SQLite数据库

10.2 Django Debug Toolbar

# 安装
pip install django-debug-toolbar

# settings.py 配置
INSTALLED_APPS = [
    ...
    'debug_toolbar',
]

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

# 仅在DEBUG模式下启用
if DEBUG:
    INTERNAL_IPS = ['127.0.0.1']

# urls.py 添加路由
if settings.DEBUG:
    import debug_toolbar
    urlpatterns += [path('__debug__/', include(debug_toolbar.urls))]

十一、常见问题与解决方案

问题1：pip安装Django超时

# 使用国内镜像源
pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或者使用阿里云镜像
pip install django -i https://mirrors.aliyun.com/pypi/simple/

问题2：运行时报ModuleNotFoundError

确保已激活虚拟环境：

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

# 确认Django已安装
pip list | grep -i django

问题3：迁移数据库报错

# 按顺序执行
python manage.py makemigrations
python manage.py migrate

# 如果还有问题，查看具体SQL
python manage.py sqlmigrate blog 0001

问题4：端口被占用

# 查看占用8000端口的进程
lsof -i :8000

# 杀掉进程
kill -9 PID

# 或者使用其他端口
python manage.py runserver 8080

十二、总结

本章我们完成了以下内容：

了解了Django框架的特点和适用场景
搭建了Python虚拟环境并安装Django
创建了第一个Django项目和应用
编写了Hello World视图并配置URL路由
详解了settings.py核心配置项
推荐了开发工具和调试方法

下一章我们将深入学习 Django的模型层（Model）和ORM数据库操作，学习如何通过Python代码定义数据表结构并进行增删改查操作。

完整代码已上传至GitHub，建议跟着教程动手实践，边学边写代码效果最佳！

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

Django教程