Sidney Zhang
9020752eed
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
3.6 KiB
3.6 KiB
环境排查
uv 不识别（按序排查）
- 刚装完、当前会话不认识：会话内刷新 PATH——
- PowerShell：
$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User") - Git Bash / zsh：
export PATH="$PATH:$HOME/.local/bin" - cmd：重开终端。
- PowerShell：
- 试试模块入口：
python -m uv --version。可用则后续所有uv <子命令>都换成python -m uv <子命令>。 - 用 pip 兜底安装：
pip install uv后回到第 2 条，立即生效（winget/官方脚本方式要等新终端）。 - 彻底没有 Python/uv：先装 Python 3.10+（或让
uv官方脚本一并装好托管 Python），再走第 3 条。
无 pyproject.toml 的目录跑脚本
- 脚本头部带 PEP 723 声明（
# /// script ... ///），直接uv run <脚本>即可，uv 自动建缓存环境。 - 报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
- 需要重建缓存环境：删除
%LOCALAPPDATA%\uv\cache\environments-v2下对应目录（或整体清uv cache clean）后重试。
网络与镜像（国内环境）
uv sync / uv run 拉包慢或超时时，临时切换清华镜像：
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
uv sync
要持久化则写入 pyproject.toml：
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
sync 相关
No solution found/ 依赖解析冲突：dependencies里的版本约束互相矛盾。放宽或修正pyproject.toml后重试。- lock 与 pyproject 不一致：
uv.lock过期，uv sync会自动更新；若报 lock 损坏，删除uv.lock后重新uv sync。 requires-python不满足：本机 Python 全部低于 3.10。让 uv 自动下载即可：uv sync -p 3.12（或省略，uv 自选）。
已有 .venv 但缺 pyproject.toml
历史环境是手动 pip install 搭的，不是 uv 管理：
- 在项目根新建
pyproject.toml，dependencies写全实际用到的包（参考现有 .venv 里pip list）。 requires-python与现有解释器大版本一致（如">=3.12"），避免 uv 另下新 Python。uv sync让 uv 接管该.venv并生成uv.lock。
.venv 损坏 / 重建
症状：uv run 报奇怪的导入错误、DLL 加载失败，或 .venv 被移动过。
Remove-Item -Recurse -Force .venv
uv sync
playwright 相关
ModuleNotFoundError: playwright：环境未同步。项目根执行uv sync，或直接用uv run python <脚本>；单脚本模式下直接uv run <脚本>（PEP 723 自动装）。详见 SKILL.md 步骤 1 回退链。- 复用系统 Chrome/Edge 无需
playwright install：只有用 uv 环境内置 Chromium 时才需要uv run playwright install chromium。 playwright install下载浏览器慢：$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"后重试。
无 uv 的最终兜底
uv 完全装不上时，用标准库 venv 手动搭（仅应急，失去 lock 可复现性）：
python -m venv .venv
.venv\Scripts\python.exe -m pip install pandas openpyxl playwright requests
# 此后所有命令用 .venv\Scripts\python.exe 替代 uv run python
与全局环境隔离
- 本项目所有命令都经
uv run，不会污染全局 site-packages。 - 若此前
pip install过 playwright/pandas 到全局，与本.venv无冲突，但项目内一律走uv run。