彻底告别 Python 安装包：内网环境下 uv 的“暴力”安装与避坑指南
前言
在严格管控的 Windows 开发环境下，传统的 Python 安装方式（官网 .exe 或 PowerShell 在线脚本）经常会遇到网络连接关闭（TLS 握手失败）、权限受限等问题。本文记录了如何利用 uv（Rust 编写的高性能 Python 工具）实现无 Python 环境依赖的“纯净式”开发流程，并解决跨机器迁移后的环境失效问题。
一、 为什么选择 uv？
- 不依赖系统 Python：它是一个独立的二进制文件，能自己下载并管理各个版本的 Python。
- 极速体验：比 pip 快 10-100 倍。
- 环境隔离：不再有复杂的“环境变量”污染，每个项目都极其纯净。
二、 突破安装封锁（离线/手动模式）
当官方安装脚本报出“基础连接已关闭”时，说明内网拦截了 PowerShell 的外网访问：
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
1. 手动搬运主程序
- 浏览器下载：从 uv GitHub Releases 下载 uv-x86_64-pc-windows-msvc.zip。
- 安置与寻路：
- 解压得到 uv.exe。
- 将其放置在固定目录（如 D:\tools\uv\）。
- 手动配环境：将该路径添加到系统的 环境变量 Path 中。
- 验证：打开新终端输入 uv --version。
三、 配置内网生存加速器（镜像源）
uv 的逻辑分为“下载 Python 解释器”和“下载第三方包”两部分，都需要配置镜像。
1. 配置 Python 下载镜像（解决 python install 报错）
在 PowerShell 执行以下命令，或将其加入系统环境变量：
$env:UV_PYTHON_INSTALL_MIRROR = "https://mirrors.aliyun.com/python-release/"
2. 配置 PyPI 包索引镜像
编辑（或创建）配置文件 %APPDATA%\uv\uv.toml：
[[index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
四、 跨机器迁移：解决 Exit Code 103 报错
场景回放：将项目源码连同 .venv 文件夹从旧电脑搬到新电脑，运行 uv 命令报错：
error: Querying Python at ...\.venv\Scripts\python.exe failed with exit status exit code: 103
1. 深度复盘
虚拟环境（.venv）是不可移动的。它内部记录了旧电脑的绝对路径。在新电脑上，这些路径变成了“断头路”，导致 uv 无法通过旧的链接找到 Python。
2. 正确的重建流程
不要尝试修复旧环境，直接毁掉重建：
- 清理缓存（可选，但推荐）：
如果之前同步失败过，建议先清理缓存以排除脏数据干扰：uv cache clean - 清理残骸：删除项目根目录下的 .venv 文件夹。
- 下载 Python（如果本地没有）：
uv python install 3.12 - 重新定基 (uv venv)：
手动创建一个干净的、适配当前电脑路径的虚拟环境：uv venv --python 3.12 - 全自动装修 (uv sync)：
如果遇到 Windows Hardlink 权限报错或跨盘符问题，先切换为 Copy 模式
$env:UV_LINK_MODE = "copy" uv syncuv sync 会读取 uv.lock 文件，根据图纸精准地把所有库重新装回来。
五、 核心命令速查表
| 命令 | 场景 | 就像是… |
|---|---|---|
| uv python install | 电脑里没 Python 时 | 从云端领养一个 Python |
| uv venv | 手动创建环境地基 | 买了一个空房子（有了框架） |
| uv sync | 自动安装所有依赖 | 按照装修图纸搬入所有家具 |
| uv run | 运行脚本 | 走进房子开始生活（自动处理环境） |
六、 总结流程（Mermaid 图解）
graph TD
Start[开始: 手动下载 uv.exe] --> Path[配置系统 PATH]
Path --> Mirror[设置 Python & PyPI 镜像源]
Mirror --> InstallPy[uv python install 3.12]
InstallPy --> Migration{是否为迁移项目?}
Migration -- 是 --> Delete[删除旧 .venv 文件夹]
Delete --> Venv[uv venv --python 3.12]
Migration -- 否 --> Venv
Venv --> Sync[uv sync 同步依赖]
Sync --> Run[uv run 运行项目]
style Start fill:#f9f,stroke:#333
style Sync fill:#00ff00,stroke:#333
结语
uv 不仅是一个工具，更是一种“项目即环境”的开发哲学。在内网环境下，掌握了镜像配置和 sync 重建逻辑，你就能在任何机器上实现“一分钟进入开发状态”的极速体验。