62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
---
|
||
name: "uv-env-setup"
|
||
description: "用 uv 准备并维护本项目 Python 运行环境（pyproject.toml → uv sync → uv run）。当用户提到环境准备/环境初始化/装依赖/重建 venv，脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），.venv 缺失或损坏，或首次运行 scripts/、skills/*/scripts/ 下的 Python 脚本时使用。"
|
||
---
|
||
|
||
# uv 运行环境准备
|
||
|
||
本项目所有 Python 脚本共用一套 uv 管理的环境：根目录 `pyproject.toml` 是依赖的**唯一事实来源**，`uv sync` 落地 `.venv\`，`uv run` 执行脚本（自动使用该环境，免激活、免手装依赖）。
|
||
|
||
## 步骤 1：确认 uv 可用
|
||
|
||
```powershell
|
||
uv --version
|
||
```
|
||
|
||
未安装时任选其一（Windows）：
|
||
|
||
- `winget install astral-sh.uv`
|
||
- `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
|
||
- `pip install uv`
|
||
|
||
装完重开终端使 PATH 生效。
|
||
|
||
**完成判据**：`uv --version` 打印出版本号。
|
||
|
||
## 步骤 2：同步依赖
|
||
|
||
项目根目录（`pyproject.toml` 所在处）执行：
|
||
|
||
```powershell
|
||
uv sync
|
||
```
|
||
|
||
- 首次运行自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright）。
|
||
- 本机无兼容 Python 时，uv 自动下载托管 Python（`requires-python = ">=3.10"`）。
|
||
- `uv run` 本身也会隐式同步；显式 `uv sync` 是为了在跑脚本前把依赖错误一次性暴露出来。
|
||
|
||
**完成判据**：命令退出码 0，且项目根出现 `.venv\` 目录。
|
||
|
||
## 步骤 3：验证
|
||
|
||
```powershell
|
||
uv run python -c "import pandas, openpyxl, playwright; print('env OK')"
|
||
uv run python skills\youtube-studio-csv-download\scripts\youtube_export_download.py --selftest
|
||
uv run python skills\yt-studio-url-builder\scripts\build_studio_urls.py --help
|
||
```
|
||
|
||
**完成判据**：三条命令均成功——打印 `env OK`、`selftest OK`、脚本的用法帮助。
|
||
|
||
## 其他技能如何使用本环境
|
||
|
||
- 统一在项目根目录用 `uv run python <脚本> [参数]` 执行，uv 自动向上定位 `pyproject.toml` 并复用其环境。
|
||
- 不用裸 `python`（依赖 PATH 碰运气），不手动激活 venv，不 `pip install` 到全局。
|
||
|
||
## 新增依赖
|
||
|
||
改 `pyproject.toml` 的 `dependencies`（唯一入口），再 `uv sync` 更新 `uv.lock`。禁止 `pip install` / `uv pip install` 直装——绕过 lock，环境不可复现。
|
||
|
||
## 排查
|
||
|
||
网络慢/超时、uv 安装失败、`.venv` 损坏重建、多版本 Python 冲突等，查 [references/troubleshooting.md](references/troubleshooting.md)。
|