Go 编译诊断怎样用 -json 交给编辑器解析

如果你希望编辑器或 CI 稳定识别 Go 构建错误，可以把 go build -json 当成一条换行分隔的 JSON 事件流来消费。每条事件只有 ImportPath、Action、Output 三个核心字段：先按事件读取，再按包路径归组，最后从输出文本中提取文件位置和消息。不要把每一条 build-output 都标成错误，真正表示构建失败的是 build-fail。

官方资料：https://go.dev/cmd/go/

最稳妥的接入方式是“构建器负责产生事件，解析器负责归组和定位，编辑器适配器负责转换诊断对象”。JSON 事件提供结构化边界，但不会替你完成所有文件、行列号和编辑器协议的语义映射。

先看懂 -json 输出到底表达什么

官方定义的 JSON 流是逐行输出的 BuildEvent 序列。ImportPath 是当前构建包的包标识；它与 go list -json 的 Package.ImportPath 对齐，但不要把它直接当成本地目录。Action 当前主要区分 build-output 与 build-fail，Output 则承载工具链输出片段。

这里有两个容易误判的边界。第一，单个包可能出现多条输出事件，不能只保留最后一条；把同一 ImportPath 下的 Output 按原顺序拼接，才得到该包完整的构建输出。第二，build-output 可能包含普通信息，也可能包含编译器诊断文本，事件类型本身不能替代消息级分类。

按 JSONL 事件边界读取，而不是切字符串

编辑器桥接器的第一层只做一件事：逐行解码 JSON，并保留读取错误、包路径和事件类型。不要用逗号或固定关键词切割整段 stdout，因为输出片段可能包含多行文本，且一个包有多个事件。

type BuildEvent struct {
    ImportPath string `json:"ImportPath"`
    Action     string `json:"Action"`
    Output     string `json:"Output"`
}

func readBuildEvents(r io.Reader) ([]BuildEvent, error) {
    // Scanner 按换行读取，保持每条 JSON 事件的边界。
    scanner := bufio.NewScanner(r)
    // 编译器消息可能较长，适当放大单行上限，避免截断诊断。
    scanner.Buffer(make([]byte, 8*1024), 1024*1024)

    var events []BuildEvent
    for scanner.Scan() {
        // 空行没有事件语义，直接跳过以兼容包装脚本的多余换行。
        line := bytes.TrimSpace(scanner.Bytes())
        if len(line) == 0 {
            continue
        }
        var event BuildEvent
        if err := json.Unmarshal(line, &event); err != nil {
            return nil, fmt.Errorf("decode build event: %w", err)
        }
        events = append(events, event)
    }
    if err := scanner.Err(); err != nil {
        return nil, fmt.Errorf("read build stream: %w", err)
    }
    return events, nil
}

这段代码只负责读取，不负责判断成功。实际接入时还要同时保存进程退出码：解析成功不代表构建成功，构建命令返回非零时仍应把本次任务标为失败；反过来，某些包装器可能在失败前已经输出了最后几条有效事件，也不能因为 JSON 可解析就忽略退出码。

把 Output 变成编辑器能定位的诊断

第二层按 ImportPath 建立包级索引，再从拼接后的文本中寻找编译器常见的“文件:行:列:消息”形态。能提取到位置时生成文件诊断；只能确认包失败时，生成包级诊断并保留原始文本。这样不会为了追求行号而丢掉模块加载错误或依赖包错误。

type Diagnostic struct {
    File    string
    Line    int
    Column  int
    Message string
    Level   string
}

func classifyEvent(event BuildEvent, output string) []Diagnostic {
    // build-fail 决定失败级别；普通输出仍需继续解析其中的编译器消息。
    level := "info"
    if event.Action == "build-fail" {
        level = "error"
    }
    // 位置提取器只负责识别格式，无法识别时保留包级文本。
    diagnostics := parseLocations(output, level)
    if len(diagnostics) == 0 && level == "error" {
        diagnostics = append(diagnostics, Diagnostic{Message: output, Level: level})
    }
    return diagnostics
}

parseLocations 不应假设所有失败都来自当前包：导入依赖、构建标签、生成文件和外部工具都可能改变消息格式。对不能定位的文本，编辑器可以把 File 留空，展示包路径和原始消息；这比伪造一个文件位置更可靠。

三种接入方案怎样选

如果只是 CI 采集，直接保存原始 JSONL 和退出码最稳，后处理系统再解析；如果要给编辑器即时提示，使用“按包归组 + 文本定位 + 诊断适配器”的桥接层；如果已经有语言服务，则让语言服务消费统一的 Diagnostic，不要让每个编辑器重复解析 Go 输出。

兼容性、失败边界与落地清单

接入前确认运行环境的 Go 版本支持该 JSON 编码，并把命令版本、工作目录、构建标签和环境变量作为诊断上下文记录。解析器要覆盖：截断的最后一行、超长输出、未知 Action、相同包的多段输出、依赖包错误和无法映射到本地文件的消息。未知事件不要静默丢弃，至少保留原始行。

• 保存每个 ImportPath 的原始事件顺序，不只存最后一条。
• 把退出码作为最终成败依据，把 Action 作为消息分类线索。
• 无法得到文件位置时生成包级诊断，保留原文。
• 用一个解析入口服务 CI、编辑器和语言服务，减少规则漂移。

常见问题

-json 会直接给出编辑器需要的完整行列信息吗？

不会。它提供事件、包路径和输出片段，文件、行列号与严重级别仍需由接入层结合输出文本和编辑器模型完成。

只要出现 build-fail 就可以停止读取吗？

不建议。应继续消费并保存剩余事件，等待进程退出；否则可能丢失其他包的诊断和完整原始输出。