遇到 SocialCoach 安装报缺依赖，不建议立刻换源。通常先按“解释器与虚拟环境 → 系统库 → 安装来源/安装方式”的顺序排除：如果日志已经出现 Python.h 缺失或 gcc 失败，换 pip 源解决不了；如果解释器路径不是当前虚拟环境，补系统库也没有意义。适用场景是命令行安装到一半报错、日志很长；操作动作是下面五步；验证方式是最小导入命令是否正常退出；风险边界是换源或换安装方式不能替代环境核对，系统库缺失必须用系统包管理器处理。
SocialCoach 安装报缺依赖时，判断顺序建议是：先定位日志里第一条真实错误，再核对解释器路径、版本和虚拟环境，最后区分纯脚本依赖与需要系统库的依赖。若错误指向缺头文件或编译工具，应先补系统组件；若错误指向找不到包或网络超时，再换安装来源。换源或换安装方式不能替代环境核对，验证以最小导入命令是否通过为准。
从完整日志里定位第一条真正的错误
日志很长时，不要从第一行逐行读，那会把时间花在依赖解析和下载信息上。先把安装输出存下来，并让 pip 输出更完整的构建信息：
python -m pip install -v <包名> 2>&1 | tee install.log然后在日志里搜错误关键词，别直接翻屏幕：
grep -n -i -E "error|fatal|failed|no module|could not" install.log找到候选行后，不要停在 pip 最后的汇总行。第一条真正的错误通常是第一次出现的 fatal error、Python.h、gcc failed、CERTIFICATE_VERIFY_FAILED 或 No matching distribution。把那一行和它上方 10-20 行一起复制出来，同时记录安装的包名、包版本和当前解释器路径。上方上下文是判断方向的关键：如果是编译命令，说明卡在构建扩展；如果是下载 URL 或 SSL 字样，说明卡在源或证书；如果只有 No module named，通常说明装到了另一个环境。
确认解释器版本与虚拟环境是否和依赖声明一致
安装报缺依赖时，最常见原因是安装用的解释器和运行用的解释器不是同一个。先执行三条命令：
python `--version`
python -c "import sys; print(sys.executable)"
python -m pip list判断标准分开看：第一，python `--version` 的输出要与项目声明的 Python 版本要求一致，可以去 pyproject.toml 的 requires-python 或 setup.py 的 python_requires 里核对，这里不预设某个版本一定兼容。第二，sys.executable 应该指向当前虚拟环境里的解释器，例如项目下的 .venv、venv 或 conda 环境路径，而不是系统全局路径；如果路径不对，后面所有安装命令都需要改成带虚拟环境路径的解释器来执行。第三，python -m pip list 要能看到依赖包，或者至少能确认缺失的是哪个包；如果裸 pip list 和 python -m pip list 结果不同，后续统一用 python -m pip，不要混用。
区分纯脚本依赖与需要系统库的依赖
这一步决定你是继续补 Python 包，还是先补系统组件。对照日志里的关键词：
| 报错关键词 | 指向 | 检查动作 |
|---|---|---|
| command 'gcc' failed / gcc: not found / cl.exe not found / Microsoft Visual C++ 14.0 or greater is required | 编译工具缺失 | Linux 查 gcc、build-essential；macOS 查 xcode-select；Windows 查 Build Tools。确认命令是否存在，再决定是否安装 |
| fatal error: Python.h: No such file or directory | Python 开发头文件缺失 | 查 python3-dev、python3-devel 或 python-dev 是否已装，并确认它与当前解释器版本同系列 |
| fatal error: openssl/ssl.h / libffi.h / libxml2 / zlib.h | 系统开发库缺失 | 用系统包管理器查 libssl-dev、libffi-dev、libxml2-dev、zlib1g-dev 等包是否已安装 |
| CERTIFICATE_VERIFY_FAILED / SSLError / certificate verify failed | 证书或 TLS 校验问题 | 检查系统时间、CA 证书、pip 的 index-url 与 trusted-host 配置，再重试安装 |
| Could not find a version that satisfies / No matching distribution | 源或平台/版本不匹配 | 先确认包名拼写，再换源或换安装方式；不要先补系统库 |
| No module named 'xxx' 但 pip list 能查到 xxx | 解释器或虚拟环境不一致 | 回到上一步检查 sys.executable 与 pip 所属环境 |
出现编译工具和系统头文件关键词时，换 pip 源通常无效；出现证书字样时，先处理证书和源配置；只有纯脚本依赖缺失，才更适合直接补 Python 包。适用场景是你能从日志里找到上述任一类关键词；风险边界是不要因为一个 No module named 就断定缺包，可能是环境用错。
换安装来源或换安装方式后重试并验证
只有解释器、虚拟环境和系统库都排除后，再换安装来源或安装方式。换源的通用骨架如下，镜像地址和主机按你的环境替换：
python -m pip install `--index-url` <镜像地址> `--trusted-host` <镜像主机> `--no-cache-dir` <包名>如果项目在当前目录，也可以换成本地安装或可编辑安装：
python -m pip install `--no-cache-dir` .
python -m pip install `--no-cache-dir` -e .换方式包括改用项目声明的安装工具，例如 poetry install 或 conda install，但执行位置仍然要在已激活的虚拟环境里。安装完成后不要只看 Successfully installed，要做一次最小导入验证：
python -c "import socialcoach; print(socialcoach.__file__)"如果实际模块名不同，替换 import 后的名称；如果 SocialCoach 是命令行程序，可以再用 python -m socialcoach `--help` 或 socialcoach `--version` 验证。成功判据是命令正常退出，并打印出模块路径或帮助信息。若仍然报 ModuleNotFoundError，先回头核对 sys.executable，说明包装到了另一个环境，而不是继续换源。
把这次的解决步骤写成可复用的环境记录
换机器或重装时，直接按记录执行，不重复翻日志。模板如下，把尖括号内容替换成实际输出：
项目：SocialCoach
操作系统：
Python 版本：python `--version` 输出
解释器路径：python -c "import sys; print(sys.executable)" 输出
虚拟环境：.venv / venv / conda 环境名
安装命令：
第一次报错原文（首条真实错误及上方 10-20 行）：
使用的安装来源：
补装的系统包及版本：
最终成功的安装命令：
最小导入验证命令及输出：
判断结果：解释器问题 / 系统库问题 / 安装来源问题
下次换机器执行顺序：
1. 创建并激活虚拟环境
2. 核对 python `--version` 与 sys.executable
3. 安装项目依赖
4. 运行最小导入验证记录时保留报错原文，不要只写“缺依赖”。原文能帮你下次区分是 Python.h、gcc 还是证书问题。验证结果要写命令和实际输出，而不是写“成功”。这份记录可以放在项目根目录或团队文档中，换机器时直接照抄命令，并先核对版本与解释器路径。