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

Ne0inhk

23 Mar 2026 — 9 min read

【个人主页：玄同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-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`) - 项目目录已初始化 ### 安装 uv（如未安装） ```powershell # 使用 PowerShell 安装 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # 验证安装 uv --version ``` ## 执行步骤 ### 1. 创建虚拟环境 ```powershell # 创建虚拟环境（使用 Python 3.13） uv venv .venv --python 3.13 # 验证创建成功 .venv\Scripts\python.exe --version ``` > **注意**：如果遇到执行策略错误，请以管理员身份运行 PowerShell 并执行： > ```powershell > Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser > ``` ### 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/ # basedpyright .basedpyright/ ``` ### 3. 安装依赖 使用 `uv add` 命令会自动更新 `pyproject.toml` 并安装依赖： ```powershell # 初始化项目（生成 pyproject.toml） uv init # 添加生产依赖 uv add gradio fastapi sqlalchemy pydantic chromadb openai ` langchain langgraph python-jose bcrypt httpx ` python-dotenv loguru # 添加开发依赖 uv add --dev ruff basedpyright pytest pytest-asyncio pytest-cov ``` > **说明**：`uv add` 是推荐的方式，它会： > - 自动将依赖记录到 `pyproject.toml` > - 生成 `uv.lock` 锁定文件确保版本一致 > - 团队成员只需运行 `uv sync` 即可同步依赖 ### 4. 创建 VS Code 配置 创建 `.vscode/settings.json`： ```json { "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe", "python.terminal.activateEnvironment": 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"], "python.analysis.typeCheckingMode": "basic", "python.testing.pytestEnabled": true, "python.testing.pytestArgs": ["--asyncio-mode=auto"] } ``` 创建 `.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 配置示例 ```toml [project] name = "my-project" version = "0.1.0" description = "项目描述" readme = "README.md" requires-python = ">=3.13" dependencies = [ "gradio>=5.0.0", "fastapi>=0.115.0", "sqlalchemy>=2.0.0", "pydantic>=2.12.0", "chromadb>=0.5.0", "openai>=1.0.0", "langchain>=1.2.0", "langgraph>=1.0.0", "python-jose>=3.3.0", "bcrypt>=4.0.0", "httpx>=0.28.0", "python-dotenv>=1.0.0", "loguru>=0.7.0", ] [project.optional-dependencies] dev = [ "ruff>=0.15.0", "basedpyright>=1.38.0", "pytest>=9.0.0", "pytest-asyncio>=1.3.0", "pytest-cov>=7.0.0", ] [tool.ruff] target-version = "py313" line-length = 100 select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"] ignore = ["E501"] [tool.ruff.format] quote-style = "double" indent-style = "space" [tool.basedpyright] pythonVersion = "3.13" typeCheckingMode = "standard" reportMissingImports = true reportMissingTypeStubs = true [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" addopts = "--cov=src --cov-report=term-missing --cov-report=html" [tool.coverage.run] source = ["src"] branch = true omit = ["tests/*", "*/__pycache__/*"] [tool.coverage.report] exclude_lines = [ "pragma: no cover", "def __repr__", "raise NotImplementedError", "if TYPE_CHECKING:", ] ``` ### 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 . # 类型检查 basedpyright . # 运行测试 pytest # 运行测试（带覆盖率） pytest --cov ``` ## 验证安装 ```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.13` | 创建虚拟环境 | | `uv pip install <pkg>` | 安装包 | | `uv add <pkg>` | 添加依赖到 pyproject.toml | | `uv add --dev <pkg>` | 添加开发依赖 | | `uv sync` | 同步依赖 | | `uv run <command>` | 在虚拟环境中运行命令 | | `pytest --cov` | 运行测试并生成覆盖率报告 | ```

如何使用这个 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 是我日常开发的得力助手，希望它也能帮助到你！