⚠️免责声明：本文项目仅供技术学习参考，严禁直接作为毕业设计或课程作业提交。请结合自身需求进行二次开发与创新，学术诚信从我做起 🙂
直接说怎么跑起来
很多同学代码写得还行，一到环境搭建就懵——Python版本不对、依赖装不上、启动报错、数据库连不上。
拢共就四步：先装Python，再给项目整个虚拟环境，pip装依赖，最后flask run。听着没几步，每一步我都栽过。
但每一步都有坑。
流程我按自己踩过的顺序重排了一遍，跟着敲，正常十来分钟能跑起来——慢也就慢在下载依赖那步。
一、环境准备清单
先把需要的工具列出来，一个一个装好：
| 工具 | 版本要求 | 用途 |
|---|---|---|
| Python | 3.8 ~ 3.12 | 运行环境 |
| pip | 最新版 | Python包管理 |
| MySQL（可选） | 5.7 / 8.0 | 数据库（SQLite可选跳过） |
| 编辑器 | VS Code / PyCharm | 写代码 |
| 浏览器 | Chrome / Edge | 测页面 |
为什么Python 3.8 ~ 3.12？
低于3.8很多新特性用不了，高于3.12有些第三方库还没兼容。中间版本最稳。毕设推荐 3.10 或 3.11。
二、Windows 下 Python 安装
1. 下载
去 Python 官网下载：https://www.python.org/downloads/
选 Windows installer (64-bit)，下载 .exe 安装包。
2. 安装
注意第一步最关键：勾选Add Python to PATH。
这个不勾，后面命令行输python找不到，90% 的新手都栽在这一步。
然后点Install Now，默认安装就行。
3. 验证安装成功
打开 CMD（Win + R，输 cmd，回车），输入：
python --version能输出版本号就是装好了。
如果提示 “‘python’ 不是内部或外部命令”，说明PATH没配好，回去重新勾上或者手动加环境变量。
三、虚拟环境：隔离项目依赖
为什么要用虚拟环境？
因为不同项目依赖的库版本不一样——A项目用 Flask 2.x，B项目用 Flask 1.x，混在一起会打架。虚拟环境让每个项目有自己独立的依赖包，互不干扰。
创建虚拟环境
打开 CMD，进到项目目录：
cd D:\myd_shop python -m venv venv这行会在项目目录下创建一个venv文件夹，里面就是这个项目的独立 Python 环境。
激活虚拟环境
venv\Scripts\activate激活成功后，命令行前面会出现(venv)的标识。
退出虚拟环境：
deactivateMac / Linux 用户
cd/your/project/path python3-mvenv venvsourcevenv/bin/activate四、安装项目依赖
项目根目录下应该有个requirements.txt，列出了所有依赖包：
Flask==3.0.0 Flask-SQLAlchemy==3.1.1 Flask-Login==0.6.3 Flask-WTF==1.2.1 Werkzeug==3.0.1 PyMySQL==1.1.0 Pillow==10.1.0 captcha==0.4一键安装：
pip install -r requirements.txt依赖安装常见坑
坑1：下载太慢，超时
用国内镜像源加速：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple常用的国内镜像：
- 清华：https://pypi.tuna.tsinghua.edu.cn/simple
- 阿里云：https://mirrors.aliyun.com/pypi/simple/
- 中科大：https://pypi.mirrors.ustc.edu.cn/simple/
坑2：提示 “Microsoft Visual C++ 14.0 is required”
有些包（比如 Pillow、cryptography）需要编译环境。
解决方法：去微软官网下载 “Build Tools for Visual Studio”，安装时勾选 “C++ 生成工具”。或者直接下载对应包的 whl 文件手动安装。
坑3：版本冲突
如果报 “ERROR: Cannot install … because these package versions have conflicting dependencies”，那就是依赖版本冲突了。
解决方法：先看冲突的是哪两个包，然后调整requirements.txt里的版本号，找到都兼容的版本。
坑4：pip 版本太低
先升级 pip：
python -m pip install --upgrade pip然后再装依赖。
五、数据库配置
毕设推荐两种方案，选一个就行：
方案A：SQLite（最简单，零配置）
SQLite 是文件数据库，不需要装服务，一个文件就是整个数据库。毕设演示完全够用。
配置：
# config.pyimportos BASE_DIR=os.path.abspath(os.path.dirname(__file__))classConfig:SECRET_KEY='your-secret-key-here-change-it'SQLALCHEMY_DATABASE_URI='sqlite:///'+os.path.join(BASE_DIR,'myd_shop.db')SQLALCHEMY_TRACK_MODIFICATIONS=False优点：不用装数据库软件，项目复制到哪都能跑
缺点：并发差（毕设不影响），功能比 MySQL 少
方案B：MySQL（正式一点）
如果答辩老师要求用 MySQL，就用这个。
先装 MySQL（推荐 MySQL 8.0），装完创建数据库：
CREATEDATABASEmyd_shopDEFAULTCHARACTERSETutf8mb4COLLATEutf8mb4_general_ci;配置：
classConfig:SECRET_KEY='your-secret-key-here'SQLALCHEMY_DATABASE_URI='mysql+pymysql://root:你的密码@localhost:3306/myd_shop?charset=utf8mb4'SQLALCHEMY_TRACK_MODIFICATIONS=FalseMySQL 常见坑：
坑1：连接不上，报 Access denied
检查用户名密码对不对、MySQL 服务有没有启动。Windows 下可以在服务里看 MySQL 服务状态。
坑2：报 2003 Can’t connect to MySQL server
MySQL 没启动。去服务里启动 MySQL，或者命令行net start mysql80。
坑3：报 “Unknown charset ‘utf8mb4’”
MySQL 版本太低了，5.5.3 以上才支持 utf8mb4。升级 MySQL，或者把 charset 改成 utf8。
坑4：中文乱码
确保数据库、表、连接都是 utf8mb4。连接串里加上?charset=utf8mb4。
六、初始化数据库表
第一次跑项目，数据库里是空的，需要建表。
方式1：直接执行建表 SQL
把第一篇里的建表 SQL 全部复制到 Navicat 或 phpMyAdmin 里执行。
方式2：用 Flask-Migrate 自动迁移
更专业的做法，用flask db命令自动生成和执行迁移。
# app.py 里初始化fromflask_migrateimportMigratefrommodelsimportdb migrate=Migrate(app,db)然后命令行执行：
flask db init # 初始化迁移目录（第一次才需要） flask db migrate -m "init" # 生成迁移文件 flask db upgrade # 执行迁移，建表以后加字段、改表结构，就再跑flask db migrate和flask db upgrade。
答辩时我提了句"用的Flask-Migrate做迁移"，老师果然多问了两句表结构怎么改的——这个词值几分印象分。
方式3：代码里直接 create_all
最简单粗暴：
# app.py 最后加withapp.app_context():db.create_all()应用启动时自动建表。缺点是改表结构的时候不会自动更新，适合项目初期快速跑起来。
七、创建管理员账号
后台管理需要一个管理员账号，写个初始化脚本：
# init_admin.pyfromappimportapp,dbfrommodelsimportAdminfromwerkzeug.securityimportgenerate_password_hashwithapp.app_context():# 检查是否已有管理员ifAdmin.query.filter_by(username='admin').first():print('管理员已存在')else:admin=Admin(username='admin',password=generate_password_hash('admin123'),role='super')db.session.add(admin)db.session.commit()print('管理员创建成功：admin / admin123')运行：
python init_admin.py毕设演示的时候，管理员账号密码简单点就行——admin / admin123，记起来方便。
八、启动项目
开发模式启动
set FLASK_APP=app.py set FLASK_DEBUG=True flask runMac / Linux：
exportFLASK_APP=app.pyexportFLASK_DEBUG=True flask run或者直接在app.py底部写：
if__name__=='__main__':app.run(debug=True,host='0.0.0.0',port=5000)然后直接python app.py就行。
host='0.0.0.0'的意思是允许局域网访问——答辩的时候老师想用他自己的电脑访问你的项目，用这个就能通过你的IP访问。
访问地址
打开浏览器，输入：
- 前台首页：http://127.0.0.1:5000/
- 后台管理：http://127.0.0.1:5000/admin/login
九、常见启动报错排查
报错1：ModuleNotFoundError: No module named 'flask'
原因：没装依赖，或者没激活虚拟环境。
解决：先激活虚拟环境（venv\Scripts\activate），再pip install -r requirements.txt。
报错2：ImportError: cannot import name 'secure_filename' from 'werkzeug.utils'
原因：Werkzeug 版本太新，secure_filename移到了werkzeug.utils下面的别的位置（其实新版本还在 utils 里，这个一般是版本不兼容）。
解决：降低 Werkzeug 版本pip install werkzeug==2.3.7，或者按 Flask 版本对应的 Werkzeug 版本装。
报错3：sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: user
原因：数据库里没有表，还没初始化。
解决：执行建表 SQL 或者跑db.create_all()。
报错4：Address already in use
原因：5000 端口被占用了——可能上一个 Flask 进程没关掉。
解决：
- Windows：
netstat -ano | findstr :5000找到 PID，然后taskkill /F /PID 进程号 - Mac/Linux：
lsof -i :5000找到 PID，kill -9 进程号 - 或者换个端口：
flask run --port 5001
报错5：OSError: [WinError 10013]以一种访问权限不允许的方式做了一个访问套接字的尝试
原因：端口被系统占用或权限不够。
解决：换个端口，比如 8000、8080。
报错6：jinja2.exceptions.TemplateNotFound
原因：模板文件找不到——路径错了，或者文件名不对。
解决：确认 templates 文件夹在正确的位置（app.py 同级目录），模板路径写对了。
报错7：图片上传不了 / 上传后不显示
原因：上传目录不存在 / 路径配置错了 / 静态文件路由没配置。
解决：
- 确保
static/uploads/goods/目录存在 - Flask 自动服务 static 目录下的文件，路径应该是
/static/uploads/goods/xxx.jpg - 检查 Nginx 或开发服务器的静态文件配置
十、毕设演示小贴士
1. 准备几个测试账号
提前注册几个普通用户账号，每个账号里放几个订单、购物车里加点东西，演示的时候直接看，不用现场注册。
2. 准备管理员登录入口
后台地址别藏太深，演示的时候好找。可以在前台页脚放个"管理后台"的链接。
3. 数据别太空
数据库里多塞点测试数据——十几个商品、几个分类、几轮播图、几个订单。页面看起来饱满，老师第一印象好。
4. 用 PyCharm 演示加分
能在 PyCharm 里跑起来，随时能打开代码给老师看，比单纯打开网页效果好得多。
5. 固定启动步骤写成脚本
写个run.bat（Windows）或run.sh（Mac），一键启动，演示的时候不用手敲命令：
@echo off call venv\Scripts\activate set FLASK_APP=app.py set FLASK_DEBUG=True python app.py pause双击就启动，多省事。
启动报错相关，答辩会问什么
1. 为什么要用虚拟环境？
答：虚拟环境可以为每个项目创建独立的Python依赖环境，避免不同项目之间包版本冲突。比如A项目用Flask 2.x，B项目用Flask 3.x，放在同一个全局环境里就会冲突。
2. requirements.txt 是干嘛的？怎么生成？
答：requirements.txt 是项目依赖清单，列出了所有需要安装的Python包及其版本。别人拿到项目后，pip install -r requirements.txt就能一键安装所有依赖。生成命令是pip freeze > requirements.txt。
3. Flask 的 debug 模式有什么用？为什么生产环境不能开？
答：开发时开着确实方便，改完代码自动重启，报错页还能直接看详细堆栈。但线上必须关掉debug——你想啊，那个交互式调试器谁都能在上面敲Python代码，等于把服务器钥匙挂网上了。
4. 为什么数据库连接用配置文件不直接写死在代码里？
答：配置和代码分离是最佳实践——开发环境、测试环境、生产环境的数据库地址、密码都不一样，用配置文件可以根据环境切换，不用改代码。密码等敏感信息也不应该提交到代码仓库里。
5. 数据库迁移工具有什么用？
答：数据库迁移工具（如 Flask-Migrate / Alembic）可以追踪数据库表结构的变化，生成迁移脚本，支持升级和回滚。项目迭代过程中表结构会不断变化（加字段、改类型），用迁移工具可以有序地管理这些变化，也方便在不同环境之间同步表结构。
环境搭建挺邪门，会的人闭着眼装完，不会的人光一个PATH就能卡半天，我当初就卡过。
其实就那么几个固定的坑，踩过一次就记住了。
上面这些我挨个踩过，照着走基本能起得来；真卡住了，回第九节对着报错表对号入座就行。
梅雅达编程笔记原创 · 首发 CSDN · 转载请注明出处
