利用 UV 与 Trae Skill 快速搭建 Python 开发环境

执行步骤

1. 创建虚拟环境

# 创建虚拟环境（使用 Python 3.13）
uv venv .venv --python 3.13
# 验证创建成功
.venv\Scripts\python.exe --version

注意：如果遇到执行策略错误，请以管理员身份运行 PowerShell 并执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2. 配置 .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 并安装依赖：

# 初始化项目（生成 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：

{
 "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：

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

创建 .vscode/launch.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 配置示例

[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：

# 项目规则

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

### 虚拟环境激活
```powershell
.venv\Scripts\Activate.ps1

依赖管理

# 安装依赖
uv pip install <package-name>
# 查看依赖
uv pip list
# 导出依赖
uv pip freeze > requirements.txt

代码规范

# 代码检查
ruff check .
# 代码格式化
ruff format .
# 类型检查
basedpyright .
# 运行测试
pytest
# 运行测试（带覆盖率）
pytest --cov

验证安装

# 验证 Python 版本
.venv\Scripts\python.exe --version
# 验证依赖安装
.venv\Scripts\python.exe -c "import fastapi; import gradio; print('OK')"
# 使用 uv 同步依赖
uv sync

常用命令速查

如何使用这个 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 代码检查工具