Go从1.11版本引入模块机制以来，依赖管理方式发生了根本性变化。开发者不再需要把代码放在GOPATH指定的目录下，也不再依赖各种第三方的vendor工具。但模块机制依赖网络下载，一旦遇到无外网的构建环境，很多人就会手足无措。本文将系统讲解go get的工作原理，并给出几套经过验证的离线依赖方案。
一、go get 的底层机制是怎么运作的
要理解离线方案，先得弄清楚go get到底做了什么。当执行go get github.com/gin-gonic/gin时，Go命令并不是简单地拉取代码，而是经历了一个完整的解析流程。
首先它会读取当前模块的go.mod文件，分析现有的依赖图，确定需要补齐哪些模块版本。接着通过模块代理（由GOPROXY环境变量控制，默认值是proxy.golang.org）去查询目标模块的版本列表。代理返回的是结构化的元数据，包括可用版本号、时间戳等信息。拿到版本列表后，Go会根据MVS（Minimal Version Selection，最小版本选择）算法计算出一个统一的依赖版本集合，而不是像npm那样安装每个依赖各自声明的最新版本。最后下载的模块会被解压并写入本地缓存目录，这个目录由GOMODCACHE变量指定，默认位置在GOPATH下的pkg/mod文件夹。
下载完成后还有一步校验。Go会根据go.sum文件中记录的哈希值验证模块内容是否被篡改，验证通过才允许参与编译。这套机制保证了依赖的可复现性和安全性，但也意味着离线环境下必须同时解决下载源和校验数据两个问题。
二、无网络环境下的离线部署方案
方案一：利用vendor目录打包依赖
vendor是Go官方支持的方式，执行go mod vendor后，所有依赖的源码会被复制到项目根目录的vendor文件夹中。此时只要把这个文件夹连同项目一起拷贝到内网机器，编译时加上-mod=vendor参数（Go 1.14之后在存在vendor目录时会自动启用），构建过程就完全不需要访问网络。
# 在有网的机器上执行，生成vendor目录 go mod tidy go mod vendor # 将整个项目（含vendor）拷贝到内网机器后 go build -mod=vendor ./...
这个方案的优点是简单直接，vendor目录可以纳入Git版本管理，团队成员克隆代码后无需任何额外配置即可构建。缺点是仓库体积会明显膨胀，尤其是依赖较多的大型项目，vendor目录可能达到几百MB。另外要注意vendor只会包含当前构建目标实际用到的包，如果测试需要用到某些仅在测试中import的依赖，记得先执行完整的测试编译再生成vendor。
方案二：迁移模块缓存目录
如果内网机器上需要构建多个项目，逐个打vendor就不划算，直接迁移GOMODCACHE更高效。模块缓存目录的位置可以这样查看：
# 查看模块缓存路径 go env GOMODCACHE # 通常输出类似 /home/user/go/pkg/mod # 在有网机器上先把所有依赖拉齐 go mod download all # 打包缓存目录（注意保留文件权限） tar -czvf modcache.tar.gz -C $(go env GOPATH)/pkg mod # 传输到内网机器后解压到相同路径结构 tar -xzvf modcache.tar.gz -C /home/user/go/pkg
这里有个容易踩的坑：模块缓存中的文件权限是只读的，用tar打包时务必加上-p参数保留权限，解压后如果权限丢失，Go可能报缓存校验失败的错误。解压完成后，在内网机器上设置GOFLAGS=-mod=mod并确保GOPROXY指向off，这样任何下载请求都会直接失败而不是挂起等待，构建时Go发现缓存中已有匹配版本就会直接使用。
方案三：内网搭建私有模块代理
对于需要长期在隔离网络中开发的团队，建议搭建一个私有代理服务。开源项目Athens是常见选择，它可以配置成磁盘缓存模式，在有网环境预先把常用模块拉取一遍填充缓存，再把整个缓存数据搬进内网运行。
配置好之后，内网机器只需设置GOPROXY=http://内网代理地址，使用体验与联网环境完全一致。同时需要处理校验问题，可以通过设置GONOSUMDB或使用GONOSUMCHECK相关配置，也可以在内网自建一个sumdb代理来转发校验数据。私有代理方案的前期投入较大，但对于十人以上的团队来说，维护成本远低于逐台机器搬运缓存。
三、常见问题与排查技巧
离线环境下最典型的报错是找不到模块版本，提示信息通常包含dial tcp字样，这说明Go仍在尝试联网下载。排查时第一步执行go env GOPROXY确认代理设置，离线环境建议显式设置为off，例如go env -w GOPROXY=off，这样报错会立刻出现，方便定位是哪个模块缺失。
另一个高频问题是校验失败。如果go.sum文件中的哈希与缓存内容不匹配，Go会拒绝构建。在确认缓存来源可信的前提下，可以删除go.sum中对应的条目再执行go mod tidy重新生成。但切记不要用GONOSUMDB=*之类的配置全局关闭校验，这会让项目失去依赖完整性的保护，正确做法是为特定的私有模块配置跳过名单。
还有一种情况是缓存目录权限混乱导致的异常，症状是明明模块存在却报错not found。此时可以执行go clean -modcache清空缓存重来，或者在迁移时使用rsync的archive模式保留完整属性。企业环境中建议将GOMODCACHE放在磁盘空间充足的分区，模块缓存只增不减，长期使用后体积可观。
最后提醒一点，go.mod中的Go版本声明要与内网机器上的工具链兼容。如果go.mod写着go 1.21而内网只有1.19，即使依赖齐全也可能构建失败。制作离线交付包时，把指定版本的Go工具链一并打包，能省去不少环境差异带来的麻烦。
Go modulesgo get离线依赖修改时间：2026-09-14 11:27:09