使用 uv：一个命令搞定 Python 离线部署

uv 相较于传统工具（如 pip-tools）的一个显著优势，它简化了工作流。

在需要离线部署 Python 项目的生产环境中，如何高效、可靠地管理依赖一直是个难题。幸运的是，新一代的 Python 包管理器 uv 提供了一个极其简化的解决方案。

本文将为您呈现一个经过优化的工作流，仅需一个核心命令，即可利用 uv 强大的缓存机制，实现快速、可复现的离线部署。

核心理念：缓存即是可移植的环境

整个策略的基石是 uv 的本地缓存。工作流可以被提炼为两个阶段：

在线准备: 在可上网的开发电脑上，使用一个命令完成依赖解析、锁文件生成和包下载缓存的全部工作。
离线部署: 将项目文件、uv 程序本身以及填充好的缓存目录一起打包，拷贝到目标服务器上，然后以完全离线的方式从本地缓存进行安装。

第一步：在开发电脑上准备“离线部署包”

此阶段的目标是创建一个自包含的部署压缩包，里面有我们需要的一切。

关键前提：

开发电脑的 操作系统、CPU 架构 (如 x86_64, aarch64) 和 Python 主版本号 必须与目标服务器完全一致。这是因为许多 Python 包（如 numpy, pandas）会分发针对特定平台的二进制 Wheel 文件，平台不匹配将导致部署失败。

操作流程：

清理缓存（推荐）

为了确保我们打包的缓存是纯净的，只包含当前项目的依赖，建议先执行一次缓存清理。
```
uv cache clean
```
一键同步与锁定

现在，在你的项目根目录下（包含 pyproject.toml 的地方），运行 uv sync。这个强大的命令会为你处理所有事情：
- 检查 pyproject.toml。
- 如果 uv.lock 不存在或已过期，它会重新解析所有依赖，并自动创建或更新 uv.lock 文件。
- 根据最终的锁文件，将所有依赖包下载并安装到本地的虚拟环境 (.venv) 中。
- 所有下载的包都会被妥善地存放在 uv 的全局缓存目录里。
```
# 运行此命令，uv 会自动搞定 lock 和 sync
uv sync
```
定位与打包

现在，所有组件都已就绪。我们需要将它们打包以便传输。
- 找到缓存目录: 运行 uv cache dir 命令获取缓存目录的绝对路径。
```
uv cache dir
# Linux/macOS 示例输出: /home/user/.cache/uv
# Windows 示例输出: C:\Users\user\AppData\Local\uv\cache
```
- 创建部署包: 将以下 4 个部分拷贝到一个新建的部署文件夹（例如 my-project-deploy）中，然后将其压缩 (.tar.gz 或 .zip)。
  1. uv 可执行文件: 注意，你需要的是适用于服务器操作系统和架构的 uv 版本。你可以从 uv 的 GitHub Releases 页面轻松获取。
  2. pyproject.toml 文件。
  3. uv.lock 文件（由上一步自动生成）。
  4. 完整的 cache 目录：将上一步找到的 uv 缓存目录整体复制过来，可以重命名为 cache 以方便后续操作。

第二步：在服务器上进行离线部署

前提条件：

目标服务器已安装与开发环境一致的 Python 版本。
服务器上无需预装 uv 或拥有网络连接。

操作流程：

传输与解压

将你制作的部署包上传到服务器并解压。解压后，你的项目目录结构应该如下：

my-project/
├── uv                # (或 uv.exe on Windows)
├── pyproject.toml
├── uv.lock
└── cache/
    └── ... (成百上千的缓存文件)

执行离线同步

进入项目目录 (my-project)，运行最终的安装命令：
```
# (仅非 Windows 系统) 授予 uv 执行权限
chmod +x ./uv

# 使用本地缓存，在离线模式下安装所有依赖
./uv sync --cache-dir ./cache --offline
```
命令解析：
- ./uv sync: 执行我们带过来的 uv 程序，并进行同步操作。
- --cache-dir ./cache: 强制 uv 使用当前目录下的 cache 文件夹作为唯一的包源。
- --offline: 关键参数。它会禁止 uv 进行任何网络活动，确保部署过程在完全隔离的环境下进行。
命令执行完毕后，uv 会在项目目录下创建一个 .venv 虚拟环境，并从你提供的 cache 文件夹中闪电般地装好所有依赖。

结论

uv 通过将锁定和同步的智能化合并，将复杂的离线部署流程简化为 打包 -> 传输 -> 离线同步 的三部曲。这种现代化的工作流不仅极大提升了效率，更通过锁文件和完整的缓存保证了生产环境的确定性和稳定性，是现代 Python 项目部署的绝佳实践。

使用 uv：一个命令搞定 Python 离线部署