迁移PHP项目至Buf CLI：protoc_builtin PHP与原生protoc行为不符求助

开发者阿泽

2026-6-16

迁移PHP项目至Buf CLI时对齐原生protoc输出的解决方案

核心问题分析

你遇到的两个关键差异：

GPBMetadata目录位置：原生protoc会在输出根目录创建Metadata目录并保留原结构，Buf默认将其放在对应模块目录下；
蛇形命名转换：Buf生成的命名规则和原生protoc不一致。

针对性解决方案

1. 对齐GPBMetadata目录位置

原生PHP插件支持metadata_out参数指定Metadata文件的输出路径，你需要在buf.gen.yaml中通过opt传递该参数，同时保持主文件输出路径和原protoc的--php_out一致：

version: v1
plugins:
  - name: php
    out: ./src  # 替换为你原生protoc使用的输出路径
    opt: metadata_out=./src/Metadata

配置后，GPBMetadata文件会生成在输出根目录的Metadata文件夹下，和原生protoc的行为完全匹配。

2. 修复蛇形命名转换差异

这个差异通常是因为Buf内置的protoc_builtin: php插件版本，和你之前使用的protoc版本不匹配导致的——Buf每个版本会绑定特定版本的protoc，不同版本的PHP插件命名转换逻辑可能有调整。解决方式有两种：

降级Buf版本：确认你之前使用的protoc版本，对照Buf的Release Notes找到绑定对应protoc版本的Buf版本，降级后即可对齐命名逻辑；
使用外部PHP插件：放弃Buf内置插件，直接指定你原来使用的protoc-gen-php可执行文件路径，完全复用旧版本的插件逻辑：

version: v1
plugins:
  - name: php
    path: /path/to/your/protoc-gen-php  # 替换为你本地的protoc-gen-php路径
    out: ./src
    opt: metadata_out=./src/Metadata