（二十六）从声明重建环境

1. uv 路线

交付源代码时，一起带上 pyproject.toml、uv.lock 和 .python-version。把项目复制到新的目录后，使用 Python 3.12 重新同步；运行数据按需要另行恢复。

# 在新复制的某个项目目录中运行，当前目录原先没有 .venv。
uv sync --locked
# 用重建环境执行相同测试与完整操作。
uv run python tools/check.py

--locked 会检查锁定文件是否与项目声明一致，需要更新锁定结果时停止并指出问题。修改依赖后先在开发目录更新锁定文件并检查，再一同交付。

2. pip 与 .venv 路线

# 在另一份没有 .venv 的项目副本中，使用 Python 3.12 创建环境。
py -3.12 -m venv .venv
# 安装随项目提供的具体版本，再以可编辑方式安装当前项目。
.venv\Scripts\python -m pip install -r pip-requirements.txt
.venv\Scripts\python -m pip install --no-deps -e .
# 始终用这份环境的解释器执行检查。
.venv\Scripts\python tools/check.py

macOS/Linux 中相应解释器在 .venv/bin/python。模型清单包含 CPU 轮子的索引配置；直接使用随附文件即可。两条路线分别在独立环境执行同一套检查，才能核对安装步骤确实齐全。

本章的两个新 pip 环境分别通过了 20 项和 23 项测试，uv 项目环境也通过相同检查。依赖升级时重新导出清单，避免手动维护两组不一致的版本；导出用法见 uv 锁定结果导出文档。

# 维护 pip 清单时，从已有锁定结果导出；不把当前项目本身写进依赖列表。
uv export --locked --all-groups --no-hashes --no-emit-project --output-file pip-requirements.txt
# 模型项目改用随附工具，在导出结果前加上 CPU 索引配置。
uv run python tools/export_requirements.py

Python 版本、平台与依赖都属于环境信息。记录本机验证用的系统和版本，再到实际部署平台执行检查；锁定依赖之后，仍要核对进程能启动、资源能找到和数据能恢复。