01 安装、解释器与虚拟环境

大约 3 分钟编程语言Pythonvenvpip环境管理

01 安装、解释器与虚拟环境

目标：让解释器版本、项目依赖和运行路径都可验证、可切换、可重建。

1. 先确认解释器

Windows 使用 py 启动器可以列出版本和路径：

py -0p
py -3.14 --version
py -3.14 -c "import sys; print(sys.executable)"

Linux 和 macOS 常用：

python3 --version
command -v python3
python3 -c "import sys, sysconfig; print(sys.executable); print(sysconfig.get_paths())"

排障时至少记录以下信息：

import platform
import sys
import sysconfig

print(sys.version)
print(sys.executable)
print(platform.platform())
print(sysconfig.get_paths())

不要只依赖 python --version。同一个终端里，python、python3、py、IDE 和 systemd 可能指向不同解释器。

2. 选择 Python 版本

选型看四件事：

支持状态：是否仍处于安全修复期。
平台支持：目标操作系统和 CPU 架构是否有官方构建。
依赖兼容：关键二进制包是否提供对应 wheel。
变更成本：固件、内网源、容器基础镜像和发布流程能否同步升级。

新项目可以使用当前稳定系列；长期运行项目应优先选择组织已验证的固定版本，并在升级窗口内完成兼容性验证。

3. 用 venv 隔离项目依赖

标准库已经带有 venv，适合大多数项目：

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

虚拟环境的核心价值是把 python、pip 和 site-packages 绑定到项目目录。不要提交 .venv，但应提交依赖声明和锁文件。

检查当前环境：

python -c "import sys; print(sys.prefix != sys.base_prefix)"
python -m pip list
python -m pip check

第一行输出 True 时，说明当前解释器运行在虚拟环境中。

4. requirements 与 pyproject

小型脚本可以从 requirements.txt 开始：

# requirements.txt
requests==2.32.5
PyYAML==6.0.3

可发布项目优先使用 pyproject.toml：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "ops-inspector"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "PyYAML>=6,<7",
]

[project.optional-dependencies]
dev = [
  "pytest>=8",
  "mypy>=1.10",
  "ruff>=0.8",
]

边界建议：

应用使用锁文件固定完整依赖图。
库声明宽松但有上限的依赖，不把开发工具强加给使用者。
requires-python 要反映真实兼容范围，并在 CI 中覆盖。
不把密码、令牌、私有索引凭据写进项目文件。

5. 可复现环境的检查清单

解释器实现和版本已记录。
虚拟环境目录已加入 .gitignore。
依赖声明与锁文件可重建环境。
CI 从干净缓存执行一次安装。
生产启动使用绝对解释器路径或容器入口。
启动日志记录 Python 版本和程序版本。

import logging
import platform
import sys

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
logging.info("runtime python=%s platform=%s executable=%s", platform.python_version(), platform.platform(), sys.executable)

6. 常见陷阱

用 sudo pip install 污染系统 Python。
在项目外激活 venv 后误以为依赖已经隔离。
只固化顶层依赖，间接依赖仍随上游变化。
把 PYTHONPATH 当作长期依赖注入手段，导致导入来源不可预测。
生产服务依赖 shell 初始化文件中的激活命令。