market/skills/python-runtime/references/troubleshooting.md

Python 故障排查

"python: command not found" / "python3: command not found"

原因：未安装或未加入 PATH。

# 1. 找一下二进制
which python3 2>/dev/null; which python 2>/dev/null
ls /usr/bin/python* /usr/local/bin/python* /opt/homebrew/bin/python* 2>/dev/null

# 2. 查 PATH
echo "$PATH" | tr ':' '\n' | head -20

# 3. macOS：检查 Homebrew Python
brew list python 2>/dev/null && echo "Homebrew Python installed"

# 4. 修复 PATH
# Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"
# Intel mac / Linux 常见
export PATH="/usr/local/bin:$PATH"

根治：按主 SKILL.md 决策树重新执行 L1–L3 安装路径。

"pip: command not found"

# 用 module 模式调用
python3 -m pip --version

# 仍失败：手动 bootstrap
curl -fsSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
python3 /tmp/get-pip.py --user
rm /tmp/get-pip.py

# 把 ~/.local/bin 加入 PATH（zsh / bash）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

"externally-managed-environment"（PEP 668）

触发系统：Debian 12+、Ubuntu 23.04+、Fedora 38+、Arch（部分）。

优先级从高到低：

# 方案 1（推荐）：虚拟环境
python3 -m venv .venv
source .venv/bin/activate
pip install package-name

# 方案 2：pipx 装 CLI 工具
pipx install package-name

# 方案 3：用户目录
pip install --user package-name

# 方案 4（不推荐，可能破坏系统）
pip install --break-system-packages package-name

SSL / TLS 证书错误

# pip：升级 certifi
pip install --upgrade certifi

# 临时绕过（仅调试）
pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org package-name

# 永久信任（不推荐）
pip config set global.trusted-host "pypi.org files.pythonhosted.org"

macOS 系统时间偏差也会导致 SSL 失败：sudo sntp -sS time.apple.com。

import 失败

包名 ≠ import 名是最常见原因：

安装名 (pip install)	import 名
Pillow	PIL
python-dateutil	dateutil
beautifulsoup4	bs4
scikit-learn	sklearn
PyYAML	yaml
pytorch	torch

# 1. 确认安装到了正确的 Python
python3 -c "import sys; print(sys.executable)"
pip3 show package-name

# 2. 是否在虚拟环境
echo "$VIRTUAL_ENV"

# 3. 强制重装
pip install --force-reinstall --no-cache-dir package-name

macOS "xcrun: error" / 编译失败

安装 lxml / numpy / Pillow 等需要 C 扩展的包时：

# 安装 / 重置 Xcode CLI
xcode-select --install
sudo xcode-select --reset

# 包级依赖
brew install libxml2 libxslt    # lxml
brew install libjpeg zlib       # Pillow
brew install openssl readline   # cryptography 类

Windows PowerShell 执行策略

Get-ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

之后才能 .\.venv\Scripts\Activate.ps1。

Windows Store 占位符

python --version 弹出 Store 页面：

1. 设置 → 应用 → 高级应用设置 → 应用执行别名
2. 关闭 python.exe / python3.exe 的 Store 别名
3. 重启终端

代理环境配置

# pip
pip install --proxy http://proxy:port package-name
pip config set global.proxy http://proxy:port

# 取消
pip config unset global.proxy

# 系统级（zsh / bash）
export http_proxy=http://proxy:port
export https_proxy=http://proxy:port

EnvironmentSnapshot 信号速查

probe-python.sh 输出后，按字段快速判断：

字段	期望	失败原因
system_python.version	非空且 ≥ 3.8	未装 Python 或版本太低
system_pip.version	非空	pip 未装（macOS Apple 自带 Python 没有 pip）
hatch_path	非空	DesireCore Hatch 未释放，调 POST /api/runtime/hatch/install
pep668: true	—	系统 Python 受保护，必须 venv/pipx
active_venv	操作前为空，激活后非空	venv 未生效，重新 source .venv/bin/activate

重置整个 Python 环境（最后手段）

# 1. 退出所有虚拟环境
deactivate 2>/dev/null
conda deactivate 2>/dev/null

# 2. 删除可疑虚拟环境
rm -rf .venv venv

# 3. 重新探测
bash skills/python-runtime/scripts/probe-python.sh

# 4. 按主 SKILL.md 决策树重新安装