第3章开发环境搭建

第3章：开发环境搭建

说实话，很多初学者在环境搭建这一步就栽了跟头。我见过太多人，代码写得挺溜，结果一换电脑就抓瞎——依赖冲突、版本不对、项目跑不起来。嗯，今天我们就来把这套流程捋顺。

3.1 为什么需要虚拟环境？

你想想看，一个Python项目可能依赖Django 3.2，另一个项目却需要Django 4.0。如果全装到系统里，那叫一个乱。虚拟环境说白了就是给每个项目一个独立的「小房间」，互不干扰。

我在项目中遇到过最惨的一次：同事把项目依赖全装到系统Python里，结果升级一个包，把另一个线上项目的环境搞崩了。从那以后，我要求团队必须用虚拟环境，没得商量。

核心原则： 每个项目一个虚拟环境，环境之间完全隔离。

3.2 创建Python虚拟环境

Python 3.3以上版本自带 venv 模块，不需要额外安装。我个人习惯用 python -m venv 这种方式，干净利落。

# 创建虚拟环境（在项目根目录下执行）
python -m venv venv

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

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

# 退出虚拟环境
deactivate

激活后，你会看到命令行前面多了 (venv) 字样。这就是虚拟环境生效的标志。

小技巧： 我习惯把虚拟环境命名为 venv，这样所有项目统一，也方便写自动化脚本。记得把 venv/ 加到 .gitignore 里，别提交到版本库。

3.3 依赖管理：requirements.txt

为什么要用 requirements.txt？说白了就是「环境快照」。你在一台机器上装好了所有依赖，用这个文件就能在另一台机器上完全复现。

生成方式很简单：

# 导出当前环境的所有依赖
pip freeze > requirements.txt

# 在新环境中安装依赖
pip install -r requirements.txt

来看看一个典型的 requirements.txt 长什么样：

dash==2.14.0
plotly==5.17.0
pandas==2.0.3
numpy==1.24.3
requests==2.31.0
python-dotenv==1.0.0

这里有个坑，我曾经踩过：pip freeze 会导出所有已安装的包，包括那些间接依赖。如果你只想导出项目直接依赖，可以用 pipreqs 这个工具。

# 安装 pipreqs
pip install pipreqs

# 自动扫描项目并生成 requirements.txt
pipreqs ./ --encoding=utf8 --force

注意： 版本号一定要写清楚。我见过有人写 dash>=2.0，结果部署时装了个大版本，API全变了，项目直接崩掉。锁定版本号，别偷懒。

3.4 项目目录结构规划

好的目录结构，能让项目活得更久。我这些年折腾下来，总结了一套比较顺手的结构：

device-dashboard/
├── venv/                    # 虚拟环境（不提交到git）
├── src/                     # 源代码
│   ├── __init__.py
│   ├── app.py              # 应用入口
│   ├── data/               # 数据处理
│   │   ├── __init__.py
│   │   ├── loader.py       # 数据加载
│   │   └── processor.py    # 数据清洗
│   ├── dashboard/          # 看板组件
│   │   ├── __init__.py
│   │   ├── layout.py       # 页面布局
│   │   └── callbacks.py    # 交互逻辑
│   └── utils/              # 工具函数
│       ├── __init__.py
│       └── helpers.py
├── data/                   # 数据文件（原始数据）
│   └── device_data.csv
├── assets/                 # 静态资源
│   ├── style.css
│   └── logo.png
├── tests/                  # 测试代码
│   ├── __init__.py
│   └── test_loader.py
├── requirements.txt        # 依赖清单
├── .gitignore              # Git忽略规则
├── README.md               # 项目说明
└── run.py                  # 启动脚本

这个结构有几个好处：

src/ 放核心代码，和配置文件、数据文件分开
data/ 放原始数据，方便调试时直接读取
assets/ 放样式和图片，保持整洁
tests/ 单独放测试，养成写测试的习惯

我的习惯： 每个模块都放一个 __init__.py，哪怕里面是空的。这样Python才能正确识别包结构。另外，run.py 作为启动脚本，里面就一行 from src.app import app; app.run()，干净。

3.5 知识体系总览

下面这张图，把本章的核心逻辑串起来了：

3.6 实战：从零搭建项目环境

咱们来走一遍完整流程。假设你要开始做这个设备数据看板项目：

创建项目目录：mkdir device-dashboard && cd device-dashboard
创建虚拟环境：python -m venv venv
激活环境：source venv/bin/activate（Windows用 venv\Scripts\activate）
安装核心依赖：pip install dash plotly pandas numpy requests python-dotenv
生成依赖文件：pip freeze > requirements.txt
创建目录结构：按上面规划好的结构，创建所有文件夹和 __init__.py
初始化Git仓库：git init，并创建 .gitignore 文件

  关键一步： 在 .gitignore 里至少加上这三行：

  venv/

  __pycache__/

  *.pyc

嗯，到这里环境就搭好了。以后不管换到哪台机器，只要把代码拉下来，执行 pip install -r requirements.txt，就能直接跑起来。省心。

额外建议： 如果你用VS Code，装个Python扩展后，它会自动识别虚拟环境。你打开终端时，它会自动激活 venv，不用手动敲命令。这个小细节能省不少事。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录