2. 环境准备：Python 3.10+安装、虚拟环境搭建、必备库安装

在开始边缘网关与 Modbus TCP 通信调试之前，必须建立一套干净、可复现的 Python 开发环境。本章将指导你完成从 Python 解释器安装到项目依赖管理的完整流程，确保后续所有实战代码在统一的环境中稳定运行。

环境一致性原则：工业现场调试环境复杂，不同网关固件、Python 版本、库版本之间的兼容性问题极易引发“能跑但报错”的陷阱。严格遵循本章步骤，可避免 90% 以上的环境类故障。

2.1 Python 3.10+ 安装与验证

本课程所有代码基于 Python 3.10 及以上版本开发，利用其增强的类型注解、改进的 asyncio 异步支持以及更稳定的 match 语句。推荐使用 Python 3.10.11 或 3.11.x 长期支持版本。

操作系统 下载来源 安装注意事项
Windows 10/11 python.org 或 Microsoft Store 安装时务必勾选 “Add Python to PATH”；选择 “Customize installation” 并确保 pip 被选中
Ubuntu/Debian APT 仓库或 deadsnakes PPA sudo apt install python3.10 python3.10-venv python3.10-dev
macOS Homebrew 或 python.org brew install python@3.10；注意系统自带 Python 版本通常较低

安装完成后，打开终端（Windows 使用 PowerShell 或 CMD）执行以下命令验证：

# 检查 Python 版本
python --version
# 预期输出：Python 3.10.11 或更高

# 检查 pip 是否可用
pip --version
# 预期输出：pip 23.x from ... (python 3.10)

# 检查是否支持 asyncio（Python 3.4+ 内置）
python -c "import asyncio; print(asyncio.__version__)"
常见问题：Windows 系统若同时安装了多个 Python 版本，请使用 py -3.10 或 python3.10 指定版本；Linux/macOS 使用 python3.10 而非 python。
Python 3.10+ 环境验证流程 ① 下载安装 ② PATH 配置 ③ 版本验证 Windows: 勾选 Add to PATH Linux/macOS: 使用 python3.10 通过 ✓ 💡 验证要点： • 版本号 ≥ 3.10.0 • pip 可用 • asyncio 模块可导入

2.2 虚拟环境搭建

虚拟环境是 Python 项目隔离依赖的基石。本课程推荐使用 Python 内置的 venv 模块，无需额外安装第三方工具。每个项目应有独立的虚拟环境，避免库版本冲突。

2.2.1 创建虚拟环境

在项目根目录下执行以下命令：

# 进入你的项目目录（例如 edge_gateway_project）
cd edge_gateway_project

# 创建虚拟环境（命名为 venv 或 .venv 均可）
python -m venv venv

# 预期输出：无报错，目录下出现 venv/ 文件夹

2.2.2 激活虚拟环境

操作系统 激活命令 验证方式
Windows (CMD) venv\Scripts\activate.bat 命令行前缀出现 (venv)
Windows (PowerShell) venv\Scripts\Activate.ps1 命令行前缀出现 (venv)
Linux / macOS source venv/bin/activate 命令行前缀出现 (venv)
激活后检查：执行 which python（Linux/macOS）或 where python（Windows），路径应指向 venv/bin/python 或 venv\Scripts\python.exe，而非系统全局 Python。

2.2.3 退出虚拟环境

deactivate
虚拟环境生命周期 创建 venv 激活环境 安装依赖 开发调试 deactivate 每个项目独立 venv → 避免全局污染 → 可复现部署

2.3 必备库安装

本课程的核心依赖库包括 pymodbus（Modbus 协议实现）、asyncio（异步 I/O 框架，Python 3.4+ 内置）、loguru（日志管理）。此外，推荐安装 python-dotenv 用于管理环境变量。

2.3.1 安装命令

确保虚拟环境已激活，然后执行：

# 核心库
pip install pymodbus==3.6.8
pip install loguru==0.7.2

# 辅助工具（可选但推荐）
pip install python-dotenv==1.0.0

# 一次性安装所有依赖
pip install pymodbus==3.6.8 loguru==0.7.2 python-dotenv==1.0.0

2.3.2 库功能速览

库名 版本 核心功能 本课程用途
pymodbus 3.6.8 Modbus TCP/RTU/ASCII 客户端与服务器实现 边缘网关与 PLC/仪表 的 Modbus TCP 通信
asyncio 内置 基于协程的异步 I/O 框架 并发处理多设备轮询、非阻塞数据采集
loguru 0.7.2 零配置日志库，支持彩色输出、文件轮转 调试日志、错误追踪、运行状态记录
python-dotenv 1.0.0 从 .env 文件加载环境变量 管理网关 IP、端口、设备 ID 等配置

2.3.3 验证安装

# 激活虚拟环境后执行
python -c "import pymodbus; print(pymodbus.__version__)"
# 预期输出：3.6.8

python -c "import loguru; print(loguru.__version__)"
# 预期输出：0.7.2

python -c "import asyncio; print('asyncio OK')"
# 预期输出：asyncio OK
版本锁定：pymodbus 3.x 与 2.x 的 API 有较大差异。本课程基于 3.6.8 编写，若使用其他版本，请参考官方迁移指南。建议将依赖版本写入 requirements.txt 文件。
边缘网关 Python 依赖库架构 厂务数据采集应用 pymodbus Modbus TCP 通信 asyncio 异步并发调度 loguru 日志记录 Python 3.10+ 运行时

2.4 项目初始化与依赖管理

为便于团队协作和部署，建议将项目依赖记录在 requirements.txt 文件中：

# 生成 requirements.txt（在虚拟环境激活状态下）
pip freeze > requirements.txt

# 查看生成的文件内容
cat requirements.txt
# 输出示例：
# pymodbus==3.6.8
# loguru==0.7.2
# python-dotenv==1.0.0

其他开发者可通过以下命令一键复现环境：

# 克隆项目后，创建并激活虚拟环境，然后执行
pip install -r requirements.txt
推荐项目结构：
edge_gateway_project/
├── venv/ # 虚拟环境（不提交到 Git）
├── .env # 环境变量配置（不提交到 Git）
├── requirements.txt # 依赖清单
├── main.py # 主程序入口
├── config.py # 配置加载模块
└── README.md # 项目说明

2.5 环境验证脚本

编写一个快速验证脚本，确保所有组件正常工作：

# verify_env.py
import sys
import asyncio
from loguru import logger
from pymodbus.client import AsyncModbusTcpClient

async def check_environment():
    """验证开发环境是否就绪"""
    logger.info("开始环境验证...")

    # 1. 检查 Python 版本
    py_version = sys.version_info
    assert py_version.major == 3 and py_version.minor >= 10, \
        f"需要 Python 3.10+, 当前为 {py_version.major}.{py_version.minor}"
    logger.success(f"Python 版本: {py_version.major}.{py_version.minor}.{py_version.micro}")

    # 2. 检查 pymodbus 版本
    import pymodbus
    logger.success(f"pymodbus 版本: {pymodbus.__version__}")

    # 3. 测试异步客户端创建（不连接）
    client = AsyncModbusTcpClient("127.0.0.1", port=502)
    logger.success("AsyncModbusTcpClient 创建成功")

    # 4. 检查 loguru 日志输出
    logger.success("所有环境检查通过！")

if __name__ == "__main__":
    asyncio.run(check_environment())

运行脚本：

python verify_env.py

预期输出（彩色日志）：

2025-01-15 10:30:00.123 | INFO     | __main__:check_environment:10 - 开始环境验证...
2025-01-15 10:30:00.124 | SUCCESS  | __main__:check_environment:16 - Python 版本: 3.10.11
2025-01-15 10:30:00.125 | SUCCESS  | __main__:check_environment:19 - pymodbus 版本: 3.6.8
2025-01-15 10:30:00.126 | SUCCESS  | __main__:check_environment:22 - AsyncModbusTcpClient 创建成功
2025-01-15 10:30:00.127 | SUCCESS  | __main__:check_environment:25 - 所有环境检查通过！
← 上一章 📖 返回目录 下一章 →