在无网环境下使用 python uv 的核心方法是提前在联网机器上下载好所需的包和索引缓存，然后将其打包迁移至目标环境。具体做法是先在联网环境中利用 uv pip download 命令将依赖项下载到本地目录，并生成 requirements.txt 文件；随后将该目录及文件拷贝至无网机器，通过 uv pip install --no-index --find-links 命令指定本地路径进行安装。此方法依赖于预先获取的完整依赖树，确保离线环境中能解析所有包的版本关系。
如何在联网机器上预下载依赖包
在联网机器上，可以使用 uv pip download 命令将项目所需的所有依赖包及其元数据下载到指定目录。该命令会递归解析依赖关系，下载 wheel 文件和必要的构建依赖，同时保持原有的目录结构以便后续安装。执行时需指定输出目录（如 --dest）和需求文件（如 -r requirements.txt），这样可以在不实际安装的情况下完成资源的收集。这一步骤生成的文件集合构成了离线安装的基础资源库。
uv pip download -r requirements.txt --dest ./offline_packages
上述命令执行后，./offline_packages 目录下将包含所有需要的 .whl 文件以及对应的 .dist-info 元数据文件夹。这些文件可以直接被后续的离线安装命令读取。如果项目有特定的 Python 版本或平台限制，可以在命令中追加 --python-version 或 --platform 参数以确保下载的包与目标环境兼容。例如，若目标服务器为 Linux x86_64，则应明确指定以获取正确的二进制包，避免下载源码包导致离线编译失败。
立即学习“Python免费学习笔记（深入）”；
如何在无网机器上从本地目录安装
在无网机器上，需要将之前下载的 offline_packages 目录和 requirements.txt 文件传输至目标机器。安装时，必须禁用网络索引以防止 uv 尝试连接 PyPI，并通过 --find-links 参数指向本地包目录。使用 uv pip install 命令配合 --no-index 和 --find-links 选项，可以强制 uv 仅从本地文件系统解析和安装依赖。这种方式完全隔离了网络请求，确保在无网环境下也能成功部署。
uv pip install -r requirements.txt --no-index --find-links ./offline_packages
执行上述命令后，uv 会扫描 ./offline_packages 目录，根据 requirements.txt 中的版本约束匹配相应的 wheel 文件并进行安装。如果依赖之间存在复杂的版本冲突，uv 会在本地解析这些冲突并给出错误提示，此时需回到联网机器检查需求文件的版本兼容性。此外，若目标环境需要特定的解释器路径，可在命令前加上 uv python pin 或使用 --python 参数指定解释器位置，确保安装过程在正确的虚拟环境或系统环境中进行。
当本地包缺少某个间接依赖时会发生什么
如果在联网机器上预下载时遗漏了某个间接依赖，或者该依赖因平台不兼容未被正确下载，无网机器上的安装过程将会失败。uv 在解析依赖树时，如果发现某个必需的包在 --find-links 指定的本地目录中不存在，且禁用了网络索引，它将无法获取该包并抛出 No matching distribution found 错误。这种情况下，唯一的解决办法是返回联网机器，重新运行 uv pip download 并确保所有依赖都被完整捕获，特别是那些可能因条件标记（如 sys_platform）而被过滤掉的包。因此，预下载阶段的完整性验证至关重要，建议在联网环境中先模拟一次安装过程，确认所有依赖均可本地解析后再进行迁移。
