根本原因是装错了包名，必须安装pip install grpcio（而非grpc），且需确保grpcio版本与python版本严格匹配（如1.60.x仅支持3.8~3.12）、编译环境完备、使用虚拟环境隔离依赖。
pip install grpcio 但 import grpc 报 ModuleNotFoundError
根本原因是装错了包名。gRPC 的 PyPI 官方包是 grpcio，不是 grpc；安装 pip install grpc 会装一个空壳伪包或失败包，解释器自然找不到 grpc 模块。
- 必须执行
pip install grpcio（注意是grpcio，不是grpc） -
grpcio版本与 Python 版本强绑定：比如grpcio==1.60.x只支持 Python 3.8～3.12；用 Python 3.7 装这个版本，安装看似成功，但核心 C 扩展没编译进去，import grpc仍会失败 - Linux/macOS 下缺少
gcc、python3-dev（或python3-devel）会导致编译失败，建议先装好再装grpcio
启动时报 AbstractMethodError: io.grpc.internal.AbstractServerImplBuilder.delegate()
这是 Java gRPC 生态的典型二进制不兼容问题，常见于 Spring Boot + gRPC 混合项目中——Python 侧虽不直接抛这个错，但如果你用 Jython、Py4J 或调用 JVM 服务，也可能间接暴露。
- 错误本质：starter（如
grpc-server-spring-boot-starter）依赖 gRPC Java 1.40+，而 classpath 中实际加载的是旧版grpc-core（如 1.29.x），delegate()方法在旧版里不存在 - 检查方式：运行
mvn dependency:tree | grep grpc，看是否有多个grpc-netty、grpc-protobuf版本共存 - 修复优先级：用官方 BOM 统一管理，例如在
pom.xml的<dependencymanagement></dependencymanagement>中声明io.grpc:grpc-bom对应版本，而非单独指定各 grpc 组件
Linux 下报 GLIBCXX_3.4.29 not found
这不是 Python 代码写错了，而是 grpcio 预编译的 wheel 包用了高版本 GCC 编译，系统自带的 libstdc++.so.6 太旧，缺对应符号。
- 绝对不要手动替换系统
/usr/lib64/libstdc++.so.6——可能让apt、systemd等崩溃 - 首选方案：换用匹配的
grpcio版本，比如老系统（CentOS 7 / Ubuntu 16.04）用grpcio==1.39.0（对应 GCC 5.3 编译） - 次选方案：升级系统 libstdc++（仅限非生产环境），例如 Ubuntu 16.04 可
sudo apt install libstdc++6升级到较新包，但需验证基础命令是否正常
多个项目共用全局 pip 导致 grpcio 版本打架
一个项目需要 grpcio==1.47.2（适配旧版 Nacos Python SDK），另一个要 grpcio==1.60.1（适配新 proto 插件），全局安装必然冲突。
- 虚拟环境不是可选项，是必选项：
python -m venv myproj-venv→source myproj-venv/bin/activate（macOS/Linux）或myproj-venv\Scripts\activate（Windows） - 避免用
pip list看全局包来判断环境是否干净——要确认which python和which pip指向的是 venv 内路径 - 若用
pip-tools，写requirements.in时明确写grpcio==1.47.2，再pip-compile生成带 hash 的requirements.txt，杜绝“本地能跑、CI 失败”
grpcio 根本不在当前解释器的 sys.path 里。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
