Go mod tidy 为什么删掉看似需要的依赖

go mod tidy 会删除看似需要的依赖，是因为它整理的是当前模块源码与工具声明实际需要的模块，而不是维护一份“以后可能用到”的安装清单。只在配置文件、生成命令或注释中出现的模块名，不一定构成保留依据；应先找出依赖由哪个包真正使用，再决定修改导入、工具声明还是模块位置。

Go Modules 官方文档：https://go.dev/ref/mod#go-mod-tidy

依赖写进 go.mod 就一定会保留吗

设想一个报表服务：开发者准备接入数据库驱动，先把模块加入 go.mod，但接入代码尚未保存，配置里只有驱动名称。随后整理依赖，刚加入的行消失了。这个场景中，准备接入的计划与源码的导入关系是两件事；反复手工补回同一行，不能补出缺失的代码关系。

require 声明模块需求，import 则引用包。一个模块可包含多个包，判断时不能把模块路径、包路径和磁盘目录混成同一个名字。开发者应从调用位置寻找包，再回到提供该包的模块，而不是只在配置里搜索模块名。

主模块、源码包、测试包、工具声明、外部包与模块需求构成不同层面的静态关系。这里的“需要”取决于 Go 所加载的关系集合，不取决于某个 README 是否提过模块，也不是看本机曾否下载过它。

先确认整理的是哪个模块

# 在准备整理的项目目录确认当前模块文件、工作区和工具链
go env GOMOD GOWORK
go version
# 查看源码所在目录，确认其是否属于这个模块
pwd

这些命令供读者在自己的项目中使用，本文没有执行或伪造输出。多模块仓库尤其容易混淆：在仓库根目录看到一个服务目录，不等于根模块负责其所有依赖。子目录自己的 go.mod 划出了独立模块；工作区可以让多个模块一起开发，但不能把它理解成“替每个模块自动保留同一套依赖”。

先确认修改的 go.mod 属于谁，再讨论某行该不该保留。还要确认代码已经保存并纳入当前分支：IDE 未保存的 import、尚未生成的文件和其他分支中的实现，都不等于当前磁盘上的依赖关系。

配置里的依赖为什么没有导入关系

数据库驱动是一个直观例子。若程序只出现 "mysql" 这个驱动名，没有把对应驱动包链接进程序，字符串本身不会自动变成 Go import。确实需要通过初始化注册驱动时，可以在真正使用该驱动的应用包中采用空白导入。

驱动官方仓库：https://github.com/go-sql-driver/mysql

package main

import (
    "database/sql"
    "fmt"

    // 引入包的初始化注册行为，不是用无意义代码强行保留模块。
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    // 只查看已注册驱动，不连接数据库，也不需要账号或连接字符串。
    fmt.Println(sql.Drivers())
}

这是原创的最小应用示例，说明导入关系，不是数据库连接教程。实际项目应选择与自身 Go 工具链兼容的驱动版本；本文没有承诺任意历史工具链都支持最新驱动。只有应用真的需要这个初始化副作用才这样导入，不能为保留无用依赖随意增加 _。

相同道理也适用于动态插件名、配置中的包路径和脚本下载地址：Go 不会把任意字符串解释成静态依赖。若某能力由外部进程提供，它可能本来就应该由部署脚本或独立工具模块管理，而不是伪装成应用库。

开发工具应该怎样声明

“我明明安装过生成器，为什么 tidy 还删？”要区分本机有可执行文件与模块声明了工具需求。Go 1.24 起提供 tool 指令，可把工具包明确记录为模块依赖；需要兼容旧工具链的团队应另行选择匹配其版本的工具管理方式，而不是直接提交旧工具链无法理解的指令。

# 以下是占位写法，不可原样执行：替换为真实工具包和团队选定版本
go get -tool example.com/team/generator/cmd/generator@v1.2.3
# 在支持工具声明的环境中，通过已声明的工具包调用
go tool example.com/team/generator/cmd/generator

example.com/team/generator 是说明语法的虚构路径，不是下载地址。工具声明记录的是工具包，版本由相应模块需求承载。应把生成器与业务代码的用途分开；不要对不可导入的 main 包机械添加空白 import。

旧项目中常见带自定义构建标签的 tools.go。它是否适合当前工具、Go 版本及工具包类型，需要结合该工具的说明。不能认为“只要有 go:generate 注释就会自动保留依赖”，也不要把工具入口放进 ignore 标签文件后期待 tidy 一定加载它。

构建标签和测试依赖有哪些例外

不要把删除原因笼统归结为“Linux 下运行，所以 Windows 专用依赖被删了”。tidy 会考虑平台文件和自定义构建标签，测试导入也在其考虑范围内。特殊的 ignore 标签并不会被当成启用；testdata、以点或下划线开头的目录也有默认忽略边界，除非相关包被显式导入。先判断代码属于哪种情况，比随手修改系统变量更有帮助。

tidy 也可能改变间接依赖记录，不宜仅凭行数减少或注释移动判定功能丢失。反过来，如果源码加载已经报错，也不要把不完整的整理结果当成业务依赖证明；先处理缺失文件、错误导入或版本不兼容。不要为了让命令继续而习惯性加上忽略错误的选项。

删除后该恢复配置还是修改代码

在报表服务这个场景里，合理的修复不是盲目恢复整个文件，而是按用途补齐真实声明：驱动由应用正确导入，生成器由工具声明或独立工具模块管理，另一个服务的库则在那个服务的模块中维护。确定归属后再整理依赖，并在自己的开发环境进行对应业务构建和测试。

# 在已确认归属、源码已保存的模块目录整理依赖，可能修改 go.mod 和 go.sum
go mod tidy
# 使用 Git 的项目可阅读变更，理解增加和删除分别来自哪里
git diff -- go.mod go.sum

加上 indirect 注释能强行保留吗？ 不能把它当成保留开关。注释描述关系，tidy 仍会按加载到的包与工具调整需求。

replace 能代替使用关系吗？ replace 表达替换位置或版本，不是某功能已在应用中使用的证明。不要仅因存在替换项就断言其模块必须保留为直接需求。

必须先删除 go.sum 再整理吗？ 不需要把删除校验文件当作常规修复。先确定模块归属和真实导入，再让命令管理必要记录，避免把有价值的变更线索一起丢掉。

最终要回答的不是“怎样阻止 tidy 删除一行”，而是“这个依赖由哪段当前代码或工具声明负责”。能够指出明确归属，依赖清单才有可解释的维护依据。