如何解决 uv run 因网络问题导致的 Python 下载失败

uv 是一个极其出色的 Python 项目和虚拟环境管理工具。通过简单的 uv run <你的脚本.py> 命令，它就能在后台自动下载所需的 Python 版本并配置好运行环境，整个过程丝滑流畅。

然而，由于 uv 默认从 GitHub.com 下载预编译的 Python，限于墙的威力，可能会遇到连接超时或下载失败的问题。错误信息通常如下图所示：

当看到这个错误时，请不要担心，这只是网络问题。我们可以通过"手动搬运"的方式轻松解决。下面是详细的操作步骤。

第一步：解读错误信息，定位所需版本

首先，仔细查看终端里的报错信息。您需要从里面找到两个关键信息：

Python 版本 : 类似 cpython-3.12.0 这样的字符串，这告诉我们 uv 尝试下载的是 3.12.0 版本的 CPython。
系统架构 : 紧跟在版本号后面的部分，例如 aarch64-apple-darwin 代表 ARM 架构的 macOS 系统，而 Windows 用户通常会看到 x86_64-pc-windows 或类似的标识。

掌握这两个信息后，我们就可以准备手动下载了。

根据您在第一步中确定的 Python 版本 和系统架构 ，访问以下地址，找到并下载对应的 .tar.gz 压缩包。

这里列出了一些常见 Windows (x86_64-windows) 版本的下载链接：

Python 3.14.x（如果显示 3.14. 开头，可以下载这个）
- x86_64-windows: github.com/astral-sh/p...
Python 3.13.x（如果显示 3.13. 开头，可以下载这个）
- x86_64-windows: github.com/astral-sh/p...
Python 3.12.x（如果显示 3.12.开头，可以下载这个）
- x86_64-windows: github.com/astral-sh/p...
Python 3.11.x（如果显示 3.11. 开头，可以下载这个）
- x86_64-windows: github.com/astral-sh/p...
Python 3.10.x（如果显示 3.10. 开头，可以下载这个）
- x86_64-windows: github.com/astral-sh/p...

提示：如果您的版本或系统不在此列，可以访问 uv 的 Python 构建发布页面 https://github.com/astral-sh/python-build-standalone/releases 自行查找。

下载完成后，您会得到一个 .tar.gz 格式的压缩文件。

解压文件 ：将其完全解压。解压后，您会得到一个名为 python 的文件夹。
重命名文件夹 ：这是最关键的一步！您需要将这个 python 文件夹重命名为 uv 能够识别的格式。命名规则通常是 <解释器>-<版本>-<平台>-<架构>-<ABI>。

如果你是从上面列出的下载链接进行的下载，那么重命名规则如下：
- 3.14.x 版本应重命名为: cpython-3.14.0-windows-x86_64-none
- 3.13.x 版本应重命名为: cpython-3.13.9-windows-x86_64-none
- 3.12.x 版本应重命名为: cpython-3.12.0-windows-x86_64-none
- 3.11.x 版本应重命名为: cpython-3.11.14-windows-x86_64-none
- 3.10.x 版本应重命名为: cpython-3.10.19-windows-x86_64-none
- ...以此类推。
重命名后的文件夹如下图所示：

接下来，我们需要将这个重命名好的文件夹"搬"到 uv 存放 Python 解释器的地方。

打开 AppData 目录 ：在 Windows 上，这个目录通常位于 %APPDATA% (即 Roaming 文件夹)下。打开任意文件夹，在地址栏输入 %APPDATA%，然后回车，即进入该文件夹。
定位或创建目标路径：
- 首先，找到或新建一个名为 uv 的文件夹。
- 接着进入 uv 文件夹，再找到或新建一个名为 python 的文件夹。
复制文件夹 ：将您在第三步中重命名好的 Python 文件夹（例如 cpython-3.11.14-windows-x86_64-none）复制或移动到这个 python 目录中。

最终的文件结构应如下图所示：

现在，所有准备工作都已完成。回到您的终端，重新执行之前的 uv run <脚本.py> 命令。

这一次，uv 会在工具链目录中检测到已存在的 Python 版本，跳过下载步骤，直接开始创建虚拟环境和执行脚本。您会发现命令瞬间就成功运行了！