关注同名公众号及时获取更多技术资讯

很多人做 Python 项目时是不是也遇到过这些情况：

• 本地跑得好好的，换台电脑就依赖乱套？
• Windows 开发，结果容器一跑各种报错？
• HuggingFace 模型下了几次，硬盘差点爆掉？
• .env 文件写得花里胡哨，API Key 死活识别不了？

这篇文章我就结合最近的一个模型评测项目，分享一下我总结的“Conda + uv 管包 + Docker 跑项目”最佳实践。希望能帮你少踩坑。

01 虚拟环境：Conda vs uv

很多人会问：我已经在用 Conda 新建虚拟环境了，还需要再 uv venv 吗？

答案是：不需要。

最佳组合是：

• Conda 建环境（解决 Python 版本、CUDA、C 库问题）
• uv 管包（替代 pip，更快、更稳）

示例：

conda create -n pj310 python=3.10
conda activate pj310
uv pip install -r requirements.txt

这样，你的项目环境就既有 Conda 的强大兼容性，又能享受 uv 的极速安装。

02 冻结依赖：什么时候用？

• requirements.txt：开发阶段的依赖清单（主依赖，版本可以宽松一点）
• 冻结依赖（freeze）：把当前环境里所有依赖和精确版本保存下来，用于复现和上线。

生成冻结依赖：

uv pip freeze --exclude-editable | Out-File -Encoding utf8 requirements-freeze.txt

什么时候用？

• 开发 → 用 requirements.txt
• 上线/复现 → 用 requirements-freeze.txt

03 Docker：最常用的 5 条命令

先记住这几个就够用

04 Dockerfile 示例（逐行解释）

FROM python:3.10-slim

# 安装系统工具
RUN apt-get update && apt-get install -y --no-install-recommends git build-essential && rm -rf /var/lib/apt/lists/*

# 工作目录
WORKDIR /work

# 安装 uv 并创建虚拟环境
RUN python -m pip install -U pip uv && uv venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 拷贝依赖清单并安装
COPY requirements.txt /tmp/requirements.txt
RUN uv pip install -r /tmp/requirements.txt

CMD ["bash"]

几个要点：

• 容器是 Linux，不要写 Windows 专属包（如 pywin32）。
• 开发阶段挂载代码，不要 COPY 全项目，重建太慢。

05 .env 配置的坑

.env 文件很容易写错，注意：

错误写法：

OPENAI_API_KEY="sk-xxxx" # 我的key

正确写法：

OPENAI_API_KEY=sk-xxxx

不要加引号，不要写行内注释！

06 HuggingFace 缓存一定要挂载

不挂缓存，每次容器重建都要重新下载模型，太折磨。

正确做法：

docker run --rm -it `
  --env-file .env `
  -e HF_HOME=/hf_cache `
  -v "F:\hf_cache:/hf_cache" `
  -v "F:\working\pj:/work" `
  pj-model-eval:py310

07 推荐依赖分层

• requirements.txt（通用依赖）
• requirements.win.txt（Windows 专属包）
• requirements-freeze.txt（冻结依赖，用于复现/上线）

这样，本地和容器就能各跑各的，互不干扰。

08 简要总结

• .env里别加引号、别写注释
• Windows 路径有空格 → 用引号
• HuggingFace 缓存要挂载
• Windows/Linux 依赖要分开写
• Dockerfile 拆层写，依赖能命中缓存，构建更快

讨论区互动：你平时是怎么管理环境的？有没有踩过类似的坑？欢迎留言交流～？