2. 开发环境搭建与项目初始化
在开始构建实时监控大屏之前，必须建立标准、可复现的开发环境。本章将引导你完成从 Python 安装到 Git 初始化的完整流程，确保所有学员在相同的技术栈上工作，避免“在我电脑上能跑”的环境差异问题。
2.1 技术栈概览
本项目采用轻量级全栈方案，后端使用 Flask 提供 RESTful API，前端使用 ECharts 进行数据可视化。下表列出了核心依赖及其在本课程中的职责：
| 组件 | 版本建议 | 职责说明 |
|---|---|---|
| Python | 3.10+ | 运行时基础，提供异步支持与类型注解 |
| Flask | 3.0+ | Web 框架，处理路由、请求与模板渲染 |
| Flask-CORS | 4.0+ | 解决前后端跨域请求问题 |
| python-dotenv | 1.0+ | 管理环境变量，分离配置与代码 |
| Gunicorn | 21.2+ | 生产级 WSGI 服务器（部署阶段使用） |
版本选择建议： 建议使用 Python 3.10 及以上版本，因为 3.10 引入了结构模式匹配（match-case）和更清晰的错误提示，这些特性在后续的数据清洗和路由处理中会用到。Flask 3.0 移除了对旧版 Werkzeug 的兼容，强制使用更安全的默认配置。
2.2 安装 Python 与虚拟环境
Python 安装完成后，最关键的一步是创建虚拟环境。虚拟环境为每个项目提供独立的依赖空间，避免不同项目之间的包冲突。
步骤一：创建项目虚拟环境
# 进入项目根目录
cd realtime-monitor-dashboard
# 创建虚拟环境（Windows）
python -m venv venv
# 创建虚拟环境（macOS / Linux）
python3 -m venv venv步骤二：激活虚拟环境
# Windows (CMD)
venv\Scripts\activate
# Windows (PowerShell)
venv\Scripts\Activate.ps1
# macOS / Linux
source venv/bin/activate激活成功后，终端提示符前会出现 (venv) 标识，表示当前处于虚拟环境中。
常见错误： 如果 Windows PowerShell 提示“无法加载文件……因为在此系统上禁止运行脚本”，请以管理员身份运行 PowerShell，执行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 后重试。切勿跳过此步骤直接全局安装依赖。
2.3 项目目录结构设计
良好的目录结构是项目可维护性的基石。本课程采用分层架构，将路由、模型、静态资源和配置分离。下图展示了完整的项目骨架：
核心目录说明
- app/：应用主包，内部按功能拆分为
routes/（路由）、models/（数据模型）、services/（业务逻辑）和static/（静态资源）。 - config/：包含
default.py（通用配置）和production.py（生产环境配置），通过环境变量切换。 - tests/：存放 pytest 测试用例，与
app/目录结构镜像。 - run.py：应用启动入口，加载配置并创建 Flask 实例。
2.4 初始化 Git 仓库
版本控制是团队协作和代码回溯的基础。在项目根目录执行以下命令：
# 初始化 Git 仓库
git init
# 添加所有文件到暂存区
git add .
# 首次提交
git commit -m "chore: 初始化项目结构与虚拟环境"配置 .gitignore
在项目根目录创建 .gitignore 文件，排除虚拟环境、缓存文件和本地配置：
# 虚拟环境
venv/
.venv/
# Python 缓存
__pycache__/
*.pyc
*.pyo
# 环境变量与本地配置
.env
*.local
# IDE 配置
.vscode/
.idea/
# 操作系统文件
.DS_Store
Thumbs.db
最佳实践： 将
.env 加入 .gitignore 可以避免数据库密码、等敏感信息泄露到远程仓库。团队成员之间通过 .env.example 模板共享配置结构。
2.5 配置 requirements.txt
requirements.txt 是 Python 项目的依赖清单，确保所有开发者安装相同版本的包。生成方式有两种：
方式一：手动编写（推荐用于教学）
Flask==3.0.3
Flask-CORS==4.0.1
python-dotenv==1.0.1
gunicorn==21.2.0方式二：自动导出（用于已有环境）
# 激活虚拟环境后执行
pip freeze > requirements.txt
注意： 使用
pip freeze 会导出当前环境中所有已安装的包，包括间接依赖。建议在提交前手动清理，只保留直接依赖项，并在注释中注明用途。例如：# Web 框架、# 跨域支持。
2.6 验证环境
完成上述步骤后，执行以下命令验证环境是否配置正确：
# 检查 Python 版本
python --version
# 输出示例：Python 3.10.12
# 检查虚拟环境是否激活
pip list
# 应只显示基础包和 requirements.txt 中列出的包
# 测试 Flask 是否可导入
python -c "import flask; print(flask.__version__)"
# 输出示例：3.0.3如果所有命令均正常输出，说明开发环境搭建成功。此时项目目录结构应如下所示：
realtime-monitor-dashboard/
├── app/
│ ├── __init__.py
│ ├── routes/
│ ├── models/
│ ├── services/
│ └── static/
├── config/
│ ├── __init__.py
│ ├── default.py
│ └── production.py
├── tests/
│ └── __init__.py
├── venv/
├── .gitignore
├── .env
├── requirements.txt
└── run.py