## 一、项目初始化

| 场景 | 命令 | 说明 |
|------|------|------|
| 创建新项目 | `uv init my-project` | 生成项目目录、`pyproject.toml`、`.python-version` |
| 在已有目录初始化 | `uv init` | 当前目录下初始化，不新建子目录 |
| 指定 Python 版本创建 | `uv init --python 3.12 my-project` | 锁定 Python 版本 |
| 创建库项目（不是应用） | `uv init --lib` | 生成适合打包发布的结构 |

## 二、虚拟环境

| 场景           | 命令                                  | 说明                  |
| ------------ | ----------------------------------- | ------------------- |
| 创建虚拟环境       | `uv venv`                           | 自动创建 `.venv`        |
| 创建时指定 Python | `uv venv --python 3.12`             | 用特定版本               |
| 创建时带 pip     | `uv venv --seed`                    | 装上 pip 和 setuptools |
| 激活环境         | `.venv\Scripts\activate`（Windows）   | 跟标准 venv 一样         |
| 删除环境         | `Remove-Item -Recurse -Force .venv` | 删掉即可，之后能重新创建        |

## 三、依赖管理（核心流程）

### 添加依赖

| 命令 | 说明 |
|------|------|
| `uv add numpy` | 安装并写入 `pyproject.toml` |
| `uv add pandas --dev` | 安装为开发依赖 |
| `uv add "numpy>=2.0,<3.0"` | 带版本约束 |
| `uv add git+https://github.com/user/repo.git` | 从 Git 安装 |
| `uv add ./local-package` | 从本地路径安装 |

### 移除依赖

| 命令 | 说明 |
|------|------|
| `uv remove numpy` | 卸载并从 `pyproject.toml` 移除 |

### 同步/安装

| 命令 | 说明 |
|------|------|
| `uv sync` | 根据锁文件安装所有依赖（有锁文件时） |
| `uv sync --no-dev` | 只安装正式依赖，跳过开发依赖 |
| `uv lock` | 生成/更新 `uv.lock` 锁文件 |
| `uv lock --upgrade-package numpy` | 只升级指定包的锁版本 |
| `uv tree` | 查看依赖树 |

## 四、用 uv 运行/执行

| 命令 | 说明 |
|------|------|
| `uv run python main.py` | 在项目环境中运行脚本 |
| `uv run python` | 进入项目环境的 Python 交互模式 |
| `uv run pytest` | 运行项目中的测试 |
| `uv run ipython` | 运行任意命令，自动使用当前环境 |
| `uv run --with requests python` | 临时加一个包再运行（不写入依赖） |
| `uvx ruff check .` | 运行一次性工具（等同于 `uv tool run`） |

## 五、Python 版本管理

| 命令                       | 说明                |
| ------------------------ | ----------------- |
| `uv python list`         | 查看已安装的 Python 版本  |
| `uv python install 3.12` | 安装指定版本            |
| `uv python pin 3.12`     | 为当前项目锁定 Python 版本 |

## 六、典型工作流

### 从头开始一个项目

```powershell
# 1. 创建项目
uv init myproject
cd myproject

# 2. 添加依赖（自动创建 .venv 并安装）
uv add numpy pandas

# 3. 写代码...

# 4. 运行
uv run python main.py
```

### 克隆已有项目

```powershell
# 1. 克隆
git clone <url>
cd project

# 2. 一键装上所有依赖
uv sync

# 3. 运行
uv run python main.py
```

### 用 pip 风格的即时安装（不写 pyproject.toml）

```powershell
# 只是装个包试试，不想污染项目定义
uv pip install requests
uv pip list
uv pip uninstall requests
```