理解虚拟环境与两种依赖管理文件的职责
Python 虚拟环境的核心价值在于隔离项目依赖，避免不同项目因共享全局解释器而引发版本冲突或环境污染。通过为每个项目创建独立的运行空间，开发者可以精确控制第三方库的版本。在依赖管理方面，requirements.txt 与 pyproject.toml 扮演着不同角色。requirements.txt 是一种扁平化的依赖快照文件，通常记录精确到补丁版本的库及其依赖树，非常适合传统 Web 应用或脚本项目的部署与环境复现。而 pyproject.toml 是 Python 官方推荐的现代项目配置标准，它不仅声明项目的抽象依赖，还集中管理构建系统、元数据与开发工具配置。二者并非互斥，而是互补：pyproject.toml 用于日常开发与依赖声明，requirements.txt 用于生产环境的确定性安装。建立声明、锁定与部署的模型，能有效提升项目的可维护性与协作效率。
创建虚拟环境并配置项目依赖
创建虚拟环境是 Python 项目初始化的标准第一步。在终端中执行 python -m venv .venv 命令，系统会在当前目录生成名为 .venv 的隔离文件夹，其中包含独立的 Python 解释器副本与 site-packages 目录。激活环境时，Linux 或 macOS 用户运行 source .venv/bin/activate，Windows 用户执行 .venv\Scripts\activate。激活成功后，终端提示符通常会显示 (.venv) 前缀。为确认当前环境已正确切换，可执行 which python 或 where python，以及 python -m pip --version，若输出路径指向 .venv 内部而非系统全局路径，则说明隔离生效。随后即可使用 python -m pip install requests numpy 安装基础依赖。建议始终通过 python -m pip 而非直接调用 pip 来执行安装，这能彻底避免多版本 Python 共存时调用错解释器的风险，确保依赖准确落入当前虚拟环境。
使用 requirements.txt 导出、安装与固定依赖
requirements.txt 是 Python 生态中最经典的依赖管理载体，其核心优势在于提供确定性的环境快照。当项目开发完成或准备部署时，执行 pip freeze > requirements.txt 可将当前虚拟环境中所有已安装包的精确版本导出至文件。该文件天然支持批量安装，新成员或 CI 流水线只需运行 pip install -r requirements.txt 即可一键还原完全一致的运行环境。在版本固定方面，requirements.txt 默认使用双等号锁定具体版本号，有效防止上游库自动升级导致的隐性破坏。对于依赖关系复杂的传统应用，可结合 pip-compile 将高层级依赖解析为包含所有子依赖的锁定文件，实现声明与锁定分离。尽管现代工具链逐渐转向 pyproject.toml，但 requirements.txt 在 Docker 镜像构建、服务器部署及快速复现历史环境时，依然是不可或缺的标准实践。
使用 pyproject.toml 规范化项目依赖配置
pyproject.toml 作为 PEP 518 引入的标准化配置文件，旨在统一 Python 项目的构建与依赖声明。其基础结构采用 TOML 格式，清晰易读。核心配置位于 project 表下，通过 name、version、requires-python 定义项目元数据，并使用 dependencies 数组声明运行时依赖，例如 dependencies = ["requests>=2.28.0", "click>=8.0"]。与硬编码版本不同，此处通常指定兼容范围，由包管理器在解析时自动选择最优版本。现代 Python 工具链均原生支持该格式。配置完成后，开发者可在虚拟环境中执行 pip install -e . 以可编辑模式安装项目及其依赖，便于开发调试。若需构建发布包，则运行 python -m build 即可自动读取 pyproject.toml 生成 wheel 与 sdist。该文件将项目配置、依赖声明与构建逻辑集中管理，大幅降低了传统 setup.py 带来的维护成本，是构建现代化 Python 库与应用的基石。
验证依赖环境并排查常见问题
依赖安装完成后，必须进行严格验证以确保环境健康。执行 pip list 可快速核对已安装包及其版本，而 pip check 则能自动扫描依赖树，输出缺失或冲突的包。排查常见问题时，首要检查虚拟环境是否激活：若终端未显示环境前缀且 pip install 报错权限不足，通常是因为误用了全局 Python。其次，避免同时维护 requirements.txt 与 pyproject.toml 中的依赖列表，这极易导致版本不一致。推荐以 pyproject.toml 为单一事实来源，通过工具自动生成锁定文件。当出现依赖冲突时，可尝试升级冲突包、使用 pip install --upgrade 或借助现代解析器重新计算依赖树。日常维护建议定期运行 pip list --outdated 评估升级风险，并在 CI 流程中强制使用锁定文件安装，从而保障开发、测试与生产环境的高度一致性。
