1、先确认解释器路径#

第一步不要直接看 python --version，因为版本号相同也可能对应不同环境。可以打印解释器的完整路径：

1
python -c "import sys; print(sys.executable)"

如果项目使用虚拟环境，正常情况下路径里应该能看到 .venv、venv 或 conda 环境名。

在 Windows 上还可以顺手看一下命令解析结果：

1
where python

如果输出里有多个 Python 路径，就要确认当前终端实际排在第一位的是哪一个。

2、导出当前可运行环境的依赖#

如果原机器还能正常运行，先在原机器上导出依赖：

1
python -m pip freeze > requirements.txt

然后在新机器上创建环境并安装：

1
python -m venv .venv
2
.\.venv\Scripts\activate
3
python -m pip install -r requirements.txt

这里推荐始终使用 python -m pip，不要直接用 pip。这样可以减少 pip 指向另一个 Python 的情况。

3、记录项目的启动目录#

有些脚本在项目根目录运行正常，换到子目录运行就失败。原因通常是代码里使用了相对路径，例如：

1
from pathlib import Path
2

3
data_path = Path("data/input.csv")

这个路径不是相对于 Python 文件，而是相对于当前命令行所在目录。为了避免误判，可以在启动时打印：

1
from pathlib import Path
2

3
print("cwd:", Path.cwd())

如果项目必须从根目录启动，可以把启动命令写进 README 或脚本里，例如：

1
python scripts/run_report.py

不要只写“运行 run_report.py”，否则下次很容易在错误目录里启动。

4、检查依赖版本是否真的一致#

有些问题不是包缺失，而是版本变了。比如 pandas、numpy、torch、opencv 这类库，版本差异可能影响 API 或运行结果。

可以对关键包单独检查：

1
python -c "import pandas as pd; print(pd.__version__)"
2
python -c "import numpy as np; print(np.__version__)"

如果项目对版本敏感，requirements.txt 里最好保留精确版本：

1
pandas==2.2.2
2
numpy==1.26.4

等项目稳定后，再考虑升级依赖，而不是在复现问题时顺手升级。

5、把环境变量列成清单#

很多项目还依赖环境变量，例如接口地址、数据库路径、模型文件目录等。可以准备一个 .env.example：

1
DATA_DIR=./data
2
OUTPUT_DIR=./outputs
3
API_BASE_URL=http://localhost:8000

真正的 .env 不一定提交到仓库，但示例文件可以告诉别人需要配置哪些项。

如果变量缺失，代码里也应该给出明确错误：

1
import os
2

3
data_dir = os.getenv("DATA_DIR")
4
if not data_dir:
5
    raise RuntimeError("缺少 DATA_DIR 环境变量")

这样比后面出现一个“文件不存在”的报错更容易定位。

小结#

Python 项目换环境运行时，我现在会按这个顺序检查：

• 先确认 sys.executable，不要只看版本号。
• 用 python -m pip freeze 固定当前可运行依赖。
• 明确从哪个目录启动项目。
• 单独检查关键库版本。
• 把环境变量写成 .env.example 或清单。

环境复现的关键不是记住某一次安装命令，而是把“能运行的条件”记录完整。以后迁移电脑、部署服务器或交给别人运行时，排查成本会低很多。