Python Django H5 MySQL 项目搭建全流程

在搭建一个 Django + H5 前端 + MySQL 后端项目时常见的痛点包括：环境依赖冲突、虚拟环境未激活导致包找不到、路由配置错误、模板方法不匹配、静态文件在生产环境无法访问。下面按步骤给出完整的方法，方便你落地。

环境安装与验证

Python 是解释型语言，需要先安装解释器。怎么说呢，推荐使用官方源：

# 下载 & 安装
curl -O https://www.python.org/ftp/python/3.12.4/python-3.12.4-amd64.exe
# 验证
python --version # Windows
python3 --version # macOS/Linux

安装完成后立即验证版本。避免后期因版本不匹配导致的奇怪报错。

创建 Django 项目

Django 提供两种常用创建方式：命令行和 IDE。下面演示最稳妥的命令行方式。

基于命令行创建

# 先全局安装 Django
pip install django
# 在项目根目录执行：
django-admin startproject MyBlog .

说到提示。如果你使用的是 Windows，确保脚本方法中没有空格；若出现 “CommandNotFoundError”，请检查 pip 是否已添加到 PATH。按理说，

使用 PyCharm 创建

PyCharm 能自动为你生成项目结构并配置虚拟环境。适合不熟悉命令行的新手，

配置虚拟环境

虚拟环境能隔离不同项目的依赖，避免“PackageNotFoundError”。其实，推荐使用 Python 自带的 venv：

# 在项目根目录下创建虚拟环境
python -m venv myenv
# 激活虚拟环境
myenv\Scripts\activate
# 激活虚拟环境
source myenv/bin/activate
# 安装依赖
pip install django mysqlclient # mysqlclient 用于连接 MySQL
# 开发完成后退出
deactivate

IDE 绑定虚拟环境

• Setting → Project → Python Interpreter → Add Interpreter → Existing Environment → choose myenv/bin/python 或 myenv\Scripts\python.exe
• 绑定成功后所有终端命令都会在该 env 下执行。
• 如果你更习惯在终端操作，可以在 VS Code 的终端中选择同一 env。

目录结构与关键文件说明

MyBlog/
├── manage.py # Django CLI 工具入口
├── db.sqlite3 # 开发时默认 SQLite 数据库，可忽略或删除
├── myenv/ # 虚拟环境目录
│ ├── Scripts/ # 激活脚本
│ └── Lib/
├── MyBlog/ # 项目配置包
│ ├── __init__.py
│ ├── settings.py # 全局配置文件
│ ├── urls.py # 项目级路由表
│ ├── wsgi.py # WSGI 入口。用于部署到 Gunicorn/uWSGI 等
│ └── asgi.py # ASGI 入口，用于异步支持
└── apps/ # 自定义应用目录
└── user/
├── __init__.py
├── apps.py # App 配置类，需要添加到 INSTALLED_APPS 中
├── models.py # 数据模型定义文件
├── views.py # 视图函数 / 类视图文件
├── urls.py # App 路由表，可选；若存在需 include 到项目 urls 中
├── admin.py # 后台管理注册文件
└── migrations/ # 自动生成迁移记录夹

关键文件作用快速梳理：

app 注册与设置检查清单

• # 确认 app 名称正确：apps.user.apps.UserConfig，而不是错误写法 apps.user.UserConfig 或者只写 user。错误注册会导致 “AppRegistryNotReady” 报错。
• # 同时记得把自定义模型所在 app 加入到数据库迁移前的 INSTALLED_APPS 列表里否则 makemigrations 会报 “no changes detected”。
• # 如果你把 app 放在 apps/ 子目录下请确保相对方法正确。
• # 对照 settings.INSTALLED_APPS 顺序，如果顺序不对会影响权限、signals 等初始化逻辑。话说回来，
• # 一般建议把第三方插件放在最前面再放自己的 app。以免覆盖冲突，
• # 示例

  INSTALLED_APPS =
  

  } } – 请确认引号内无多余空格或换行符。 再看**注**，如果忘记加入 `apps.user`。`makemigrations` 和 `migrate` 都不会产生任何变化。

  ---

  💡 常见痛点汇总：

  痛点	场景	快速定位	修复建议
  包找不到	运行 python manage.py runserver 报 ModuleNotFoundError	未激活 virtualenv 或 pip 安装到了程序 Python	在当前 shell 下执行 source myenv/bin/activate 并 运行
  路由匹配失败	访问 /user/list/ 返回 404	方法未包含 /urls.py> 或 include 写错了	确认 /urls.py 存在且已被主路由导入
  模板渲染为空	页面显示空白或模板未找到错误	模板方法不正确；说起来，APP 未开启 APP_DIRS=True 或没有 templates 文件夹	在 settings.TEMPLATES 中加入绝对方法或确认 APP 内有 /templates//... .html
  静态资源缺失	页面图片无法加载。仅显示占位图	静态资源未收集或 Nginx 配置错误；DEBUG=False 时 Django 不再自动服务静态文件	执行 python manage.py collectstatic;配置 Nginx alias 指向 STATIC_ROOT

  ---

  📌 步骤一：新建 APP 并注册到 INSTALLED_APPS 中

  bash cd MyBlog # 确保位于项目根目录下 python manage.py startapp user // 创建单独 APP **如果你想把 APP 放入自定义 folder 如 apps/user** bash mkdir -p apps && cd apps && python ../manage.py startapp user . 接下来修改 `/apps.py` python class UserConfig: default_auto_field = 'django.db.models.BigAutoField' name = 'apps.user' # 必须指向完整包名，否则会抛异常！最终将其加入 `/settings.py` python INSTALLED_APPS =

  ---

  📌 步骤二：模型设计 & 数据库迁移

  1️⃣ 模型定义

  python from django.db import models class User: username = models.CharField password = models.CharField email = models.EmailField create_time = models.DateTimeField update_time = models.DateTimeField

  def __str__:
  return self.username
  

  *Tip这方面。* 对字段加上合适长度限制，防止数据存储异常。说起来，

  2️⃣ 配置数据库

  python DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql','NAME': 'django_test'。'USER': 'root','PASSWORD': '','HOST': '127.0.0.1','PORT': '',// 默认为3306，可省略 } } *⚠️ 注意*：MySQL8.x 要求 `mysqlclient>=1.x`;若遇到 “Unable to load _mysql module” 错误，请先确保程序已安装 libmysqlclient-dev / Homebrew mysql-client。

  3️⃣ 生成迁移 & 执行迁移

  bash python manage.py makemigrations // 创建 migration 文件夹/apps/user/migrations/*.py python manage.py migrate // 将表同步至数据库 *常见错误*这方面，- **No changes detected** ：忘记保存模型或未将 APP 添加至 INSTALLED_APPS。- **OperationalError: Can't connect to server …其实，** ：MySQL 服务未启动或使用者名密码不匹配。

  ---

  📌 步骤三：编写视图 & 路由映射

  A) 简单视图

  python from django.http import HttpResponse,JsonResponse def list: return HttpResponse

  B) 定义 App 路由

  python from django.urls import path from . import views urlpatterns =

  C) 主路由导入

  python from django.urls import path。include urlpatterns =

  ---

  📌 步骤四：模板渲染与继承

  A) 创建模板目录和页面

  每个 App 可拥有自己的 templates 文件夹： text apps/user/templates/user.html 内容示例的观点是，{% load static %}
  {% block content %} 欢迎来到使用者页面！{% endblock %}
  ©2026 Demo Site. {% if some_flag %}
  Flag True!说起来，
  {% endif %}

  {'% block header '%}'}

  {'% block main_content '%}'}
  {'% block footer '# ©2026 Demo Site'{%'endblock'%}'}

  ";，>

  <% for item in items:%>

  <% if item.active:%>

  <% endif:%>

  ...

  ©2027 Demo Site All rights reserved. ©2027 Demo Site All rights reserved. ©2027 Demo Site All rights reserved. ©2027 Demo Site All rights reserved. ©2027 Demo Site All rights reserved. ©2027 Demo Site All rights reserved.

  * End of Sample * `.trim;var f=document.createElement;f.innerHTML=''+JSON.stringify+'<\/button>';document.body.appendChild;

  接下来让子模板继承:

  child.html 示例:

  html {% extends "base.html" %} {% block title %)User Page{%endblock title%) } {% block main_content %)欢迎进入使用者首页！{%endblock main_content%) } ... ... @endsection; ✅ 小技巧: 使用 {%% extends %%} 前要先保证 base.html 已经存在而且方法正确，否则会抛 “TemplateDoesNotExist”。

  ---

  最终完整流程

  环境准备

  bash

  pip install django mysqlclient pillow gunicorn nginx # sudo apt-get install nginx # brew install nginx # sudo systemctl enable nginx # sudo systemctl start nginx #

  cd ~/workspace && mkdir MyBlog && cd MyBlog #

  git init && git add . && git commit -m "Initial commit"

  python -m venv myenv && source myenv/bin/activate

  pip install django mysqlclient pillow gunicorn ngnix-nginx-config-generator==0.x.x \ ipython tqdm pandas matplotlib seaborn \ pyjwt cryptography bcrypt psycopg

  pip freeze> requirements.txt #

  django-admin startproject MyBlog .

  mkdir -p apps && cd apps && python ../managepy startapp user . sed -i '/name/d' apps/user/apps.yaml || true # sed -i "/^name/d;/^defaultautofield/d;/^label/d，/^verbosename/d;/^proxy/d，其实，/^ordering/d;/^uniquetoger/d;/^indextoger/d;/^db_table/d;/^managed/d/" apps/user/apps.yaml || true sed -i "/name/s/'*/'apps.user'/g;" apps/user/apps.yaml

  sed -i "/INSTALLED_APPS/a \\t'settings.apps.user.apps.UserConfig'," settings/init.py?，?，

  export PYTHONPATH=$PYTHONPATH:/path/to/MyBlog #

  cd ..

  echo " INSTALLED_APPS=

  DATABASES={ 'default': {'ENGINE':'django.db.backends.mysql','NAME':'django_test','USER':'root','PASSWORD':'',\ 从'HOST'来看，'127.0.0.1','PORT':''},}

  STATICURL='/static/' STATICROOT=os.path.join STATICFILES_DIRS=

  TEMPLATES=,'APPDIRS':True。\ OPTIONS:{'contextprocessors':}},]

  MIDDLEWARE= "

  touch templates/base.html ... touch templates/home.html ...

  echo ' def list: return HttpResponse def list_page: return render'

  echo ' urlpatterns='

  #

  RUN ALL BELOW

  #

  source my.env/bin activate ## Activate again just in case!cd ~/workspace/MyBlog ## Ensure correct dir!./managepy makemigrations ## Generate migrations based on your model definition!，./managepy migrate ## Create tables in database!，./managepy createsuperuser ## Create super admin!，./managepy runserver ## Run dev server!，!' echo "Done!Open http://localhost:8000/admin and http://localhost:user/list/"

  #

  Production Deploy Setup ------------------------------

  #

  gunicorn --workers=4 --bind unix:/tmp/gunicorn.sock wsgi & sudo service nginx restart ### reload config!

  #

  Static Files Collection ------------------------

  #

  ./managepy collectstatic ### copy all assets into ./staticbuild/

  #

  Config Nginx -------------------------------

  cat > /etc/nginx/sites-enabled/myblog.conf EOFCONTENTHERE

  sudo service nginx reload ### reload config again!

  #

  #

  DONE

  #

  * End of Quick Start * .trim;document.title=Quick Start Completed;var b=document.createElement;b.textContent=a.split.slice.join;document.body.appendChild;.trim;var g=document.createElement;document.body.appendChild;var c=document.createElement;老实说，c.textContent=You can copy/paste this entire snippet into your terminal or IDE environment.;document.body.appendChild;.trim;var d=document.createElement;document.body.appendChild;按理说，var i=document.createElement;i.innerHTML=If you encounter any issues during process:

  \
  • If you get an error about missing packages after running `${String.fromCharCode}${String.fromCharCode}`,check that you are in correct virtual environment.
  \
  • If database connection fails with `${String.fromCharCode}${String.fromCharCode}`。verify that your MySQL service is running and credentials match.
  \
  • If a template cannot be found after adding it to your project,ensure that your application is listed under `${String.fromCharCode}${String.fromCharCode}`.` + '
  ';document.body.appendChild;