Sidney Zhang
9020752eed
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
# 环境排查
|
||
|
||
## uv 不识别（按序排查）
|
||
|
||
1. **刚装完、当前会话不认识**：会话内刷新 PATH——
|
||
- PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
|
||
- Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
|
||
- cmd：重开终端。
|
||
2. **试试模块入口**：`python -m uv --version`。可用则后续所有 `uv <子命令>` 都换成 `python -m uv <子命令>`。
|
||
3. **用 pip 兜底安装**：`pip install uv` 后回到第 2 条，立即生效（winget/官方脚本方式要等新终端）。
|
||
4. **彻底没有 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` 拉包慢或超时时，临时切换清华镜像：
|
||
|
||
```powershell
|
||
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
|
||
uv sync
|
||
```
|
||
|
||
要持久化则写入 `pyproject.toml`：
|
||
|
||
```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 管理：
|
||
|
||
1. 在项目根新建 `pyproject.toml`，`dependencies` 写全实际用到的包（参考现有 .venv 里 `pip list`）。
|
||
2. `requires-python` 与现有解释器大版本一致（如 `">=3.12"`），避免 uv 另下新 Python。
|
||
3. `uv sync` 让 uv 接管该 `.venv` 并生成 `uv.lock`。
|
||
|
||
## .venv 损坏 / 重建
|
||
|
||
症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。
|
||
|
||
```powershell
|
||
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 可复现性）：
|
||
|
||
```powershell
|
||
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`。
|