本地运行Buf pre-commit钩子提示需系统安装Go但已安装的问题求助

问题背景 #

我使用Buf的pre-commit钩子在Protobuf文件编译为Go代码前做检查，配置如下：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0 # Use the ref you want to point at
    hooks:
      # Git style
      - id: check-added-large-files
        args: ["--maxkb=512"]
      - id: check-merge-conflict
      - id: check-vcs-permalinks
      - id: forbid-new-submodules

      # Common errors
      - id: end-of-file-fixer
      - id: check-yaml
        args: [--allow-multiple-documents]
      - id: check-merge-conflict
      - id: check-executables-have-shebangs

      # Cross platform
      - id: check-case-conflict

  - repo: https://github.com/yoheimuta/protolint
    rev: v0.53.0
    hooks:
      - id: protolint
        files: protos/.

  - repo: https://github.com/python-jsonschema/check-jsonschema
    rev: 0.23.3
    hooks:
      - id: check-github-workflows

  - repo: https://github.com/bufbuild/buf
    rev: v1.50.1
    hooks:
      - id: buf-dep-update
      - id: buf-dep-prune
      - id: buf-breaking
        args: ["--against", ".git/subdir=start/protos"]

本地运行时持续报错：

An unexpected error has occurred: AssertionError: For now, pre-commit requires system-installed golang

移除Buf相关钩子后流程正常，且我已安装Go：

> go version
  go version go1.24.1 linux/amd64
> which go
  /usr/local/go/bin/go

本地执行命令的结果：

> which go && pre-commit run
/usr/local/go/bin/go
[INFO] Installing environment for https://github.com/bufbuild/buf.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
An unexpected error has occurred: AssertionError: For now, pre-commit requires system-installed golang
Check the log at /home/{user}/.cache/pre-commit/pre-commit.log

Go安装在/usr/local/go/bin/go，该配置在GitHub上可正常运行，求解决方法。

解决方案 #

1. 确保Go路径被pre-commit识别 #

pre-commit的隔离环境可能未读取到Go的PATH配置，需将Go的bin目录加入系统全局PATH：

• 编辑shell配置文件（如~/.bashrc或~/.zshrc），添加：

  export PATH=$PATH:/usr/local/go/bin
  export GOPATH=$HOME/go
  export PATH=$PATH:$GOPATH/bin
  

• 执行source ~/.bashrc（对应你的shell配置文件）使变更生效，再重新运行pre-commit run。

2. 给Buf钩子显式指定Go路径 #

在pre-commit配置中为Buf钩子添加env字段，强制指定Go的PATH：

- repo: https://github.com/bufbuild/buf
  rev: v1.50.1
  hooks:
    - id: buf-dep-update
      env:
        PATH: "/usr/local/go/bin:$PATH"
    - id: buf-dep-prune
      env:
        PATH: "/usr/local/go/bin:$PATH"
    - id: buf-breaking
      args: ["--against", ".git/subdir=start/protos"]
      env:
        PATH: "/usr/local/go/bin:$PATH"

3. 改用本地预编译的Buf二进制 #

pre-commit默认会从源码编译Buf，依赖系统Go环境。可直接使用预编译的Buf跳过编译环节：

• 本地安装Buf二进制：

  curl -sSL https://github.com/bufbuild/buf/releases/download/v1.50.1/buf-Linux-x86_64.tar.gz | sudo tar -xvzf - -C /usr/local/bin buf
  

• 修改pre-commit配置为本地钩子：

  # 移除原Buf repo配置，替换为：
  - repo: local
    hooks:
      - id: buf-dep-update
        name: buf dep update
        entry: buf dep update
        language: system
        files: ^protos/.*\.proto$
      - id: buf-dep-prune
        name: buf dep prune
        entry: buf dep prune
        language: system
        files: ^protos/.*\.proto$
      - id: buf-breaking
        name: buf breaking
        entry: buf breaking --against .git/subdir=start/protos
        language: system
        files: ^protos/.*\.proto$
  

4. 临时传递环境变量运行pre-commit #

如果不想修改配置或shell环境，可直接在运行时传递PATH：

PATH=$PATH:/usr/local/go/bin pre-commit run

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