pip freeze > requirements.txt 经常失效，因其 indiscriminately 导出所有已安装包（含间接依赖和临时包），导致迁移后 ModuleNotFoundError 或运行时崩溃；推荐用 pipreqs 静态分析 import 并排除无关目录，注意编码与环境隔离。
pip freeze > requirements.txt 为什么经常失效
因为 pip freeze 只导出当前环境中已安装的包及其精确版本，不区分“项目直接依赖”和“间接依赖”，更不管哪些包其实是系统级或开发期临时装的。实际迁移后常出现：本地能跑、服务器报 ModuleNotFoundError，或者运行时突然崩在某个没声明但被间接依赖的包上。
- 用
pipreqs替代：它静态分析.py文件里的import，只生成项目真实引用的包（支持排除tests/和venv/） - 执行前先清理无关环境：
python -m venv clean_env && clean_env/bin/python -m pip install pipreqs，避免旧环境污染结果 - 注意编码问题：如果项目含中文路径或注释，
pipreqs可能报UnicodeDecodeError，加参数--encoding=utf-8
poetry export -f requirements.txt 生成的文件仍缺东西
poetry export 默认只导出生产依赖（即不含 dev-dependencies），但很多工具链（比如 black、mypy）其配置文件（pyproject.toml）里写的检查逻辑，实际运行时却依赖这些 dev 包——迁移后 CI 直接失败。
- 确认导出范围：
poetry export -f requirements.txt --without-hashes --without-dev > requirements.txt是默认行为；要包含 dev 包，必须显式加--with dev - 哈希校验（
--with-hashes）在跨平台时容易出问题：macOS 和 Linux 下同一包的 wheel 哈希可能不同，建议上线环境禁用 - 导出后手动检查是否含
setuptools、wheel：某些老版 Python（如 3.7）没预装，缺了会导致pip install -r报ERROR: Could not build wheels
Docker 构建时 pip install -r requirements.txt 卡住或超时
根本原因是国内网络直连 PyPI 极不稳定，而 Docker 默认不继承宿主机的 pip 配置，每次构建都重走公网，且无重试机制。
- 在
Dockerfile中第一行就写：RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/ - 不要用
COPY requirements.txt . && pip install -r requirements.txt这种写法：哪怕只改一行代码，Docker 也会跳过前面所有缓存层，重装全部依赖；应拆成两步：COPY requirements.txt .→RUN pip install -r requirements.txt→COPY . . - 若依赖中含私有包（如公司内网 GitLab 的
git+ssh://...），需在构建阶段挂载 SSH key，并在RUN命令前用--ssh default启用 BuildKit
venv + requirements.txt 迁移后 import 模块却找不到
最常见原因不是包没装，而是 Python 解释器没切对——特别是当系统存在多个 Python 版本（如 Ubuntu 自带 python3.10，用户又装了 python3.12），venv 创建时没指定解释器，导致新环境绑定错版本。
立即学习“Python免费学习笔记（深入）”；
- 创建虚拟环境务必带
-p参数：python3.12 -m venv venv，而不是模糊的python -m venv venv - 激活后立刻验证：
which python输出应为./venv/bin/python，且python -c "import sys; print(sys.version)"版本号与预期一致 - 某些包（如
numpy、torch）编译型依赖会绑定具体架构（manylinux2014_x86_64）和 Python ABI（cp312），换机器前先用python -c "import platform; print(platform.machine())"核对 CPU 架构
环境打包真正的难点不在“怎么装”，而在“怎么证明装的是对的”——迁移前后跑一遍 python -c "import your_main_module; your_main_module.check_deps()" 这类轻量自检函数，比任何文档都可靠。
