ShowDocs
搜索文章Ctrl K

外观

← 返回Go列表
排错

Go 工具链：环境、构建、测试与命令速查 ​

运行、测试、依赖与排错 ​

适用 Go 1.27.2；通用 go 命令适用于 PowerShell、Bash、Zsh。Windows/Linux 示例运行是历史记录，本轮没有执行以下命令；macOS 仅作平台说明，本项目不执行平台运行验证。先 cd 到含 go.mod 的目录；不确定路径先看 目录与模块。

go version 与环境检查 ​

go version 显示实际执行的工具链版本和平台；go env GOOS GOARCH GOMOD 查看目标平台及模块文件。Windows Get-Command go，Bash/Zsh command -v go 检查选中的可执行文件。多个安装并存时先解决 PATH 顺序，不要依据编辑器状态栏猜版本。

go run 与 go build ​

go run . 编译并运行当前包，命令行参数放点号后，例如 go run ./task-cli list。go build -o learning-api.exe . 生成 Windows 程序；Linux/macOS 使用 go build -o learning-api .。成功构建通常无输出，运行需要 ./learning-api.exe 或 ./learning-api。build 会写输出文件，不能用与重要数据同名的输出路径。

go.mod file not found：进入正确目录；仅在新项目空目录执行 go mod init example.com/study。已有仓库示例不要再次 init。package ... is not a main package：正在编译可复用库，不能直接作为可执行程序启动。

go test 与失败定位 ​

go test ./... 测试所有子包；go test -v ./... 显示各测试；go test -run TestSum -count=1 . 只跑匹配测试且不复用结果缓存。[no test files] 表示没有测试，不是行为验证通过。go vet ./... 做静态检查。race 检查及工具链前提见 数据竞争。

失败时记录输入、实际/预期、文件行号，先用单个测试复现再修改。go test -cover ./... 的覆盖比例说明执行到哪些语句，不代表每个断言合理，更不能代替失败路径测试。

go mod tidy 与格式化 ​

go mod download 下载已有模块声明的依赖；go mod tidy 根据 import 补齐/清理依赖，可能修改 go.mod 与 go.sum。依赖更新后读差异、重跑测试，不要把删除 go.sum 当作网络故障的通用解决方案。go fmt ./... 会改源文件格式；提交前检查差异。

项目详细命令：文件工具、HTTP、Gin/SQLite。版本命令与模块规则依据：Go command。

Go 操作与命令 ​

本页是命令速查，需先安装 Go 并进入正确模块；命令中成对双花括号包围的内容是待替换参数，不能原样执行。以下命令未在本轮执行，download/tidy/run 可能访问网络，clean -modcache 会删除共享模块缓存，按各条目的影响范围使用。

检查工具链与环境 ​

go · Go 工具链入口，支持模块管理、编译和测试；在项目目录运行相关命令 ​

  • 查看已安装工具链版本:
bash
go version
  • 查看子命令帮助:
bash
go help {{test}}
  • 列出当前模块中的包:
bash
go list ./...

go env · 查看或持久化 Go 配置；-w/-u 会影响此后运行的 Go 命令 ​

  • 查看系统、架构和模块缓存目录:
bash
go env GOOS GOARCH GOMODCACHE
  • 以 JSON 输出所需配置:
bash
go env -json GOPATH GOMOD GOWORK
  • 持久化私有模块匹配规则；按组织路径调整:
bash
go env -w GOPRIVATE="{{example.com/team/*}}"
  • 移除持久化覆盖，恢复环境或默认设置:
bash
go env -u GOPRIVATE

初始化、依赖与工作区 ​

go mod · 管理模块依赖及校验数据；修改依赖前确认当前模块 ​

  • 显示模块依赖图:
bash
go mod graph
  • 解释某个包为何被当前模块需要:
bash
go mod why {{example.com/lib/pkg}}
  • 校验本地缓存模块是否被修改，不是依赖安全审计:
bash
go mod verify
  • 将依赖复制到 vendor，会更新本地文件:
bash
go mod vendor

go mod download · 下载模块依赖到本地缓存 ​

  • 下载当前模块需要的依赖:
bash
go mod download
  • 下载明确指定的模块版本:
bash
go mod download {{example.com/lib}}@{{v1.2.3}}
  • 以 JSON 输出下载路径与校验信息:
bash
go mod download -json {{example.com/lib}}@{{v1.2.3}}

go mod init · 为当前目录创建 go.mod；模块路径应与实际仓库或发布路径一致 ​

  • 初始化模块，会创建 go.mod:
bash
go mod init {{example.com/team/service}}
  • 检查初始化后的模块配置路径:
bash
go env GOMOD
  • 查看主模块身份:
bash
go list -m

go mod tidy · 使 go.mod 和 go.sum 与源码引用保持一致；可能下载依赖并修改文件 ​

  • 补充缺失依赖并移除未使用依赖:
bash
go mod tidy
  • 显示移除的模块及更多操作信息:
bash
go mod tidy -v
  • 仅显示所需差异，不修改文件；有差异时返回非零，需支持 -diff 的 Go 版本:
bash
go mod tidy -diff

go work · 使用工作区同时开发多个模块；init/use/sync 会修改本地工作区或模块文件 ​

  • 将已有模块组成工作区，创建 go.work:
bash
go work init {{./service}} {{./shared}}
  • 添加已有模块到工作区:
bash
go work use {{./tools}}
  • 将工作区依赖版本同步回模块，可能修改各模块 go.mod:
bash
go work sync
  • 检查当前生效的工作区路径:
bash
go env GOWORK

运行与构建程序 ​

go build · 编译 Go 包及其依赖 ​

  • 编译当前包:
bash
go build .
  • 检查当前模块下所有包是否能编译:
bash
go build ./...
  • 为 main 包指定输出路径，会覆盖同名文件:
bash
go build -o {{bin/service}} {{./cmd/service}}
  • 使用构建标签编译:
bash
go build -tags {{integration}} ./...

go run · 编译并运行 Go 程序 ​

  • 运行当前目录的 main 包:
bash
go run .
  • 运行指定命令包:
bash
go run {{./cmd/service}}
  • 在包路径后传递程序参数:
bash
go run {{./cmd/service}} {{--config}} {{config.yaml}}
  • 运行指定版本工具，会下载并执行代码:
bash
go run {{example.com/tool/cmd/tool}}@{{v1.2.3}} {{--help}}

格式化、检查与测试 ​

go fmt · 格式化包内 Go 源码，会直接改写文件；使用版本控制审阅差异 ​

  • 格式化当前包:
bash
go fmt .
  • 格式化当前模块所有包:
bash
go fmt ./...
  • 只打印格式化时会执行的命令，不改写文件:
bash
go fmt -n ./...

go test · 运行 Go 测试、检查竞态并生成覆盖率报告 ​

运行 Go 测试、检查竞态并生成覆盖率报告。

  • 测试当前模块全部包:
bash
go test ./...
  • 仅运行匹配名称的测试并显示详细结果:
bash
go test ./... -run "{{^TestExample$}}" -v
  • 忽略已有测试结果缓存并重新运行:
bash
go test ./... -count=1
  • 检查运行时数据竞争；需要支持的系统及工具链:
bash
go test -race ./...
  • 生成覆盖率文件，会覆盖指定文件:
bash
go test ./... -coverprofile={{coverage.out}}

go vet · 检查 Go 代码中可能的错误 ​

  • 检查当前模块所有包:
bash
go vet ./...
  • 只运行 printf 格式相关检查:
bash
go vet -printf ./...
  • 检查指定包:
bash
go vet {{./internal/service}}

阅读文档与报告问题 ​

go bug · 报告一个错误 ​

更多信息：https://pkg.go.dev/cmd/go#hdr-Start_a_bug_report。

  • 打开一个网页并开始报告错误：
bash
go bug

go doc · 显示包或符号的文档 ​

更多信息：https://pkg.go.dev/cmd/go#hdr-Show_documentation_for_package_or_symbol。

  • 显示当前包的文档：
bash
go doc
  • 显示包文档及导出符号：
bash
go doc {{encoding/json}}
  • 同时显示符号的文档：
bash
go doc -all {{encoding/json}}
  • 同时显示源代码：
bash
go doc -all -src {{encoding/json}}
  • 显示指定的符号：
bash
go doc -all -src {{encoding/json.Number}}

清理构建与缓存 ​

go clean · 移除目标文件和缓存文件 ​

更多信息：https://pkg.go.dev/cmd/go#hdr-Remove_object_files_and_cached_files。

  • 只打印移除命令，而不会真正移除任何东西：
bash
go clean -n
  • 删除编译缓存：
bash
go clean -cache
  • 删除所有测试结果缓存：
bash
go clean -testcache
  • 删除模块缓存：
bash
go clean -modcache

示例整理自 tldr-pages，作者为 tldr-pages team and contributors，遵循 CC BY 4.0。

静态自检 ​

遇到 go.mod file not found 时应先检查什么？提示：区分已有模块和新空目录；不要先在磁盘根目录 init。

参考解法

先查看当前目录与 go.mod；已有仓库切到模块根目录，新空目录才执行替换占位符后的 go mod init。go mod tidy 可能改文件，并非检查目录的无副作用替代品。

继续阅读