📚 课程目录第3章项目开发基础

3、项目开发基础：回顾Python/Node.js等常用开发语言在树莓派上的项目结构、依赖管理（pip、npm）以及虚拟环境的使用

在树莓派上构建可打包、可部署的项目，首先需要夯实开发基础。树莓派本质上是一台运行Linux（通常是Raspberry Pi OS，基于Debian）的ARM架构计算机，因此其项目开发与在普通Linux服务器上开发高度相似，但受限于硬件资源（CPU性能、内存、存储），对项目结构的清晰度、依赖管理的严谨性以及虚拟环境的隔离性提出了更高要求。本章将系统回顾Python与Node.js这两大主流语言在树莓派上的标准项目结构、依赖管理工具（pip与npm）以及虚拟环境（venv与Node.js的node_modules隔离机制）的核心用法，为后续的镜像制作与开机自启部署打下坚实基础。

上图展示了Python与Node.js在树莓派开发中的核心生态对比。两者在项目结构、依赖管理和虚拟环境方面各有特点，但都遵循“代码与依赖分离、环境隔离、可重复构建”的现代软件开发原则。下面我们将逐一深入剖析。

3.1 Python项目结构：从脚本到工程化

核心原理：树莓派上的Python项目通常从简单的单文件脚本（如led_blink.py）起步，但随着功能增加（如传感器数据采集、Web服务、数据库交互），必须转向模块化、包化的工程结构。一个标准的Python项目结构应包含：app/（业务逻辑包）、tests/（单元测试）、requirements.txt（依赖清单）、README.md（说明文档）以及可选的setup.py或pyproject.toml（用于安装为本地包）。

操作流程：创建项目骨架时，建议使用以下命令在树莓派终端中初始化：

mkdir my_project && cd my_project
mkdir app tests
touch app/__init__.py app/main.py app/config.py
touch tests/test_main.py
touch requirements.txt README.md
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

这里的关键在于__init__.py文件，它使app目录成为一个Python包，允许使用from app import main的方式导入模块。在树莓派上，由于系统Python环境可能被系统包管理器（apt）占用，强烈建议始终使用虚拟环境。

实战场景：假设你正在开发一个温湿度监控服务，使用DHT22传感器和Flask框架。项目结构应如下：

dht_monitor/
├── app/
│   ├── __init__.py
│   ├── main.py          # Flask入口
│   ├── sensor.py        # DHT22读取逻辑
│   └── config.py        # 配置参数（GPIO引脚、采样间隔）
├── tests/
│   └── test_sensor.py
├── requirements.txt     # flask, Adafruit_DHT, pytest
├── .env                 # 环境变量（如数据库URL）
└── README.md

常见误区：初学者常犯的错误是直接在系统Python环境中pip install，这可能导致依赖冲突或污染系统环境。例如，树莓派系统自带的python3可能被用于系统工具，若安装不兼容的库版本，可能导致系统功能异常。另一个误区是忽略requirements.txt的版本锁定，导致在不同时间部署时拉取到不同版本的依赖，引发“在我机器上能跑”的问题。

3.2 Python依赖管理：pip的进阶用法

核心原理：pip是Python的包安装器，从PyPI（Python Package Index）下载并安装包。在树莓派上，由于ARM架构，部分包可能需要编译（如numpy、opencv-python），这会消耗大量时间。因此，理解pip的安装源、缓存机制和版本控制至关重要。

判断方法：使用pip freeze可以列出当前环境中所有已安装包及其精确版本号，这是生成requirements.txt的标准方法。但需要注意，freeze会包含所有传递依赖，有时过于冗余。更推荐的做法是手动维护顶层依赖，并使用pip-tools或poetry进行编译。

命令/工具	用途	树莓派注意事项
`pip install package`	安装包	若包含C扩展，需先安装`build-essential`和`python3-dev`
`pip install -r requirements.txt`	批量安装	建议在虚拟环境中执行，避免污染系统
`pip list --outdated`	查看可更新包	更新前先备份虚拟环境或使用`pip freeze`导出
`pip cache dir`	查看缓存位置	可设置`PIP_CACHE_DIR`到SD卡外存储，减少写入
`pip download`	离线下载包	用于在无网络环境下的树莓派部署

操作流程：为了加速在树莓派上的安装，建议配置国内镜像源（如清华、阿里云）。创建~/.pip/pip.conf文件：

[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
trusted-host = mirrors.aliyun.com
timeout = 120

对于需要编译的包，可以预先安装系统依赖：sudo apt install libatlas-base-dev libjasper-dev libqtgui4等，以减少编译失败的概率。

风险提示：在树莓派上使用pip install时，若遇到“externally-managed-environment”错误（PEP 668），说明系统Python环境受保护。此时必须使用虚拟环境或添加--break-system-packages参数（不推荐）。正确的做法是始终创建venv。

3.3 Node.js项目结构与npm依赖管理

核心原理：Node.js项目以package.json为心脏，它定义了项目元数据、脚本命令和依赖列表。与Python不同，Node.js默认将依赖安装在项目根目录的node_modules文件夹中，实现了天然的本地隔离。在树莓派上，Node.js常用于构建Web服务器、MQTT客户端或基于Electron的桌面应用（尽管Electron在树莓派上资源占用较高）。

操作流程：初始化Node.js项目：

mkdir node_project && cd node_project
npm init -y
npm install express --save
npm install nodemon --save-dev

这里--save（默认）将依赖写入dependencies，--save-dev写入devDependencies。在树莓派上，建议使用Node.js 16+版本（可通过nvm或NodeSource仓库安装）。

案例拆解：假设我们要开发一个树莓派GPIO控制API服务。项目结构如下：

gpio-api/
├── src/
│   ├── index.js          # Express入口
│   ├── routes/
│   │   └── gpio.js       # GPIO路由
│   └── services/
│       └── gpioService.js # 使用onoff库控制GPIO
├── public/               # 静态文件
├── package.json
├── package-lock.json     # 锁定精确版本
└── .env                  # 端口、GPIO映射

在package.json中，可以定义启动脚本：

"scripts": {
  "start": "node src/index.js",
  "dev": "nodemon src/index.js"
}

常见误区：一个常见错误是使用npm install -g全局安装包（如pm2、nodemon）。虽然方便，但在打包镜像时，全局包不会被包含在项目依赖中，导致部署后找不到命令。正确做法是将这些工具作为devDependencies安装，或使用npx临时调用。另一个误区是忽略package-lock.json的提交，该文件锁定了依赖树的精确版本，确保npm ci（用于CI/CD）能快速、可重复地安装。

3.4 虚拟环境与依赖隔离的深度对比

核心原理：虚拟环境的核心目的是隔离不同项目的依赖，避免版本冲突。Python使用venv（标准库）或virtualenv创建独立的Python解释器和包目录；Node.js则通过node_modules的本地安装机制实现隔离，但全局包仍可能冲突。

维度	Python (venv)	Node.js (npm)
隔离粒度	解释器级隔离（复制或链接Python二进制）	包级隔离（每个项目独立node_modules）
激活方式	`source .venv/bin/activate`	无需激活，通过`npm run`执行脚本时自动使用本地依赖
依赖清单	`requirements.txt`（手动维护）	`package.json`（自动记录）
版本锁定	需`pip freeze`或`pip-tools`	`package-lock.json`自动生成
树莓派特有	需注意`venv`是否包含`pip`（有时需`python3 -m ensurepip`）	Node.js的ARM版本需从官方或NodeSource获取

判断方法：在树莓派上，选择Python还是Node.js取决于项目类型。若涉及大量传感器读取、GPIO控制、科学计算，Python生态更成熟（如gpiozero、numpy）；若开发实时Web应用、轻量级API或使用前端构建工具，Node.js更高效。对于虚拟环境，Python项目必须使用venv，而Node.js项目则需确保node_modules不被误删，并在.gitignore中排除它。

经验提醒：在树莓派上，由于SD卡空间有限，建议将虚拟环境或node_modules放在外接USB存储或网络挂载目录中，但需注意I/O性能。更推荐的做法是使用pip install --no-cache-dir和npm ci --prefer-offline减少缓存占用。

3.5 实战案例：构建一个可复现的传感器数据采集服务

背景与约束：假设我们需要在树莓派上部署一个多传感器数据采集服务，将温度、湿度、光照数据通过MQTT上报。项目要求：可复现部署（在另一台树莓派上能快速搭建）、依赖隔离、支持开机自启（为后续章节铺垫）。硬件为树莓派4B，连接DHT22和BH1750传感器。

初始现象与目标：最初，开发者在系统Python环境中直接安装Adafruit_DHT和RPi.GPIO，导致与系统包冲突，且无法在另一台设备上复现。目标是通过虚拟环境和依赖锁定，实现一键部署。

关键输入数据：项目依赖包括：paho-mqtt（MQTT客户端）、Adafruit_DHT（DHT22驱动）、smbus2（I2C通信）、python-dotenv（环境变量管理）。

分析判断过程：首先，创建虚拟环境并安装依赖：

python3 -m venv .venv
source .venv/bin/activate
pip install paho-mqtt Adafruit_DHT smbus2 python-dotenv
pip freeze > requirements.txt

然后，编写main.py，使用dotenv加载MQTT配置：

import os
from dotenv import load_dotenv
import paho.mqtt.client as mqtt
import Adafruit_DHT
import smbus2
import time

load_dotenv()
MQTT_BROKER = os.getenv('MQTT_BROKER', 'localhost')
MQTT_TOPIC = os.getenv('MQTT_TOPIC', 'sensors/data')

# 初始化传感器...
while True:
    humidity, temperature = Adafruit_DHT.read_retry(11, 4)
    # 读取光照...
    client.publish(MQTT_TOPIC, f'{{"temp":{temperature},"hum":{humidity}}}')
    time.sleep(60)

实际操作步骤：在.env文件中配置参数，并在requirements.txt中锁定版本。为了验证可复现性，在另一台树莓派上执行：

git clone <repo-url> && cd sensor-service
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

结果对比：使用虚拟环境后，部署时间从原来的30分钟（含编译错误排查）缩短至5分钟（纯下载安装）。且系统Python环境保持干净，不影响其他系统工具。

风险与代价：虚拟环境占用了约50MB磁盘空间，但换来的是依赖隔离的安心。另一个代价是每次部署需重新安装依赖，但可通过pip wheel预构建wheel包加速。

复盘经验：在树莓派项目中，应始终将requirements.txt或package-lock.json纳入版本控制。对于包含C扩展的包，建议在requirements.txt中注释编译依赖，并在README中说明sudo apt install的步骤。

总结复盘：本章回顾了树莓派上Python和Node.js项目的标准结构、依赖管理及虚拟环境使用。核心要点是：Python必须使用venv，Node.js依赖本地node_modules，两者都需锁定依赖版本。这些基础将直接影响后续章节中的镜像制作（确保镜像精简且包含正确依赖）和开机自启配置（服务能正确找到解释器和依赖路径）。