报错急救:常见坑与解法

环境

python: command not found / command not found: python3: 没装 Python,或装了但没加进 PATH。解:去 python.org 装,Windows 安装时务必勾 "Add Python to PATH";Mac 常用 python3 而不是 python。见 F-000。
版本太低(要 3.10+ 却是 3.8): 系统自带的旧 Python。解:装新版;或用 python3.12 这类带版本号的命令指定。

ModuleNotFoundError: No module named 'xxx': 最常见。要么没装这个包,要么装到了另一个 Python/环境里。解:pip install xxx;若用了虚拟环境,先确认已激活(命令行前缀有环境名);多个 Python 时用 python3 -m pip install xxx 保证装到当前解释器。
pip: command not found: 解:用 python3 -m pip ... 代替裸 pip,更可靠。
pip install 卡住 / 超时 / 下载慢: 默认源在境外。解:换国内镜像,如 pip install xxx -i https://pypi.tuna.tsinghua.edu.cn/simple。
装了却版本冲突、互相打架: 不同项目依赖不同版本,混在一起了。解:每个项目用独立虚拟环境:python3 -m venv .venv 再 source .venv/bin/activate(Windows 是 .venv\Scripts\activate)。

UnicodeDecodeError(读中文文件时): 没指定编码,系统默认编码不是 UTF-8。解:读写文件都带上 encoding="utf-8",如 open(path, encoding="utf-8")。
FileNotFoundError: 路径不对,或你以为的"当前目录"和实际不一致。解:先 print(os.getcwd()) 看当前在哪;用绝对路径,或用 pathlib.Path(__file__).parent 定位到脚本所在处。
PermissionError: 没权限,或文件正被别的程序占用。解:换一个你有写权限的目录(别写系统目录);关掉占用该文件的程序。
程序卡住不动、不报错: 多半在等一个永远不会来的东西(网络、输入)。解:给网络请求加 timeout;循环里加步数上限和日志,看它卡在哪一步(这正是 F-023 强调 trace 的原因)。

401 / invalid api key / unauthorized: key 错、过期,或根本没读到(常是环境变量名写错)。解:确认 key 从环境变量读、变量名对;永远别把 key 硬编码进代码(会随提交泄露)。入门其实不用 key,先用 P-006 零依赖版。
429 / rate limit / too many requests: 请求太频繁,触发限流。解:降低频率、加指数退避重试;免费额度限流严,别在循环里疯狂调。
timeout / 连接失败: 网络问题或服务不可达。解:给请求设 timeout 并做重试;确认网络能访问该服务;必要时用本机开源小模型离线跑。

fatal: not a git repository: 你不在一个 git 仓库目录里。解:cd 到项目目录再操作;新项目先 git init。
clone / push 要密码、认证失败: HTTPS 现在不能用账号密码了。解:用 Personal Access Token 当密码,或配 SSH key。私有仓还要确认账号有权限。
不小心把密钥 / 大文件提交了: 提交前没检查。解:先建好 .gitignore 排除 .env 和敏感文件;已提交的密钥要视为泄露、立刻轮换,别只靠删文件(历史还在)。

没找到你的坑?正常——这页持续补充。动手教程见 F-023,不认识的词查术语表。