Go mod 依赖怎么管理？从初始化到离线构建逐步排错

Go mod 依赖管理先看当前模块，再整理依赖，最后按构建需求决定是否生成 vendor。初始化用 go mod init，整理用 go mod tidy，复制依赖源码用 go mod vendor；三个命令不是遇到报错就轮流试一遍的修复按钮。先确认错误属于哪一层，才能避免改乱依赖文件。

本文建立一个带第三方包的小程序，对照 go.mod、go.sum 和 vendor 各自的职责，再验证普通构建与禁止模块代理下载时的构建。示例面向支持模块的现代 Go 工具链，依赖固定到具体版本。首次取得依赖需要网络，本地已有完整缓存时才可能不下载。

一、先确认当前目录属于哪个模块

模块像项目的一个依赖管理边界。go.mod 的 module 行声明模块路径，require 记录依赖要求，go 指令声明工具链相关的最低版本要求。它不是只要存在就万事大吉的配置文件，路径和版本必须与项目实际情况一致。

在新建的练习目录执行 go version，再执行 go env GOMOD。初始化前你可能看到系统空设备路径等“没有主模块”的结果；初始化后应指向当前目录下的 go.mod。不同平台显示形式不同，重点是它有没有指向你准备修改的项目。

语言基础可参照 Go 教程。本文的模块路径 example.com/w3cschool/moddemo 用于本地练习，不代表那里存在一个可供下载的真实远程仓库。

先执行 go mod init example.com/w3cschool/moddemo。一个目录只需初始化一次。如果目录已经有 go.mod，应查看现有内容，而不是删除后重新初始化，以免丢掉已有依赖约束。

二、写入导入关系，再固定依赖版本

新建 main.go。程序把一段 UTF-8 文本编码成 GBK 再还原，用来建立对 golang.org/x/text 的真实导入关系。

package main

import (
    "fmt"
    "golang.org/x/text/encoding/simplifiedchinese"
)

func main() {
    original := "编程狮"
    encoded, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte(original))
    if err != nil { panic(err) }
    decoded, err := simplifiedchinese.GBK.NewDecoder().Bytes(encoded)
    if err != nil { panic(err) }
    if string(decoded) != original { panic("往返转换结果不一致") }
    fmt.Println(string(decoded))
}

然后依次运行以下命令。这里固定到 v0.14.0，是为了让教学输入稳定，并非把这个版本推荐为所有新项目的默认版本。

go get golang.org/x/text@v0.14.0
go mod tidy
go run .

输出应为“编程狮”。先保存含 import 的源码，再 tidy，顺序很重要。如果还没有任何代码导入第三方包，tidy 可能把刚添加但没有被使用的依赖移除，这不是工具莫名其妙删配置。

go get 在这里用于引入固定版本要求；tidy 根据包和测试导入整理依赖。查看 go.mod 和 go.sum 的差异，比只看命令有没有退出更有价值。已有项目中版本选择还受整个模块图约束，并不只是把某一行字符串照搬到最终构建。

三、分清 go.mod、go.sum 与 vendor

go.sum 保存校验和相关记录，用于核对取得的模块内容。它不是传统意义上完整列出最终构建全部版本的锁文件。某条依赖是否参与当前构建，不能只靠在 go.sum 搜到名字判断。

vendor 则是复制进项目的依赖源码目录。它主要服务于希望随仓库携带依赖源码的构建方式，会增加仓库体积，并带来依赖更新后的重新生成成本。仅创建一个空 vendor 文件夹没有意义，要由命令根据项目依赖生成。

go mod vendor
go run -mod=vendor .

第二条命令明确使用 vendor，输出仍应是“编程狮”。为了减少自动模式与工具链版本差异对初学者的影响，示例直接写出 -mod=vendor，不要求你先记住所有默认选择规则。

进一步理解运行时和底层机制可阅读 深入解析Go语言，但不要把运行时机制和模块依赖管理混为一谈。当前排错首先围绕导入、模块版本和构建输入展开。

四、验证受限网络构建，再按错误分类处理

要验证 vendor 是否足够，不能只在联网且缓存完整的机器上看到一次成功。完成依赖下载与 vendor 生成后，可以在当前终端暂时关闭模块代理下载，再使用已有本地工具链运行。

PowerShell 使用下面的命令，先保存旧环境变量，结束后恢复，避免影响之后的项目。

$previousProxy = $env:GOPROXY
try {
    $env:GOPROXY = 'off'
    go run -mod=vendor .
} finally {
    $env:GOPROXY = $previousProxy
}

Bash、Zsh 可以只对本次命令设置变量：GOPROXY=off go run -mod=vendor .。这验证的是无需模块代理下载的构建路径，不等同于证明机器完全断网；工具链下载与其他程序网络动作是另外的事情。

如果报 inconsistent vendoring，先比较 go.mod 和 vendor/modules.txt，通常应在确认依赖变更正确后重新生成 vendor。不要手工删报错行来让提示消失；清单和源码不一致可能在别的机器重新失败。

若报模块无法下载，检查模块路径、固定版本是否存在以及网络与私有仓库权限。若提示需要更高 Go 版本，先核对项目和依赖要求；这类错误不是反复 tidy 能解决的。工作区还可能受 go.work 影响，需要同时观察 go env GOWORK，避免在错误边界里修改配置。

总结

Go mod 排错可以按三个问题推进：当前主模块是谁，源码实际需要哪些依赖，构建从哪里取得依赖源码。init、tidy、vendor 分别回答其中一部分，不是互相替代的清理命令。

先用小程序取得普通运行和 vendor 运行一致的输出，再尝试升级固定依赖版本，观察两个依赖文件和 vendor 的变化。每次升级都重新构建验证，才能知道仓库中的依赖声明、复制源码与运行结果仍然一致。

延伸学习

1. Go 语言入门课程 可用于继续学习包、错误处理和程序组织。
2. GoProxy 依赖管理说明 可作为网络下载问题的延伸阅读。
3. Go 代码组织实践 可补充代码可读性方面的练习；它不替代官方模块文档。

常见问题

Q：只有标准库的项目为什么没有 go.sum？

因为可能没有需要记录校验和的外部模块内容。不能把“没有 go.sum”直接当成初始化失败，应结合真实导入关系判断。

Q：已经有 vendor，还需要提交 go.mod 吗？

需要。vendor 不是模块声明的替代品，构建仍需了解项目身份与依赖要求。两者应保持一致，并随依赖升级一起审查。

Q：清空全局模块缓存能解决所有错误吗？

不能。路径、版本约束、权限和工具链不匹配都不会因为清缓存自动修复。先看错误类别，避免影响其他项目并增加下载成本。

技术依据：Go 模块官方参考。