企业官网建设流程全解析

离线 CentOS 环境安装 uv 及使用 uv 管理 Python 完整教程

本教程提供一套在完全离线 CentOS 系统上安装uv工具，并通过uv安装和管理 Python 解释器的完整、可执行方案。教程分为准备阶段（联网机器）和安装阶段（离线目标机器）两大部分。

一、概念澄清

在使用uv之前，需要区分两个概念：

• uv 工具：用 Rust 编写的 Python 包管理器和项目管理工具，用于创建虚拟环境、安装依赖（替代 pip、pip-tools、poetry 等）。
• uv 管理的 Python 解释器：uv的一个功能，允许你直接管理独立的 Python 解释器本身（类似 pyenv），通过uv python install命令安装特定版本的 Python。

本教程涵盖以上两者的离线安装。

二、准备阶段（在联网机器上操作）

2.1 下载 uv 静态二进制文件

uv官方提供了静态编译的二进制文件，解压即可用，无需额外安装系统依赖库。

1. 打开浏览器访问：https://github.com/astral-sh/uv/releases
2. 找到最新版本（或你需要的特定版本），在Assets区域下载对应架构的压缩包：

确认架构：如不确定目标机器的架构，可在 CentOS 上执行uname -m查看，输出x86_64或aarch64。

2.2 下载 Python 预编译独立构建包

uv安装 Python 时默认从 astral-sh/python-build-standalone 下载预编译的 Python 包。离线环境下需要提前下载好这些包。

1. 打开浏览器访问：https://github.com/astral-sh/python-build-standalone/releases

2. 找到包含你所需 Python 版本的 Release（例如20250409、20241016等）

3. 在Assets区域下载对应架构的install_only_stripped版本（体积最小）：

   例如，对于 x86_64 架构、Linux 系统、Python 3.12：

   cpython-3.12.10+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz

多版本准备：如果需要在离线机器上安装多个 Python 版本，请一并下载对应的tar.gz文件。

2.3 组织本地目录结构（关键步骤）

uv从镜像源读取 Python 安装包时，需要特定的目录结构。下载的tar.gz文件需要按照 Release Tag 放入对应的子目录中。

在联网机器上创建如下目录结构：

# 创建镜像根目录mkdir-p~/uv-python-mirror/# 创建以 Release Tag 命名的子目录（以 20250409 为例）mkdir-p~/uv-python-mirror/20250409/# 将下载的 Python tar.gz 文件移入该子目录mvcpython-*.tar.gz ~/uv-python-mirror/20250409/

目录结构示例：

~/uv-python-mirror/ └── 20250409/ ├── cpython-3.10.17+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz ├── cpython-3.11.12+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz └── cpython-3.12.10+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz

注意：子目录名称必须与 Release Tag（如20250409）完全一致，否则uv无法正确识别。

三、传输文件到离线 CentOS 服务器

将以下内容通过 U 盘、SCP、SFTP 或其他可用方式拷贝到目标 CentOS 服务器的某个目录（例如/opt/offline/）：

1. uv-x86_64-unknown-linux-gnu.tar.gz（uv 二进制包）
2. uv-python-mirror/整个目录（Python 预编译包镜像）

四、安装阶段（在离线 CentOS 服务器上操作）

4.1 安装 uv 工具

# 1. 进入存放安装包的目录cd/opt/offline/# 2. 解压 uv 二进制包tar-xzvfuv-x86_64-unknown-linux-gnu.tar.gz# 3. 将 uv 和 uvx 移动到系统 PATH 路径（需要 root 权限）sudomvuv uvx /usr/local/bin/# 4. 验证安装uv--version# 应输出类似：uv 0.x.x

4.2 配置 Python 安装镜像源

将uv的 Python 下载源指向本地镜像目录。有两种方式：

方式一：通过环境变量（推荐，全局生效）

# 临时生效（当前终端会话）exportUV_PYTHON_INSTALL_MIRROR="file:///opt/offline/uv-python-mirror"# 永久生效（写入 ~/.bashrc）echo'export UV_PYTHON_INSTALL_MIRROR="file:///opt/offline/uv-python-mirror"'>>~/.bashrcsource~/.bashrc

方式二：通过命令行参数（临时指定）

uv pythoninstall--mirrorfile:///opt/offline/uv-python-mirror3.12

注意：file://协议后面跟的是镜像根目录的绝对路径，不是子目录路径。

4.3 使用 uv 安装 Python

配置好镜像源后，即可像在线环境一样使用uv python install命令安装 Python：

# 安装指定版本的 Python（精确版本号）uv pythoninstall3.12.10# 或安装主版本号（uv 会自动匹配最新的补丁版本）uv pythoninstall3.12

uv会自动从file:///opt/offline/uv-python-mirror目录下查找与 Release Tag 匹配的子目录，并在其中寻找对应版本的tar.gz文件进行安装。

4.4 验证 Python 安装

# 查看已安装的 Python 版本列表uv python list# 使用新安装的 Python 创建虚拟环境uv venv--python3.12.venv# 激活虚拟环境source.venv/bin/activate# 验证 Python 版本python--version# 应输出：Python 3.12.10

五、离线安装 Python 第三方包（扩展）

在离线环境中，除了安装 Python 解释器，通常还需要安装第三方依赖包。核心思路是：在联网机器上预先下载好所有依赖包，然后拷贝到离线机器安装。

5.1 在联网机器上下载依赖包

# 1. 创建依赖清单echo"numpy pandas requests">requirements.txt# 2. 使用 uv 下载所有依赖包到本地目录uv pip download-d./offline-packages-rrequirements.txt

5.2 传输到离线机器并安装

# 将 offline-packages 目录拷贝到离线机器后，执行：# 激活虚拟环境source.venv/bin/activate# 从本地目录安装所有依赖uv pipinstall--no-index --find-links ./offline-packages-rrequirements.txt

参数说明：

• --no-index：禁止访问 PyPI 网络索引
• --find-links：指定从本地目录查找包文件

六、常见问题与排查