RBE配置Python远程执行时@local_config_python找不到Python-ast.h报错

配置基于Python的RBE远程执行环境做Bazel构建时，@local_config_python规则抛出报错，提示无法找到Python-ast.h头文件，报错现场如下：

• 环境未安装Python开发依赖包：Python-ast.h不属于Python默认运行时的自带文件，是开发包内的头文件，仅安装Python主程序必然找不到该文件。
• RBE远程节点和本地环境的Python配置不一致：@local_config_python是Bazel启动时在本地探测生成的配置，若远程执行节点的Python版本、安装路径和本地探测结果不匹配，远程执行编译动作时就会找不到对应头文件。
• Bazel Python工具链配置错误，自动探测到了无效的Python安装路径。

• 补全本地Python开发依赖
  Debian/Ubuntu系执行：

  sudo apt install python3-dev
  

  如果构建指定了Python小版本（比如3.10），就安装对应版本的dev包：sudo apt install python3.10-dev
  RHEL/CentOS/Fedora系执行：

  sudo dnf install python3-devel
  

  安装完成后执行find /usr -name "Python-ast.h"校验，能返回类似/usr/include/python3.10/Python-ast.h的路径就说明本地头文件就位。
• 对齐RBE远程镜像的Python环境
  检查RBE用的执行容器镜像，确保镜像内同样安装了和本地版本完全一致的Python开发包，Python的安装路径也要和本地保持一致，避免出现本地是/usr/bin/python3.10、远程镜像只有/usr/bin/python3.8的错位问题。
• 显式指定Bazel的Python配置，避免自动探测偏差
  在项目.bazelrc里追加如下配置，路径替换为自身环境的实际值：

  build --python_path=/usr/bin/python3
  build --action_env=PYTHON_INCLUDE_PATH=/usr/include/python3.10
  

• 清理Bazel旧缓存重新构建
  之前错误探测生成的@local_config_python缓存会导致问题复现，执行以下命令清缓存后重试：

  bazel clean --expunge
  

如果是编译gRPC相关目标，还要注意Python版本要匹配gRPC的版本要求，版本跨度过大不仅会找不到头文件，还可能出现接口不兼容的编译错误。

内容的提问来源于stack exchange，提问作者Damian Akpan