我的 Trae Skill 实践｜使用 UV 工具一键搭建 Python 项目开发环境

【个人主页：玄同765】

大语言模型（LLM）开发工程师 ｜中国传媒大学·数字媒体技术（智能交互与游戏设计）

**深耕领域：**大语言模型开发 / RAG知识库 / AI Agent落地 / 模型微调

**技术栈：**Python / LangChain/RAG（Dify+Redis+Milvus）| SQL/NumPy | FastAPI+Docker ️

**工程能力：**专注模型工程化部署、知识库构建与优化，擅长全流程解决方案

「让AI交互更智能，让技术落地更高效」

欢迎技术探讨/项目合作！ 关注我，解锁大模型与智能交互的无限可能！

---

前言

作为一名 Python 开发者，项目环境搭建是每次开新项目的必经之路。虚拟环境创建、依赖管理、IDE 配置...这些重复性工作不仅耗时，还容易出错。最近我在使用 Trae AI IDE 时，发现了一个强大的功能 - Skill 系统，它允许我们将常用的工作流程封装成可复用的技能。

今天，我要分享的是我编写的一个 Skill：uv-python-setup，它可以一键完成 Python 项目的完整环境搭建，包括虚拟环境、VS Code 配置、依赖管理等。

---

为什么选择 UV？

在介绍 Skill 之前，先说说为什么选择 uv 作为工具：

特性	UV	传统工具 (pip/virtualenv)
速度	极快（Rust 编写）	较慢
统一性	虚拟环境 + 依赖管理一体	需要多个工具配合
pyproject.toml	原生支持	需要额外配置
兼容性	完全兼容 pip	-
缓存	智能缓存，极速重装	有限

uv 由 Astral 团队开发（也是 ruff 的开发者），已经成为我 Python 开发的首选工具。

---

Skill 功能概览

这个 Skill 可以帮你完成以下所有事情：

1. ✅ 创建虚拟环境 - 使用指定 Python 版本
2. ✅ 配置 .gitignore - 排除虚拟环境和临时文件
3. ✅ 安装依赖 - 生产依赖和开发依赖
4. ✅ VS Code 配置 - 自动激活虚拟环境、代码格式化、调试配置
5. ✅ 生成 pyproject.toml - 使用 uv 自动生成项目配置
6. ✅ 创建项目规则文档 - 记录项目配置和使用说明

---

完整 Skill 代码

以下是 uv-python-setup Skill 的完整内容，你可以直接复制使用：

---
name: "uv-python-setup"
description: "使用 uv 工具快速搭建 Python 项目开发环境，包括虚拟环境创建、VS Code 配置、依赖管理。Invoke when user wants to set up a Python project with uv, create venv, configure VS Code auto-activation, or manage dependencies with pyproject.toml."
---

# UV Python 项目环境搭建

使用 uv 工具快速搭建完整的 Python 项目开发环境，包含虚拟环境、VS Code 配置和依赖管理。

## 前置要求

- 已安装 uv 工具 (`uv --version`)
- 项目目录已初始化

## 执行步骤

### 1. 创建虚拟环境

```bash
# 创建虚拟环境（使用 Python 3.11）
uv venv .venv --python 3.11

# 验证创建成功
.venv\Scripts\python.exe --version
```

### 2. 配置 .gitignore

创建 `.gitignore` 文件，排除虚拟环境和临时文件：

```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# 虚拟环境
.venv/
venv/
ENV/
env/

# IDE
.idea/
.vscode/
*.swp
*.swo
*~
.DS_Store

# 环境变量
.env
.env.local
.env.*.local

# 数据库
*.db
*.sqlite
*.sqlite3

# 日志
logs/
*.log

# 测试覆盖率
htmlcov/
.coverage
.coverage.*
coverage.xml
*.cover

# pytest
.pytest_cache/

# mypy
.mypy_cache/
.dmypy.json
dmypy.json
```

### 3. 安装依赖

```bash
# 安装生产依赖
uv pip install --python .venv\Scripts\python.exe \
    gradio fastapi sqlalchemy pydantic chromadb openai \
    langchain langgraph python-jose bcrypt httpx \
    python-dotenv loguru

# 安装开发依赖
uv pip install --python .venv\Scripts\python.exe \
    ruff mypy pytest
```

### 4. 创建 VS Code 配置

创建 `.vscode/settings.json`：

```json
{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
    "python.pythonPath": "${workspaceFolder}/.venv/Scripts/python.exe",
    "python.terminal.activateEnvironment": true,
    "python.terminal.activateEnvInCurrentTerminal": true,
    "terminal.integrated.profiles.windows": {
        "PowerShell": {
            "source": "PowerShell",
            "args": ["-NoExit", "-Command", ". ${workspaceFolder}/.venv/Scripts/Activate.ps1"],
            "icon": "terminal-powershell"
        }
    },
    "terminal.integrated.defaultProfile.windows": "PowerShell",
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
        "source.fixAll.ruff": "explicit",
        "source.organizeImports.ruff": "explicit"
    },
    "ruff.interpreter": ["${workspaceFolder}/.venv/Scripts/python.exe"],
    "ruff.path": ["${workspaceFolder}/.venv/Scripts/ruff.exe"],
    "python.analysis.typeCheckingMode": "basic",
    "python.testing.pytestEnabled": true,
    "python.testing.pytestPath": "${workspaceFolder}/.venv/Scripts/pytest.exe"
}
```

创建 `.vscode/extensions.json`：

```json
{
    "recommendations": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "charliermarsh.ruff",
        "ms-python.debugpy"
    ]
}
```

创建 `.vscode/launch.json`：

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "python": "${workspaceFolder}/.venv/Scripts/python.exe"
        },
        {
            "name": "Python: FastAPI",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": ["main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"],
            "python": "${workspaceFolder}/.venv/Scripts/python.exe",
            "console": "integratedTerminal"
        }
    ]
}
```

### 5. 生成 pyproject.toml

使用 uv 自动生成项目配置：

```bash
# 初始化项目
uv init --python .venv\Scripts\python.exe

# 添加生产依赖
uv add gradio fastapi sqlalchemy pydantic chromadb openai \
    langchain langgraph python-jose bcrypt httpx \
    python-dotenv loguru

# 添加开发依赖
uv add --dev ruff mypy pytest
```

### 6. 创建项目规则文档

创建 `.trae/project_rules.md`：

```markdown
# 项目规则

## Python 虚拟环境

本项目使用 uv 创建的虚拟环境，位于 `.venv/` 目录下。

### 虚拟环境激活

```powershell
.venv\Scripts\Activate.ps1
```

### 依赖管理

```bash
# 安装依赖
uv pip install <package-name>

# 查看依赖
uv pip list

# 导出依赖
uv pip freeze > requirements.txt
```

### 代码规范

```bash
# 代码检查
ruff check .

# 代码格式化
ruff format .

# 类型检查
mypy .

# 运行测试
pytest
```
```

## 验证安装

```bash
# 验证 Python 版本
.venv\Scripts\python.exe --version

# 验证依赖安装
.venv\Scripts\python.exe -c "import fastapi; import gradio; print('OK')"

# 使用 uv 同步依赖
uv sync
```

## 常用命令速查

| 命令 | 说明 |
|-----|------|
| `uv venv .venv --python 3.11` | 创建虚拟环境 |
| `uv pip install <pkg>` | 安装包 |
| `uv add <pkg>` | 添加依赖到 pyproject.toml |
| `uv add --dev <pkg>` | 添加开发依赖 |
| `uv sync` | 同步依赖 |
| `uv run <command>` | 在虚拟环境中运行命令 |

---

如何使用这个 Skill

在 Trae 中使用

1. 将上述 Skill 代码保存到 .trae/skills/uv-python-setup/SKILL.md
2. 在 Trae 中打开项目
3. 告诉 AI："帮我搭建 Python 项目环境"
4. AI 会自动调用这个 Skill 完成所有配置

手动执行

如果你不使用 Trae，也可以按照 Skill 中的步骤手动执行，效果完全一样。

---

实际效果展示

使用这个 Skill 后，你的项目结构会变成这样：

my-project/
├── .venv/                      # Python 虚拟环境
├── .vscode/
│   ├── settings.json           # VS Code 配置（自动激活虚拟环境）
│   ├── extensions.json         # 推荐扩展
│   └── launch.json             # 调试配置
├── .trae/
│   └── project_rules.md        # 项目规则文档
├── pyproject.toml              # 项目依赖配置
├── uv.lock                     # 依赖锁定文件
├── .gitignore                  # Git 忽略配置
└── src/                        # 源代码目录

VS Code 自动激活效果

打开 VS Code 终端时，会自动激活虚拟环境：

# 打开终端后，你会看到：
(.venv) PS D:\my-project> 
# ^^^^^^ 虚拟环境已自动激活

# 直接运行 Python 命令
python --version  # Python 3.11.x

代码自动格式化

保存 Python 文件时，会自动使用 Ruff 进行格式化：

# 保存前（混乱的代码）
def  my_function(x,y,z):
    return x+y+z

# 保存后（自动格式化）
def my_function(x, y, z):
    return x + y + z

---

进阶技巧

1. 自定义依赖

根据项目需求修改 Skill 中的依赖列表：

# 数据科学项目
uv add numpy pandas matplotlib jupyter

# Web 开发
uv add django flask requests beautifulsoup4

# 机器学习
uv add scikit-learn torch tensorflow

2. 多环境配置

为不同环境创建不同的依赖组：

# 测试依赖
uv add --group test pytest pytest-cov pytest-asyncio

# 文档依赖
uv add --group docs mkdocs mkdocs-material

3. 与 CI/CD 集成

在 GitHub Actions 中使用：

- name: Setup Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

- name: Install uv
  run: pip install uv

- name: Sync dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest

---

常见问题

Q1: uv 和 pip 有什么区别？

A: uv 完全兼容 pip，但速度更快。你可以把 uv 看作是 pip 的"极速版"，所有 pip 命令在 uv 中都可以使用。

Q2: 如何迁移现有项目到 uv？

A: 非常简单：

# 1. 安装 uv
pip install uv

# 2. 创建虚拟环境
uv venv .venv

# 3. 安装现有依赖
uv pip install -r requirements.txt

# 4. 生成 pyproject.toml
uv init

Q3: 可以在 Linux/Mac 上使用吗？

A: 当然可以！uv 支持 Windows、Linux 和 macOS。Skill 中的路径需要根据系统调整：

• Windows : .venv\Scripts\python.exe
• Linux/Mac : .venv/bin/python

---

总结

通过将环境搭建流程封装成 Skill，我们可以：

1. 节省时间 - 一键完成所有配置，无需手动操作
2. 减少错误 - 标准化的流程，避免遗漏步骤
3. 团队协作 - 所有成员使用相同的开发环境
4. 可复用 - 在新项目中重复使用

这个 Skill 是我日常开发的得力助手，希望它也能帮助到你！

---

相关链接

• uv 官方文档
• Trae 官网
• Ruff 代码检查工具
• 我的 GitHub

---

如果你有任何问题或建议，欢迎在评论区留言！