使用Buf的Go项目中Proto服务文件导入失败问题排查

云原生阿岚

2026-8-4

问题描述

项目结构

vgm:
 -music:
   -app:
      -cmd
      -go.mod
   -migrations
   -proto:
      -buf.yaml
      -music_service:
         -album:
            -v1:
               -album.proto
               -service.proto
.env

album.proto 内容

syntax = "proto3";

package music_service.album.v1;

option go_package = "github.com/mygitname/vgm/music/app/gen/go/music/album/v1;pb_music_album";

message Album {
    string album_id = 1;
    string title = 2;
    uint32 create_at = 3;
}

service.proto 内容

syntax = "proto3";

package music_service.album.v1;

option go_package = "github.com/mygitname/vgm/music/app/gen/go/music/album/v1;pb_music_album";

import "music_service/album/v1/album.proto";

service AlbumService {
    rpc CreateAlbum(CreateAlbumRequest) returns (CreateAlbumResponse) {}
}
  
message CreateAlbumRequest {
    string title = 1;
}

message CreateAlbumResponse{
    Album album = 1;
}

报错信息

运行 buf lint 时触发错误：

proto\music_service\album\v1\service.proto:7:8:music_service/album/v1/album.proto: does not exist

用户疑问：这是第二次做gRPC开发，上次一切正常，搞不懂哪里错了。会不会是proto目录下没放go.mod导致的？看了一些示例，好像这个不是必须的，到底问题出在哪？

解决方案

这个问题和proto目录有没有go.mod完全没关系，核心原因是buf的工作目录没选对：

buf是基于buf.yaml所在的目录作为根目录来解析proto导入路径的。你的buf.yaml在music/proto目录下，所以必须切换到这个目录下执行buf lint命令。此时buf会从proto目录开始查找music_service/album/v1/album.proto，正好能找到对应文件。如果在项目根目录（vgm）执行命令，buf会从vgm目录开始找这个路径，自然找不到。
如果不方便切换目录，也可以在项目根目录用--path参数指定proto目录的位置：
```
buf lint --path ./music/proto
```
另外确认下buf.yaml的配置，只要是标准的基础配置（比如包含version: v1）就没问题，不需要额外设置。