需安装 grpcio 而非 grpc，import grpc 正确但 pip install grpc 错误；client 连接失败多因地址不匹配或启动时序问题；proto 修改后必须重生成 stub；大消息需调大 max_message_length 并避免内存全加载。
gRPC Python服务端启动就报 AttributeError: module 'grpc' has no attribute 'server'
这是新手最常遇到的导入错误，本质是把 grpc 和 grpcio 搞混了。Python里没有叫 grpc 的官方包，真正要装的是 grpcio，而 import 时写的是 import grpc —— 这个 grpc 是 grpcio 安装后暴露的顶层模块名，不是你自己 pip install 的包名。
- 必须执行
pip install grpcio grpcio-tools，只装grpc（不存在）或漏掉grpcio-tools都会失败 -
import grpc没问题，但别去pip install grpc—— 那是个空包，会覆盖真实模块 - 生成 stub 时用
python -m grpc_tools.protoc，不是protoc命令直调（除非你手动配置了插件路径）
Python gRPC client连不上server，报 StatusCode.UNAVAILABLE 且带 failed to connect to all addresses
这基本不是代码逻辑问题，而是网络或启动顺序踩坑。gRPC默认用 HTTP/2 明文（h2c），不走 TLS，但对 host 和 port 非常敏感。
- server 启动时绑定的是
[::]:50051，client 却连localhost:50051—— 在某些系统（尤其是 Docker 或 IPv6 优先环境）下会失败；统一用127.0.0.1:50051更稳 - server 还没完全 listen 就跑 client（比如用 pytest 启 server 后立刻发请求），加个简单等待：
time.sleep(0.1)或用grpc.channel_ready_future(channel).result(timeout=3) - 如果 server 跑在容器里，host 配置写成
0.0.0.0:50051，client 则必须用宿主机能路由到的地址（如host.docker.internal:50051或实际 IP）
proto文件改了，Python client/server运行时报 Method not found 或字段全为 None
gRPC 不做运行时 schema 校验，一切依赖 .py stub 文件是否与当前 proto 严格匹配。生成的代码没更新，通信就会静默错乱。
- 每次改
service.proto后，必须重新运行python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. service.proto - 生成的
service_pb2.py和service_pb2_grpc.py要和运行时代码在同一个 Python path 下；不要手工修改它们，也不要把旧版留在__pycache__里干扰导入 - 注意
package和python_package选项：如果 proto 里写package api.v1;，但生成时没加--python_out=.对应目录结构，import 路径就会断
微服务间传大文件或流式数据，用 gRPC Python 总卡死或内存暴涨
gRPC 默认单条 message 限制 4MB，且 Python 的 grpcio 实现对长连接流控不激进，容易在高吞吐下堆积缓冲区。
- server/client 初始化 channel 或 server 时，显式加大
max_message_length：options=[('grpc.max_receive_message_length', -1), ('grpc.max_send_message_length', -1)]（-1 表示不限，生产环境建议设具体值如100 * 1024 * 1024） - 流式接口（
stream关键字）务必在 client 端及时遍历 response iterator，别用list()全读进内存；server 端也避免在yield前攒一堆对象 - Python GIL 会让 CPU 密集型处理阻塞整个 stream，真要处理大 payload，考虑用
concurrent.futures.ThreadPoolExecutor卸载到线程
proto 定义和 Python 运行时的二进制 wire format 必须严丝合缝，差一个字段 tag 或 default 值，都可能让字段消失而不报错。调试时先用 grpcurl 直连验证服务是否正常返回原始数据，再查 Python 层解析逻辑。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
