Dockerfile中COPY依赖包的关键是明确复制内容、时机与原因：通常只需COPY requirements.txt再pip install，而非手动复制.whl文件；仅离线或私有包场景才需COPY预下载包或源码，并注意平台兼容性与文件完整性。
在 Dockerfile 中用 COPY 复制依赖包，关键不是“怎么写命令”，而是“复制什么、什么时候复制、为什么这么复制”。盲目 COPY 一堆 .whl 或 tar.gz 文件容易导致镜像臃肿、构建失败或运行时找不到包。
COPY 依赖包前先明确：你到底需要复制什么？
大多数情况下，你**不需要手动 COPY 依赖包文件**。更推荐的方式是：
- 把
requirements.txt（或pyproject.toml）COPY 进镜像，再用pip install -r requirements.txt安装 —— 这样能自动解析依赖、校验版本、适配平台； - 只有在离线环境、私有源不可达、或需固定二进制包（如含 C 扩展的 wheel）时，才考虑提前下载并 COPY 依赖包。
COPY 已下载的 wheel 包（离线场景）
如果你已用 pip download 下载好所有依赖（包括其传递依赖），得到一堆 .whl 或 .tar.gz 文件，可以这样写：
COPY requirements/ /tmp/requirements/
RUN pip install --find-links /tmp/requirements/ --no-index --no-deps /tmp/requirements/*.whl && \
pip install --find-links /tmp/requirements/ --no-index --no-deps -r /tmp/requirements/requirements.txt
说明：
-
--find-links指定本地包路径； -
--no-index禁用 PyPI，强制只从本地安装； -
--no-deps避免重复安装依赖（因为pip download已下载全部依赖，直接全量安装即可）； - 建议把
requirements.txt也放进requirements/目录，方便统一管理。
COPY 源码包或私有包（如公司内部模块）
若要安装本地开发的 Python 包（比如一个叫 mylib 的目录），可这样写：
OpenClaw Docker Setup
下载
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
COPY mylib/ /app/mylib/ RUN pip install /app/mylib/
或者更规范地，先 COPY setup.py 或 pyproject.toml，再 install：
COPY mylib/setup.py mylib/pyproject.toml mylib/PKG-INFO /app/mylib/ COPY mylib/src/ /app/mylib/src/ RUN pip install /app/mylib/
注意：COPY 要覆盖所有必要文件（如 src/、pyproject.toml、__init__.py 等），否则 pip install 会报错。
避免踩坑的关键细节
常见错误和应对建议：
-
不要 COPY 整个
site-packages：路径、Python 版本、架构不匹配会导致 ImportError； -
COPY 前确认文件存在且权限正确：Docker 构建时若文件缺失，不会报明确错误，但
pip install会失败； -
利用分层缓存：把
COPY requirements.txt放在pip install之前，可复用缓存，加快后续构建； -
wheel 包注意平台标签：比如
numpy-1.24.3-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl必须匹配镜像中的 Python 和系统架构。
不复杂但容易忽略：COPY 是静态复制，它不管包是否兼容；真正起作用的是 pip 安装逻辑和目标环境。所以优先让 pip 去解决依赖，而不是人肉搬运包文件。
