# onekeysetuv

**Repository Path**: Dinomorphia/onekeysetuv

## Basic Information

- **Project Name**: onekeysetuv
- **Description**: 一键配置uv和python的软件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UV 一键配置工具（OneKeySetupUV）

一个 Windows 图形化小工具，把 **uv / pip / Python** 的「储存位置、包缓存位置、包储存位置」一次性配置到指定目录，
并统一换成国内镜像（pip 与 uv 使用**阿里云**，uv 自身下载走阿里云 PyPI 镜像，受管 Python 走**南京大学 GitHub Release 镜像**）。

- 图形界面：`customtkinter`
- 打包：`PyInstaller`
- 运行依赖：**仅 customtkinter 一个第三方库**（下载、解压、注册表读写全部使用标准库）

---

## 功能一览

| 能力 | 说明 |
| --- | --- |
| 极简模式 | 只选一个根目录，其余目录自动推导 |
| 高级模式 | uv 储存 / uv 包缓存 / uv 包存储 / uv Python / pip 包缓存 / pip 包存储 / 系统 Python 位置 分别指定 |
| 换源 | pip 写 `pip.ini`，uv 写 `uv.toml`，并写入 `PIP_INDEX_URL` / `UV_DEFAULT_INDEX` 等环境变量 |
| 安装 uv | 从阿里云 PyPI 镜像抓取 `uv-*-py3-none-win_amd64.whl`，直接解压出 `uv.exe` / `uvx.exe`（无需本机已有 pip） |
| 安装 Python | `uv python install` + `UV_PYTHON_INSTALL_MIRROR`，从国内镜像下载受管解释器 |
| 写环境变量 | 用户级变量（`HKCU\Environment`），**无需管理员权限**；并把相关目录追加进 `PATH` |
| 一键还原 | 删除本程序写入的变量 / PATH 条目，并还原被覆盖的 `uv.toml`、`pip.ini`（原文件已自动备份） |

### 极简模式目录结构

```
<根目录>\
├── uv\              uv.exe、uvx.exe（同时作为 uv tool / python 的 bin 目录）
├── cache\
│   ├── uv\          UV_CACHE_DIR（uv 包缓存）
│   └── pip\         PIP_CACHE_DIR（pip 包缓存）
├── tools\uv\        UV_TOOL_DIR（uv tool install 的工具）
├── packages\pip\    PIP_TARGET（pip 安装的包）
├── python\          UV_PYTHON_INSTALL_DIR（受管 Python）
└── config\          uv.toml、pip.ini
```

### 写入的环境变量

```
UV_INSTALL_DIR            UV_CACHE_DIR            UV_TOOL_DIR
UV_TOOL_BIN_DIR           UV_PYTHON_INSTALL_DIR   UV_PYTHON_BIN_DIR
UV_PYTHON_CACHE_DIR       UV_DEFAULT_INDEX        UV_INDEX_URL
UV_PYTHON_INSTALL_MIRROR  UV_CONFIG_FILE
PIP_INDEX_URL             PIP_TRUSTED_HOST        PIP_CACHE_DIR
PIP_TARGET                PIP_CONFIG_FILE
以及 PATH：uv 目录、pip 目标目录的 Scripts/bin、系统 Python 及其 Scripts
```

---

## 运行

```powershell
python -m pip install -r requirements.txt
python main.py
```

> 也可以直接从源码目录运行，无需先装依赖之外的东西；`customtkinter` 是唯一的运行依赖。

---

## 打包

```powershell
python build.py            # 单文件、无控制台，产物在 dist\OneKeySetupUV.exe
python build.py --mirror   # 先用阿里云镜像安装依赖再打包
python build.py --console  # 保留控制台，便于排查问题
python build.py --onedir   # 目录形式（启动更快）
```

等价的手工命令：

```powershell
pyinstaller --noconfirm --clean --onefile --windowed --name OneKeySetupUV `
  --collect-all customtkinter --paths . main.py
```

`--collect-all customtkinter` 是必须的，否则打包后主题资源缺失。

---

## 项目结构

```
main.py                       入口（含崩溃日志与全局异常捕获）
build.py                      PyInstaller 打包脚本
onekey/
├── core/
│   ├── mirrors.py            镜像站点常量（阿里云 / 南京大学 / 清华 …）
│   ├── config.py             配置模型、极简模式布局、校验
│   ├── winenv.py             Windows 用户环境变量读写（winreg）与 PATH 管理
│   ├── state.py              改动记录与回滚（%APPDATA%\OneKeySetupUV）
│   ├── downloader.py         标准库下载器（重试 + 进度）
│   ├── uv_installer.py       从 PyPI 镜像解析 / 下载 / 解压 uv wheel
│   ├── python_installer.py   受管 Python 安装（uv + 国内镜像）
│   ├── confwriter.py         uv.toml / pip.ini 生成、环境变量应用与清理
│   └── setup_runner.py       一键流程编排
└── ui/
    ├── theme.py              配色与字体
    ├── widgets.py            Card / PathRow / SwitchRow / LogPanel / StatusBar
    └── app.py                主窗口（极简模式 / 高级模式 / 使用说明 + 运行日志）
```

---

## 注意事项

1. **`PIP_TARGET` 的影响**：开启后 pip 默认把包装进指定目录而不是 `site-packages`，
   某些依赖 `site-packages` 的工具可能找不到包。可在「高级模式 → 执行内容」中关闭。
2. **环境变量生效时机**：程序会广播 `WM_SETTINGCHANGE`，但已经打开的终端 / 编辑器需要重开才能看到新变量。
3. **uv.toml 字段是严格校验的**：uv 遇到未知字段会直接报错，因此本程序只在 `uv.toml` 中写入 uv 官方支持的项；
   缓存、工具、Python 等目录位置通过环境变量设置（这也是 uv 官方推荐方式）。
4. **回滚**：所有改动都记录在 `%APPDATA%\OneKeySetupUV\state.json`，被覆盖的配置文件备份在
   `%APPDATA%\OneKeySetupUV\backup\`。点「清除本程序设置」即可还原（不会删除已下载的文件）。
5. **镜像可用性**：第三方镜像偶尔会调整地址。若下载失败，可在「高级模式 → 镜像源」里换成清华 TUNA 等其他镜像。