cl.exe未识别即缺编译器，报错“Microsoft Visual C++ 14.0 or greater is required”本质是Windows无cl.exe；验证方式为新开PowerShell运行cl，若提示未识别则确认缺失，输出版本号则已就位。
cl.exe 命令未识别就是缺编译器
报错里出现 Microsoft Visual C++ 14.0 or greater is required 或 error: command 'cl.exe' failed，本质不是网络、权限或 pip 版本问题，而是 Windows 系统里压根没有 cl.exe 这个编译器。验证方式非常直接：新开一个 PowerShell（别用 VS Code 内置终端或旧 CMD），运行：
cl
如果提示 'cl' is not recognized，就确认缺失；如果输出类似 Microsoft (R) C/C++ Optimizing Compiler Version 19.3x，说明已就位。很多失败案例卡在这一步，只是因为没关掉旧终端——环境变量根本没加载。
装 Microsoft C++ Build Tools，不是 VS 完整版
Visual Studio 完整安装包动辄 10GB+，但 Python 编译只用到其中几个组件：cl.exe、link.exe、Windows SDK 头文件和 CMake 支持。必须去官网下载独立的 vs_buildtools.exe（推荐 Visual Studio 2022 Build Tools），安装时勾选：
-
C++ build tools（核心，含cl.exe） -
Windows 10/11 SDK（缺它会报winreg.h not found） -
CMake tools for Visual Studio（torch、onnxruntime等新包依赖）
安装路径避免中文和空格，例如 C:\BuildTools；装完必须关闭所有终端再重开，否则 pip 看不见编译器。
立即学习“C++免费学习笔记（深入）”；
使用位于 ci-tools.xrow.de 的 CI Tools 组件目录构建和维护 GitLab CI/CD 流水线，适用于创建或修复 .gitlab-ci.yml 文件，选择合适的组件。
不想编译？优先走预编译 wheel 路线
本地编译不是唯一路径，尤其在 CI、临时环境或磁盘紧张时，绕过更省事：
- 用
conda install -c conda-forge xxx：比如conda install -c conda-forge pycocotools，直接拉预编译二进制，不碰cl.exe - 手动下
.whl：访问 Gohlke 的 wheel 库，搜包名 → 找匹配你 Python 版本（如cp311）、系统（win_amd64）的文件 →pip install xxx‑1.2.3‑cp311‑cp311‑win_amd64.whl - 换
Miniconda：比 Anaconda 更轻，自带conda和基础构建链，开箱即用装 C 扩展包
注意：conda 虽快，但小众包（如新版 lightgbm 的 nightly 版）可能还没上 conda-forge，这时仍得退回 Build Tools。
位数匹配和 SDK 版本最容易被忽略
32 位 Python 配 64 位 Build Tools 会失败，查 Python 位数用：
python -c "import platform; print(platform.architecture())"
某些包（如 py7zr、pyarrow）即使装了 Build Tools，若没勾全 SDK 或 CMake，依然报头文件找不到——别只看“装了没”，要看“装对没”。另外，pip debug --verbose | findstr "Compatible tags" 可列出当前环境支持的 wheel 标签，帮你判断是否真需要编译。
