Add installation guides for OpenClaw and uv package manager

2026-04-28 12:56:13 +08:00
parent 2830a10a1b
commit b13cd32d6a
34 changed files with 0 additions and 0 deletions
@@ -0,0 +1,568 @@
+# 《极速 Python 包管理神器：uv 体验报告》
+
+## 博客大纲
+
+**主题定位**：技术分享型 —— 面向 Python 开发者，推荐 uv 包管理工具
+
+**目标读者**：
+- 使用 Python 的开发者
+- 对包管理工具有一定了解（pip、conda 用户）
+- 追求开发效率和现代化工具的程序员
+
+**字数目标**：15000-20000 字
+
+**代码语言**：以 shell 命令为主，Python 代码示例辅助
+
+**侧重点**：命令讲解 / 实操演示 / 理论说明均衡
+
+---
+
+## 第一章：引言 —— 为什么我要推荐 uv？
+
+**字数**：约 1500 字
+
+### 1.1 我的 Python 开发环境变迁
+
+讲述从 pip 到 conda 再到 uv 的使用历程：
+- 最初使用 pip：简单但慢
+- 后来用 conda：解决了依赖问题但体积庞大
+- 遇到 uv：一见钟情
+
+### 1.2 什么是 uv？
+
+简单介绍 uv：
+- Astral 公司出品（ruff、ruff 的公司）
+- 用 Rust 编写
+- 极速 Python 包管理器
+- 定位：替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv
+
+### 1.3 uv 的核心理念
+
+- **极速**：比 pip 快 10-100 倍
+- **统一**：一个工具解决所有问题
+- **现代化**：支持 PEP 标准，符合 Python 发展趋势
+
+### 1.4 这篇博客的目标
+
+- 让读者了解 uv 是什么
+- 学会安装和基本使用
+- 理解 uv 的优势
+- 能够迁移到 uv 工作流
+
+---
+
+## 第二章：安装与配置 —— 5 分钟上手 uv
+
+**字数**：约 1500 字
+
+### 2.1 Windows 安装（推荐 PowerShell）
+
+```powershell
+# 方法一：使用 PowerShell 安装脚本
+irm https://astral.sh/uv/install.ps1 | iex
+
+# 方法二：使用 winget
+winget install --id=astral-sh.uv -e
+
+# 方法三：使用 scoop
+scoop install uv
+```
+
+### 2.2 macOS / Linux 安装
+
+```bash
+# macOS
+brew install uv
+
+# Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 2.3 验证安装
+
+```powershell
+uv --version
+# uv 0.x.x
+```
+
+### 2.4 配置 PATH（如果需要）
+
+### 2.5 首次运行体验
+
+展示 uv 的速度优势
+
+---
+
+## 第三章：虚拟环境管理 —— 从此告别 conda 的臃肿
+
+**字数**：约 2500 字
+
+### 3.1 创建虚拟环境
+
+```powershell
+# 创建默认环境（.venv）
+uv venv
+
+# 创建自定义名称
+uv venv myenv
+
+# 指定 Python 版本
+uv venv --python 3.11 myenv
+uv venv --python 3.12 myenv
+
+# 列出可用版本
+uv python list
+```
+
+### 3.2 激活环境
+
+```powershell
+# PowerShell
+.venv\Scripts\Activate.ps1
+
+# CMD
+.venv\Scripts\activate.bat
+
+# Bash (Git Bash / WSL)
+source .venv/Scripts/activate
+```
+
+### 3.3 与其他工具对比
+
+| 特性 | uv | conda | venv |
+|------|-----|-------|------|
+| 创建速度 | 极快（<1秒）| 慢 | 快 |
+| 体积 | 小（几MB）| 大（数百MB）| 无 |
+| Python 版本 | 任意 | 有限 | 系统版本 |
+
+### 3.4 删除环境
+
+```powershell
+Remove-Item -Recurse -Force .venv
+# 简单粗暴，没有残留
+```
+
+---
+
+## 第四章：包管理 —— pip 的完美替代者
+
+**字数**：约 3000 字
+
+### 4.1 安装包
+
+```powershell
+# 基本安装
+uv pip install requests
+
+# 安装多个包
+uv pip install requests numpy pandas
+
+# 指定版本
+uv pip install requests==2.28.0
+uv pip install "requests>=2.28,<3.0"
+
+# 从文件安装
+uv pip install -r requirements.txt
+
+# 从 Git 安装
+uv pip install git+https://github.com/user/repo.git
+
+# 从 URL 安装
+uv pip install https://example.com/package.tar.gz
+```
+
+### 4.2 卸载包
+
+```powershell
+uv pip uninstall requests
+uv pip uninstall requests numpy pandas
+```
+
+### 4.3 查看已安装的包
+
+```powershell
+uv pip freeze
+uv pip list
+```
+
+### 4.4 依赖同步
+
+```powershell
+# 同步到 requirements.txt 定义的状态
+uv pip sync requirements.txt
+
+# 生成 requirements.txt
+uv pip freeze > requirements.txt
+```
+
+### 4.5 性能对比实测
+
+展示 uv vs pip 的安装速度对比：
+- 简单包（requests）
+- 复杂包（numpy）
+- 大包（tensorflow）
+
+---
+
+## 第五章：Python 版本管理 —— 一个命令切换版本
+
+**字数**：约 2000 字
+
+### 5.1 列出可用版本
+
+```powershell
+uv python list
+uv python list --only-installed
+```
+
+### 5.2 安装指定版本
+
+```powershell
+uv python install 3.11
+uv python install 3.12
+uv python install 3.10.14
+```
+
+### 5.3 卸载版本
+
+```powershell
+uv python uninstall 3.10
+```
+
+### 5.4 在项目中指定 Python 版本
+
+在 `pyproject.toml` 中：
+```toml
+[project]
+requires-python = ">=3.11"
+```
+
+### 5.5 实际使用场景
+
+- 维护多个项目，每个需要不同的 Python 版本
+- 测试代码在不同 Python 版本下的兼容性
+
+---
+
+## 第六章：项目管理 —— 从初始化到运行的完整流程
+
+**字数**：约 2500 字
+
+### 6.1 初始化新项目
+
+```powershell
+# 创建基础项目
+uv init myproject
+
+# 创建可打包项目
+uv init --package myproject
+
+# 创建库项目
+uv init --lib
+
+# 创建脚本项目
+uv init --script
+```
+
+### 6.2 项目结构
+
+展示 `uv init` 生成的文件结构：
+```
+myproject/
+├── .python-version
+├── pyproject.toml
+├── README.md
+├── src/
+│   └── myproject/
+│       ├── __init__.py
+│       └── main.py
+└── tests/
+    └── test_example.py
+```
+
+### 6.3 添加依赖
+
+```powershell
+cd myproject
+uv add requests
+uv add "flask>=2.0"
+uv add --dev pytest
+```
+
+### 6.4 运行项目
+
+```powershell
+uv run python src/myproject/main.py
+uv run pytest
+uv run --package mypackage
+```
+
+### 6.5 锁定依赖
+
+```powershell
+uv lock
+uv sync
+```
+
+---
+
+## 第七章：工具管理（uvx）—— 告别全局安装的烦恼
+
+**字数**：约 2000 字
+
+### 7.1 什么是 uvx？
+
+uvx = uv + npx，临时运行工具
+
+### 7.2 运行常用工具
+
+```powershell
+# 运行 black 格式化
+uvx black .
+
+# 运行 ruff 检查
+uvx ruff check .
+
+# 运行 ruff 格式化
+uvx ruff format .
+
+# 启动 Jupyter Lab
+uvx jupyter lab
+
+# 运行 httpie
+uvx --from httpie http GET example.com
+
+# 运行 mypy 类型检查
+uvx mypy src/
+```
+
+### 7.3 安装全局工具
+
+```powershell
+# 安装为全局工具
+uv tool install black
+uv tool install ruff
+
+# 列出已安装工具
+uv tool list
+
+# 升级工具
+uv tool upgrade black
+
+# 卸载工具
+uv tool uninstall black
+```
+
+### 7.4 工具来源
+
+```powershell
+# 从 PyPI 安装
+uv tool install from-pypi
+
+# 从 Git 安装
+uv tool install --git https://github.com/user/repo.git
+
+# 从本地路径安装
+uv tool install --path ./mytool
+```
+
+---
+
+## 第八章：实战案例 —— 我的日常开发工作流
+
+**字数**：约 3000 字
+
+### 8.1 场景一：快速创建数据分析环境
+
+```powershell
+# 一行命令搞定
+uv venv --python 3.11
+uv add pandas numpy matplotlib jupyter
+uv run jupyter lab
+```
+
+### 8.2 场景二：深度学习项目环境
+
+```powershell
+uv venv --python 3.10
+uv add torch torchvision torchaudio
+uv add --dev pytest black ruff
+uv lock
+```
+
+### 8.3 场景三：Web API 开发
+
+```powershell
+uv init fastapi-demo --package
+cd fastapi-demo
+uv add fastapi uvicorn pydantic
+uv run uvicorn src.fastapi_demo:app --reload
+```
+
+### 8.4 场景四：多项目维护
+
+展示如何用 uv 管理多个项目，每个使用不同配置
+
+### 8.5 我的 .NET 开发经验对比
+
+```
+回顾 .NET 的 dotnet CLI：
+- dotnet new 创建项目
+- dotnet add package 安装包
+- dotnet run 运行项目
+
+uv 的工作流几乎一样，甚至更简单！
+```
+
+---
+
+## 第九章：进阶技巧与最佳实践
+
+**字数**：约 2000 字
+
+### 9.1 依赖组管理
+
+```powershell
+# 添加开发依赖
+uv add --group dev pytest pytest-cov
+
+# 生产依赖
+uv add requests
+
+# 只安装开发依赖
+uv sync --group dev
+
+# 只安装生产依赖
+uv sync
+```
+
+### 9.2 依赖解析与锁定
+
+```powershell
+uv lock           # 生成锁文件
+uv sync           # 确保环境与锁文件一致
+uv lock --upgrade # 升级依赖
+```
+
+### 9.3 缓存管理
+
+```powershell
+uv cache clean    # 清理缓存
+uv cache prune   # 移除未使用的缓存
+uv cache dir      # 显示缓存目录
+```
+
+### 9.4 离线环境
+
+```powershell
+# 在有网环境准备
+uv pip install requests --target ./packages
+
+# 在无网环境使用
+uv pip install --offline --target ./packages requests
+```
+
+### 9.5 环境变量配置
+
+```bash
+UV_PYTHON=3.11              # 指定默认 Python 版本
+UV_CACHE_DIR=/path/to/cache  # 指定缓存目录
+UV_NO_PROGRESS=1             # 禁用进度条
+```
+
+---
+
+## 第十章：总结与资源
+
+**字数**：约 1500 字
+
+### 10.1 uv 的核心优势总结
+
+| 优势 | 说明 |
+|------|------|
+| 极速 | 比 pip 快 10-100 倍 |
+| 统一 | 替代 6 个工具 |
+| 轻量 | 几 MB vs 几百 MB |
+| 现代 | 符合 PEP 标准 |
+| 可靠 | 来自 Astral 公司 |
+
+### 10.2 迁移指南
+
+**从 pip 迁移**：
+```powershell
+# 替代
+pip install requests
+# 使用
+uv pip install requests
+
+# 替代
+pip freeze > requirements.txt
+# 使用
+uv pip freeze > requirements.txt
+```
+
+**从 conda 迁移**：
+```powershell
+# 替代
+conda create -n myenv python=3.11
+conda activate myenv
+conda install requests
+# 使用
+uv venv --python 3.11 myenv
+.venv\Scripts\Activate.ps1
+uv pip install requests
+```
+
+### 10.3 常见问题
+
+- Q: uv 和 pip 冲突吗？
+- A: 不冲突，uv 只是 pip 的替代品
+
+- Q: 我的现有项目能用 uv 吗？
+- A: 可以，直接在项目目录使用 uv pip install
+
+- Q: uv 支持 Windows 吗？
+- A: 完全支持，性能更好
+
+### 10.4 学习资源
+
+- 官方文档：https://docs.astral.sh/uv/
+- GitHub 仓库：https://github.com/astral-sh/uv
+- Discord 社区
+
+### 10.5 结束语
+
+呼吁读者尝试 uv，体验极速的 Python 开发
+
+---
+
+## 附录：命令速查表
+
+| 场景 | 命令 |
+|------|------|
+| 安装 uv | `irm https://astral.sh/uv/install.ps1 \| iex` |
+| 创建环境 | `uv venv --python 3.11` |
+| 激活环境 | `.venv\Scripts\Activate.ps1` |
+| 安装包 | `uv pip install requests numpy` |
+| 卸载包 | `uv pip uninstall requests` |
+| 列出包 | `uv pip list` |
+| 同步依赖 | `uv pip sync requirements.txt` |
+| 安装 Python | `uv python install 3.12` |
+| 创建项目 | `uv init myproject` |
+| 添加依赖 | `uv add requests flask` |
+| 运行脚本 | `uv run python script.py` |
+| 运行工具 | `uvx black .` |
+| 安装工具 | `uv tool install black` |
+| 清理缓存 | `uv cache clean` |
+
+---
+
+**大纲字数**：约 23000 字
+
+**预计文章字数**：15000-20000 字
+
+**写作风格**：
+- 口语化，像在和读者聊天
+- 强调实战，提供大量命令示例
+- 对比其他工具时客观公正
+- 适合有一定 Python 基础的开发者