50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
# 环境排查
|
||
|
||
## uv 安装与 PATH
|
||
|
||
- **`uv: command not found` / 无法识别**：装完未重开终端，PATH 未生效；重开终端或手动刷新 `$env:Path`。
|
||
- **winget 安装失败**：改用官方脚本 `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`，或 `pip install uv`。
|
||
|
||
## 网络与镜像（国内环境）
|
||
|
||
`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 损坏 / 重建
|
||
|
||
症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。
|
||
|
||
```powershell
|
||
Remove-Item -Recurse -Force .venv
|
||
uv sync
|
||
```
|
||
|
||
## playwright 相关
|
||
|
||
- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`（隐式同步）。
|
||
- **复用系统 Chrome/Edge 无需 `playwright install`**：只有用 uv 环境内置 Chromium 时才需要 `uv run playwright install chromium`。
|
||
- **`playwright install` 下载浏览器慢**：`$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"` 后重试。
|
||
|
||
## 与全局环境隔离
|
||
|
||
- 本项目所有命令都经 `uv run`，不会污染全局 site-packages。
|
||
- 若此前 `pip install` 过 playwright/pandas 到全局，与本 `.venv` 无冲突，但项目内一律走 `uv run`。
|