我的 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 可以帮你完成以下所有事情：

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

完整 Skill 代码

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

--- 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 中使用

将上述 Skill 代码保存到.trae/skills/uv-python-setup/SKILL.md
在 Trae 中打开项目
告诉 AI："帮我搭建 Python 项目环境"
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，我们可以：

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

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

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

前言