快速运行UV构建的项目1. 安装 uv（如未安装）安装完成后，打开新终端执行 uv --version 确认安装成功。

1. 安装 `uv`（如未安装）

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或通过 pip 安装（不推荐作为主要方式）
pip install uv

安装完成后，打开新终端执行 uv --version 确认安装成功。

2. 进入项目目录

cd /path/to/your/project

3. 检查项目配置（可选但推荐）

打开项目根目录的 pyproject.toml，重点关注：

requires-python = ">=x.x"：项目要求的最低 Python 版本
[project.scripts] 或 [project.gui-scripts]：定义了可直接运行的快捷命令
项目通常会在 README.md 中写明官方启动方式，优先参考。

4. 同步依赖 & 创建虚拟环境

uv sync

该命令会：

读取 uv.lock 精确锁定依赖版本
在项目根目录自动创建 .venv 虚拟环境
安装所有生产依赖（加 --dev 可包含开发依赖）

💡 现代 uv 的 uv run 命令已内置自动同步逻辑，因此你也可以跳过此步直接执行第 5 步。

5. 运行项目

根据你的项目入口选择对应方式：

场景	命令示例
通过 `pyproject.toml` 定义的脚本（推荐）	`uv run <脚本名>` 例：`uv run myapp` 或 `uv run start`
直接运行 Python 文件	`uv run python main.py`
运行 Python 模块	`uv run -m your_package_name`
需加载 `.env` 环境变量	`uv run --env-file .env <命令>`

常见问题处理

Python 版本不符：若提示版本不匹配，可让 uv 自动下载并管理所需版本：
```
uv python install 3.11  # 替换为 pyproject.toml 中要求的版本
```

想进入虚拟环境手动调试：

# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1

依赖安装慢或网络问题：可配置国内镜像（写入 ~/.config/uv/uv.toml）：
```
[pip]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
```

📌 最佳实践建议

始终优先查看 README.md，作者通常会提供专属启动命令（如 uv run make dev、uv run fastapi dev src/app.py 等）。
不要手动修改 uv.lock，依赖更新请使用 uv add <包名> 或 uv lock。
uv run 会在每次执行时自动确保环境一致，推荐作为日常运行方式，无需手动 activate。