protoc 安装教程及 GO 代码插件配置步骤

在做 Protobuf 相关开发时，protoc 编译器和对应语言的代码插件是必不可少的工具。

不少新手朋友在初次安装配置时会踩坑，比如命令找不到、插件不兼容等问题。

今天就结合我的工作安装经验，给大家讲清楚如何一步步安装 protoc 以及 GO 语言代码插件，全程干货无废话。

一、什么是 protoc 和代码插件？

先简单科普下，protoc 是 Protobuf 的官方编译器，主要作用是把 .proto 协议文件编译成不同语言的代码，比如 GO、Java、Python 等。

而代码插件则是针对特定语言的扩展工具，比如 GO 语言需要 protoc-gen-go 插件，才能让 protoc 编译出可直接使用的 GO 代码。

简单说，protoc 是基础，插件是语言专属“翻译官”。

二、protoc 编译器安装

protoc 支持 Windows、Mac、Linux 三大主流系统，不同系统安装方式略有差异，大家按需选择对应步骤。

（一）Windows 系统安装

1. 下载安装包：打开 protoc 官方 GitHub Releases 页面，找到最新的稳定版本（建议选带“stable”标识的），下载 Windows 系统对应的压缩包，比如 “protoc-27.2-win64.zip”（64 位系统）。

2. 解压并配置环境变量：把下载的压缩包解压到任意目录，比如 “D:\protoc-27.2”，然后找到解压目录下的 “bin” 文件夹（里面有 protoc.exe）。接下来配置环境变量：右键 “此电脑” → “属性” → “高级系统设置” → “环境变量”，在 “系统变量” 里找到 “Path”，点击 “编辑” → “新建”，把 “D:\protoc-27.2\bin” 路径添加进去，最后点击所有 “确定” 保存。

3. 验证安装：打开新的命令提示符（CMD），输入命令 “protoc –version”，如果能显示类似 “libprotoc 27.2” 的版本信息，说明安装成功。

（二）Mac 系统安装

Mac 系统推荐用 Homebrew 安装，更简单高效，没有安装 Homebrew 的朋友可以先执行一下命令安装。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. 执行安装命令：打开终端（Terminal），输入命令 “brew install protobuf”，等待安装完成即可。

2. 验证安装：在终端输入 “protoc –version”，显示版本信息即安装成功。如果提示 “command not found”，可以重启终端再试。

（三）Linux 系统安装

Linux 系统以 Ubuntu 为例，其他发行版类似，可通过 apt 命令安装。

1. 更新软件源并安装：打开终端，先执行 “sudo apt update” 更新软件源，然后输入 “sudo apt install protobuf-compiler” 安装 protoc。

2. 验证安装：输入 “protoc –version”，显示版本信息即成功。如果想安装特定版本，可以参考 Windows 方式从 GitHub 下载压缩包，解压后配置环境变量。

（四）安装指定版本

github 仓库找到对应版本进行下载：Releases · protocolbuffers/protobuf · GitHub

github 上的 tag，和实际安装后 protoc 的版本不一样，这里要特别注意

比如我这里要下 v3.19.4 ，但是对应的 tag 为 v21.11 对应的链接：

protoc-v3.19.4

三、GO 语言代码插件安装

目前 GO 语言常用的 Protobuf 插件是官方的 protoc-gen-go 和用于 gRPC 的 protoc-gen-go-grpc，这里以安装这两个插件为例，需要确保你的 GO 环境已经配置好（GO 1.18+ 版本推荐，支持 module 模式）。

（一）配置 GO 环境变量

首先要确保 GO 的环境变量配置正确，尤其是 GOPATH 和 GOBIN。打开终端或 CMD，执行以下命令（根据系统调整）：

# Windows 系统（CMD 中）
set GO111MODULE=on
set GOPROXY=https://goproxy.cn,direct  # 国内代理，加速下载

# Mac/Linux 系统（终端中）
export GO111MODULE=on
export GOPROXY=https://goproxy.cn,direct

如果想永久生效，Windows 可以把上述命令添加到环境变量中，Mac/Linux 可以添加到 ~/.bashrc 或 ~/.zshrc 文件里。

（二）安装插件

在终端或 CMD 中执行以下两个命令，分别安装 protoc-gen-go 和 protoc-gen-go-grpc 插件：

# 安装 protoc-gen-go（基础 GO 代码生成插件）
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

# 安装 protoc-gen-go-grpc（gRPC 相关代码生成插件，如需 gRPC 开发必装）
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

（三）验证插件安装

GO 安装的插件默认会放在 GOPATH/bin 目录下（如果没配置 GOPATH，默认在用户目录的 go/bin 下，比如 Mac 是 ~/go/bin，Windows 是 C:\Users\用户名\go\bin）。

可以进入该目录查看是否有 protoc-gen-go.exe（Windows）或 protoc-gen-go（Mac/Linux）文件，也可以直接执行以下命令验证：

# 验证 protoc-gen-go
protoc-gen-go --version
# 验证 protoc-gen-go-grpc
protoc-gen-go-grpc --version

如果能显示版本信息，说明插件安装成功。如果提示 “command not found”，请把 GOPATH/bin 目录添加到系统环境变量中（步骤和 protoc 环境变量配置类似）。

四、实操演示：用 protoc 编译 GO 代码

安装完成后，我们用一个简单的示例演示如何用 protoc 编译 .proto 文件生成 GO 代码。

1. 编写 .proto 文件

新建一个目录，比如 “proto-demo”，在目录下创建 “user.proto” 文件，内容如下（定义一个用户信息的协议）：

syntax = "proto3";  // 指定使用 proto3 语法

package proto;  // 包名，生成的 GO 代码会对应这个包

option go_package = "./pb;pb";  // 生成 GO 代码的路径（./pb）和包名（pb）

// 定义用户信息消息结构
message User {
  string id = 1;      // 用户 ID
  string name = 2;    // 用户名
  int32 age = 3;      // 用户年龄
  string email = 4;   // 用户邮箱
}

// 定义用户服务（如需 gRPC 开发）
service UserService {
  rpc GetUserById(string) returns (User);
}

2.执行编译命令

在 “proto-demo” 目录下打开终端或 CMD，执行以下编译命令：

# 编译生成基础 GO 代码和 gRPC 代码
protoc --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  user.proto

命令说明：

• –go_out=.：指定基础 GO 代码的生成目录为当前目录（. 表示当前目录）。

• –go_opt=paths=source_relative：按相对路径生成代码，对应 .proto 文件中的 go_package 配置。

• –go-grpc_out=. 和 –go-grpc_opt=paths=source_relative：生成 gRPC 相关代码，如需仅生成基础代码，可去掉这两个参数。

3.查看生成的代码

执行命令后，会在当前目录下生成 “pb” 目录，里面有 “user.pb.go”（基础代码）和 “user_grpc.pb.go”（gRPC 代码）两个文件，这就是我们可以直接在 GO 项目中引用的代码了。

常见问题

Q1. 执行 protoc 命令时提示 “protoc: command not found”？

这是环境变量配置问题。首先检查 protoc 的 bin 目录是否正确添加到系统环境变量的 Path 中，然后必须打开新的终端或 CMD 重新执行命令（旧的终端不会加载新的环境变量）。

如果还是不行，重启电脑再试，确保环境变量配置无误。

Q2. 安装插件时提示 “go: module not found” 或下载缓慢？

这是 GO 代理配置问题。

请重新配置 GOPROXY 代理（参考 3.1 节），用国内代理（比如 https://goproxy.cn）可以加速下载。配置完成后，执行 “go clean -modcache” 清理模块缓存，再重新执行安装命令。

Q3. 编译 .proto 文件时提示 “protoc-gen-go: program not found or is not executable”？

这是 protoc 找不到 GO 插件的问题。

原因有两个：

一是插件没安装成功，重新执行插件安装命令；

二是插件所在的 GOPATH/bin 目录没添加到系统环境变量中，添加后打开新终端再试。

Q4. 生成的 GO 代码提示包不存在？

进入生成代码的目录（比如 pb 目录），执行 “go mod init pb” 初始化模块，然后执行 “go mod tidy” 下载依赖包，即可解决包不存在的问题。

总结

protoc 和 GO 代码插件的安装核心就三步：安装 protoc 编译器并配置环境变量、安装对应 GO 插件、验证并实操编译。

不同系统的核心差异在 protoc 安装方式上，Windows 需手动配置环境变量，Mac 和 Linux 用包管理工具更便捷。

重点要注意环境变量的配置，不管是 protoc 还是 GO 插件，环境变量没配好都会导致命令找不到。

另外，插件版本和 protoc 版本尽量匹配，避免兼容性问题。

如果遇到问题，先检查环境变量和版本信息，大部分问题都能解决。

希望这篇教程能帮到正在踩坑的你，有其他问题欢迎在评论区交流~