Go mod edit -fmt 怎样只整理 go.mod 格式不改依赖

手工合并分支或脚本改过 go.mod 后，最常见的需求不是升级依赖，而是把文件恢复成 Go 工具链习惯的排版。这个场景直接使用 go mod edit -fmt：它只重新格式化当前主模块的 go.mod，不会查询模块版本，也不会因为格式化动作改写 go.sum。

真正需要记住的一句话是：-fmt 负责“把文件写整齐”，go get 负责调整指定依赖，go mod tidy 负责让依赖声明与源码保持一致。

先把格式整理和依赖维护分开

go mod edit 的定位是给工具或脚本编辑 go.mod。官方命令说明明确指出，它只读取目标文件，不会为文件中的模块主动查找信息；当没有其它编辑参数时，-fmt 才是专门用于“只格式化”的选项。

所以，如果 diff 只表现为缩进、空行或指令块排版变化，先用 -fmt 就够了；如果 require、replace 或 go.sum 也要变化，就已经超出格式化命令的职责。

只整理当前 go.mod 的最小命令

在主模块根目录执行下面的命令即可。它不需要填写模块名，也不需要先运行 go mod tidy。

# 进入包含 go.mod 的主模块目录
cd path/to/your-module

# 只重新格式化 go.mod，不执行依赖升级或清理
go mod edit -fmt

# 查看本次文件变化，确认只是排版或块布局变化
git diff -- go.mod

如果目标文件不在当前主模块，也可以在编辑参数之后写明文件路径：

# 指定一个要整理的 go.mod 文件
go mod edit -fmt ./tools/go.mod

这里的“只”是职责边界，不是说文件的字节一定完全不变。格式化器可能重排由 Go 语法允许的块结构，但不会替你解析源码、计算缺失依赖或选择版本。

脚本场景：-print 和 -json 什么时候更合适

如果你的目标是把结果交给人看，使用 -print；如果要让脚本读取模块路径、require、replace 等字段，使用 -json。这两个选项改变的是输出形态，不是依赖求解策略。

# 只把格式化后的 go.mod 打到标准输出，不回写文件
go mod edit -print go.mod

# 输出结构化数据，便于脚本读取模块信息
go mod edit -json go.mod

自动化任务中可以把“读取”和“写回”拆开：先用 -json 判断文件是否包含目标指令，再由专门的编辑参数修改，最后让 Go 工具链隐式完成格式化。不要把 JSON 输出当成完整模块图；官方说明也提醒，-json 描述的是这个 go.mod 文件本身，不等同于 go list -m -json all 的完整构建模块集合。

依赖真的变了，就换命令

下面几种情况不要只执行 go mod edit -fmt：

• 新增了源码 import，需要补齐模块：使用 go mod tidy，它会按模块源码和测试依赖调整 go.mod 与 go.sum。
• 明确要升级或降级某个库：使用 go get module@version，让 Go 处理版本约束。
• 要改变模块路径、替换依赖或增加工具链声明：可以用 go mod edit 的对应编辑参数，但这已不再是“只整理格式”。

实践中我会把格式整理放在提交前，把依赖维护放在一个能单独审查的变更里。这样看到 go.mod diff 时，排版噪音不会掩盖真正的版本或依赖关系变化。

常见问题

执行 go mod edit -fmt 会下载依赖吗？

按命令定位，它只读取并写回目标 go.mod，不会为了格式化去解析远程模块。若后续执行了 go get、go mod tidy 或其它需要加载模块图的命令，才应按那些命令的行为判断网络访问。

为什么格式化后仍然需要提交 go.mod？

因为 go.mod 本身被改写了。是否提交应看 diff 是否符合预期；如果出现依赖版本、replace 或其它非预期内容，先停止提交并回到产生这些变化的编辑命令排查。

把 go mod edit -fmt 当成模块文件的排版工具即可：它适合清理人工编辑留下的格式差异，不负责推断依赖，也不能代替 go get 和 go mod tidy。