本文更新于2021-11-11。

翻译自Command go官方文档（https://golang.org/cmd/go/，国内可使用https://golang.google.cn/cmd/go/；同理，文中golang.org的链接也可使用golang.google.cn替换）。章节段落结构稍作改变，对应的go版本为1.16。

go

go <command> [arguments]

go是管理Go源代码的工具。

command可参阅 go help——查看帮助信息 小节。

go bug——启动bug报告

go bug

打开默认浏览器并启动新的bug报告，报告包括有用的系统信息。

go build——编译包及其依赖包

go build [-o output] [build flags] [packages]

编译指定导入路径的包，以及其依赖包，但不安装结果。

如果构建的参数为单个目录下的.go文件列表时，会将它们当作指定单个包的源文件列表。

当编译包时，忽略以“_test.go”结尾的文件。

当编译单个main包时，生成的可执行文件会被写入到以第一个源文件（如：“go build ed.go rx.go”写入“ed”或“ed.exe”）或源代码目录名（如：“go build unix/sam”写入“sam”或“sam.exe”）命名的输出文件中。当写入Windows下的可执行文件时会添加“.exe”后缀。

当编译多个包或单个非main包时，build编译包但会丢弃目标对象文件，行为只用于类似检查包是否可以构建。

标志（flag）：

• -i：同时安装目标的依赖包。-i标志被反对使用。编译的包会自动被缓存。
• -o output：强制将结果可执行文件或对象文件写入指定名字的输出文件或目录，而不是在本节最上两个段落所描述的默认行为。如果指定的名字为一个已存在的目录或者以斜杠或反斜杠结尾，则所有结果可执行文件将写入到该目录中。

构建标志（build flags）会被build、clean、get、install、list、run、test命令共享：

• -a：强制重新构建已经是最新的包。
• -asmflags \'[pattern=]arg list\'：传递给每次go tool asm调用的参数。
• -buildmode mode：使用的构建模式，更多信息参阅“go help buildmode”。
• -compiler name：使用的编译器名，即runtime.Complier（gccgo或gc）。
• -gccgoflags \'[pattern=]arg list\'：传递给每次gccgo编译器/链接器调用的参数。
• -gcflags \'[pattern=]arg list\'：传递给每次go tool complie调用的参数。
• -installsuffix suffix：在包安装目录名字中使用的后缀，以便使输出文件与默认构建分开。如使用-race标志，安装后缀会自动设置为race，或如果显式设置则在其后追加_race。对-msan也同样。使用需要使用非默认编译标志的-buildmode选项也又类似效果。
• -ldflags \'[pattern=]arg list\'：传递给每次go tool link调用的参数。
• -linkshared：链接到的之前使用-buildmode=shared生成的共享库。
• -mod mode：使用的模块下载模式：readonly、vendor或mod。默认情况下，如果vendor目录存在且go.mod中的go版本为1.14或更高，go命令表现如同-mod=vendor被设置一样。否则，go命令表现如同-mod=readonly被设置一样。详情参阅https://golang.org/ref/mod#build-commands。
• -modcacherw：令保留在模块缓存中的新创建的目录可读写，而不是令它们只读。
• -modfile file：在模块感知模式下，读取（并且可能写入）备用的go.mod文件而不是在模块根目录下的go.mod文件。名字为“go.mod”的文件仍然必须存在用来确定模块根目录，但其不会被访问。当-modfile被指定，备用的go.sum文件也会被使用：其路径从-modfile标志产生，通过去除“.mod”扩展名并追加“.sum”。
• -overlay file：读取为构建操作提供覆盖的JSON配置文件。文件是只有一个字段的JSON结构，名为“Replace”，映射每个磁盘文件路径（一个字符串）至其后备文件路径，以使构建运行起来如同磁盘文件路径存在有后备文件路径提供的内容，或如果其后备文件路径为空则如同磁盘文件路径不存在。对-overlay标志的支持有一些限制：重要的是，从包含路径之外包含的cgo文件必需与Go包被包含于相同的目录，且当二进制和测试分别通过go run和go test运行时覆盖不会出现。
• -msan：启用与内存清理程序的互操作，只支持linux/amd64、linux/arm64，并且只能使用clang/llvm作为宿主C编译器。在linux/arm64上，pie构建模式将被使用。
• -n：打印实际需执行的命令，但不运行。
• -p n：可以并行运行的程序——如构建命令或测试二进制文件——的数量。默认为GOMAXPROCS，通常是可用的CPU的数量。
• -pkgdir dir：从dir而不是通常的位置安装和加载所有包（pkg）。例如，当使用非标准设置构建时，使用-pkgdir来令在特定的目录生成包。
• -race：启用数据竞态检测，只支持linux/amd64、freebsd/amd64、darwin/amd64、windows/amd64、linux/ppc64le、linux/arm64（只对48位VMA）。
• -tags tag,list：构建期间需满足的构建标记（tag），为逗号分隔的列表。关于构建标记，参阅go/build包文档中关于构建约束的描述。（早期Go版本使用空白分隔的列表，已经被反对使用，但仍然能识别。）
• -toolexec \'cmd args\'：用来调用如vet和asm等工具链程序的程序。例如，go命令将运行“cmd args /path/to/asm ”，而不是运行asm。TOOLEXEC_IMPORTPATH环境变量将被设置，其匹配正在构建的包的“go list -f {{.ImportPath}}”。
• -trimpath：从目标可执行文件中移除所有文件系统路径。作为文件系统绝对路径的替代，记录下的文件名将以“go”（对标准库），或“模块路径@版本”（当使用模块），或“import路径”（当使用GOPATH）开头。
• -v：打印编译的包名。
• -work：打印临时工作目录并在退出时不删除之。
• -x：打印实际需执行的命令，并运行。

-asmflags、-gccgoflags、-gcflags、-ldflags接受一个以空白分隔的参数列表，用以在构建时传递给底层工具。要在列表元素中嵌入空白，需使用单引号或双引号括起。参数列表前面可以是一个包模式和一个等号，它将该参数列表的使用限制为与该模式匹配的包（有关包模式的说明，请参阅“go help packages”）。如果没有模式，参数列表只应用于命令行中命名的包。这些标志可以使用不同的模式重复指定，以便为不同的包指定不同的参数。如果一个包与多个标志中给定的模式匹配，则使用最后一个指定的。例如：“go build -gcflags=-S fmt”只打印fmt包的反汇编，“go build -gcflags=all=-S fmt”则打印fmt包及其所有依赖包的反汇编。

有关指定包的详细信息，参阅“go help packages”。有关包和二进制文件的安装位置的详细信息，参阅“go help gopath”。有关Go和C/C++之间调用的详细信息，参阅“go help c”。

注意：构建遵守某些约定，例如在“go help gopath”中描述的。然而，并不是所有项目都能遵守这些约定。使用自己的约定来安装，或使用一个单独的软件构建系统，可以选择使用低级别的调用，如“go tool compile”和“go tool link”，来避免构建工具的开销和设计决策。

参阅：go install，go get，go clean。

go clean——删除对象文件和缓存文件

go clean [clean flags] [build flags] [packages]

从包源代码目录中删除对象文件。go命令在临时目录中构建大多数对象文件，因此go clean主要关心通过其他工具或通过手动调用go build遗留下来的对象文件。

如果给出packages参数或者-i或-r标志，clean将从与导入路径对应的每个源文件目录中删除以下文件：

• _obj/：旧的对象文件目录，来自Makefile。
• _test/：旧的测试文件目录，来自Makefile。
• _testmain.go：旧的gotest文件，来自Makefile。
• test.out：旧的测试日志，来自Makefile。
• build.out：旧的测试日志，来自Makefile。
• *.[568ao]：对象文件，来自Makefile。
• DIR(.exe)：来自go build。
• DIR.test(.exe)：来自go test -c。
• MAINFILE(.exe)：来自go build MAINFILE.go。
• *.so：来自SWIG。

在上述列表中，DIR表示目录路径的最后一个元素，MAINFILE表示目录中任何在构建包时未包含的go源文件的基本名。

标志：

• -cache：删除整个go build缓存。
• -i：删除相关的已安装的归档文件或二进制文件（由“go install”创建）。
• -modcache：删除整个模块下载缓存，包括指定版本依赖的已解压的源代码。
• -n：打印实际需执行的命令，但不运行。
• -r：递归地应用于所有由导入路径指定的依赖包。
• -testcache：令go build缓存中所有测试结果过期。
• -x：打印实际需执行的命令，并运行。

关于构建标志的更多信息，参阅“go help build”。

关于指定包的更多信息，参阅“go help packages”。

go doc——查看包或符号的文档

go doc [doc flags] [package|[package.]symbol[.methodOrField]]

打印由参数（包、常量、函数、类型、变量、方法、结构体字段）指定的项相关的文档注释，该项后跟该项下的每个第一级项（该项为包即为包级声明，该项为类型即为其方法，依次类推）的一行概要。

doc命令接受0个、1个或2个参数。

如使用0个参数，即运行：

go doc

会打印当前目录下包的包文档。如果包是命令的包（main包），包的导出符号会从展示输出中省略，除非指定了-cmd标志。

当使用1个参数运行时，参数会被视为要展示文档的项的Go语法表示。参数指定的项取决于GOROOT和GOPATH中安装的内容，以及参数的格式。参数的格式如下所示：

go doc <pkg>
go doc <sym>[.<methodOrField>]
go doc [<pkg>.]<sym>[.<methodOrField>]
go doc [<pkg>.][<sym>.]<methodOrField>

上述列表中参数匹配的第一项是待打印文档的项。（参见下面的示例。）但是，如果参数是以大写字母开头的，则假设其表示当前目录中的符号或方法。

对于包，扫描顺序是从词汇上按广度优先确定的。也就是说，呈现的包是匹配搜索的其中一个，并且为最接近搜索根，在其层次结构中搜索到的从词汇上来说的第一个。GOROOT树总是在GOPATH之前被完整扫描。

如果没有包被指定或被匹配，则选择当前目录下的包，因此“go doc Foo”显示当前目录中符号为Foo的文档。

包路径必须是限定路径或者是路径的正确后缀。go工具通常的包机制不适用于：类似“.”和“...”的包路径元素，是不被go doc实现的。

当使用2个参数运行时，第一个参数必须是完整的包路径（而不仅仅是后缀），第二个参数是一个符号、符号的方法或符号的结构体字段。这与godoc接受的语法类似：

go doc <pkg> <sym>[.<methodOrField>]

在所有的形式中，当匹配符号时，参数的小写字母不区分大小写，但大写字母只匹配大写。这意味着如果不同的符号有不同的大小写，则包中小写字母参数可能有多个匹配。如果这种情况发生，将打印所有匹配项的文档。

示例：

• go doc：显示当前包的文档。
• go doc Foo：显示当前包中Foo的文档。（Foo以大写字母开头，因此其不能匹配为一个包路径。）
• go doc encoding/json：显示encoding/json包的文档。
• go doc json：encoding/json的简写。
• go doc json.Number（或go doc json.number）：显示json.Number的文档和方法概要。
• go doc json.Number.Int64（或go doc json.number.int64）：显示json.Number的Int64方法的文档。
• go doc cmd/doc：显示doc命令的包文档。
• go doc -cmd cmd/doc：显示doc命令的包文档和导出符号。
• go doc template.new：显示html/template的New函数的文档。（html/template从词汇上来说位于text/template之前。）
• go doc text/template.new（一个参数）：显示text/template的New函数的文档。
• go doc text/template new（两个参数）：显示text/template的New函数的文档。

至少在当前的包树结构中，以下调用均会打印json.Decoder的Decode方法的文档：

• go doc json.Decoder.Decode
• go doc json.decoder.decode
• go doc json.decode
• cd go/src/encoding/json; go doc decode

标志：

• -all：显示包的所有文档。
• -c：匹配符号时区分大小写。
• -cmd：将命令（main包）当作普通包看待。否则当显示包的顶层文档时，main包的导出符号将被隐藏。
• -short：每个符号一行表示。
• -src：显示符号的完整源代码。这将显示其声明和定义的完整Go代码，如函数定义（包括函数体），类型声明或闭包引用的常量块。输出可能因此包含未导出的细节。
• -u：像导出符号、方法、字段一样显示未导出的符号、方法、字段的文档。

go env——打印环境变量

go env [-json] [-u] [-w] [var ...]

打印Go环境变量信息。

env默认像shell脚本（在Windows下，像批处理文件）一样打印信息。如果一个或多个变量名作为参数给定，env将为每个指定名字的变量新起一行打印其值。

标志：

• -json：以JSON格式打印环境变量，而不是像shell脚本一样。
• -u：需要一个或多个参数，如果指定名字的环境变量已经使用“go env -w”设置，则取消其默认设置。
• -w：需要一个或多个格式为NAME=VALUE的参数，使用指定的值修改指定名字的环境变量的默认设置。

关于环境变量的更多信息，参阅“go help environment”。

go fix——使用新的API更新包代码

go fix [packages]

在通过导入路径指定的包上运行Go fix命令。

关于fix的更多信息，参阅“go doc cmd/fix”。关于指定包的更多信息，参阅“go help packages”。

如需使用特定的选项，运行“go tool fix”。

参阅：go fmt，go vet。

go fmt——gofmt（重新格式化）包代码

go fmt [-n] [-x] [packages]

在导入路径指定的包上运行“gofmt -l -w”命令。将打印被修改的文件名。

关于gofmt的更多信息，参阅“go doc cmd/gofmt”。关于指定包的更多信息，参阅“go help packages”。

标志：

• -mod：标志的值设置要使用那种模块下载模式：readonly还是vendor。更多信息参阅“go help modules”。
• -n：打印实际需执行的命令，但不运行。
• -x：打印实际需执行的命令，并运行。

如需使用特定的选项，直接运行gofmt。

参阅：go fix，go vet。

go generate——通过执行源代码生成Go文件

go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]

通过在现存文件中描述的指令执行命令。命令可以运行任何进程，但目的是创建或更新Go源文件。

go generate永远不会通过go build、go get、go test等自动运行。必须明确地运行。

go generate扫描文件搜索指令，指令是如下格式的行：

//go:generate command argument...

(注意：开头没有空白，“//go”中间也没有空白)其中command是要运行的生成器，对应于可在本地运行的可执行文件。其必须在shell PATH中（如gofmt），或为一个完全限定路径（如/usr/you/bin/mytool），或为一个命令别名，如下所述。

注意go generate不解析文件，因此在注释或多行字符串中看起来像指令的行将会被视为指令。

指令的参数是空白分隔的记号，记号可为双引号引起的字符串，在生成器运行时每个记号作为独立的参数传递给生成器。

带引号的字符串使用Go语法，并在执行前进行计算；一个带引号的字符串作为生成器的一个单独的参数。

为了向人类和机器工具传达，代码是自动生成的，生成的源代码应有一行匹配如下的正则表达式（以Go语法）：

^// Code generated .* DO NOT EDIT\.$

该行必需出现在文件中第一行非注释、非空行文本之前。

go generate在运行生成器时会设置几个环境变量：

• $GOARCH：执行时的体系结构（arm、amd64等）。
• $GOOS：执行时的操作系统（linux、windows等）。
• $GOFILE：文件的基本名（base name）。
• $GOLINE：指令在源文件中的行号。
• $GOPACKAGE：包含指令的文件的包名。
• $DOLLAR：一个美元符号。

除了变量替换和带引号的字符串求值，在命令行上不会执行诸如“globbing”（文件名通配符匹配）之类的特殊处理。

作为执行命令前的最后一步，对任何以字母数字命名的环境变量（如$GOFILE或$HOME）的任何调用，均会在命令行中展开。在所有的操作系统上环境变量名的展开语法都类似$NAME这样。由于求值的顺序，环境变量甚至在带引号的字符串中也会展开。如果名字为NAME的环境变量未设置，$NAME会展开为空字符串。

如下形式的指令：

//go:generate -command xxx args...

表示，只对于此源文件的接续部分，字符串xxx代表由参数指定的命令。这可以用来创建别名或处理多个单词的生成器。例如：

//go:generate -command foo go tool foo

表示，命令“foo”代表生成器“go tool foo”。

generate按照命令行中给定的顺序处理包，一次一个。如果命令行列出一个单独的目录中的.go文件，它们会作为一个单独的包对待。在包中，generate按照包中文件名的顺序处理源文件，一次一个。在一个源文件中，generate按照在文件中出现的顺序运行生成器，一次一个。go generate工具还会设置构建标记“generate”，以便文件可以被go generate审查但会在构建时忽略。

对于带有无效代码的包，generate只处理带有有效包子句的源文件。（译注：未看懂）

如果任何一个生成器返回了错误退出状态，“go generate”会跳过该包所有接续的处理。

生成器运行在包的源代码目录中。

标志：

• -run=""：如果非空，指定一个正则表达式来选择执行的指令，该指令的完整原始源文本（忽略结尾处的空白和换行）匹配正则表达式。

也接受标准的构建标志，包括-v、-n和-x。

• -n：打印实际需执行的命令，但不运行。
• -v：打印正在处理的包名和文件名。
• -x：打印实际需执行的命令，并运行。

关于构建标志的更多信息，参阅“go help build”。

关于指定包的更多信息，参阅“go help packages”。

go get——添加依赖包至当前模块并安装之

go get [-d] [-t] [-u] [-v] [build flags] [packages]

get解析其命令行参数为特定模块版本的包，更新go.mod来依赖于那些版本，下载源代码至模块缓存，然后构建和安装指定名字的包。

要添加对包的依赖或更新其至最后的版本：

go get example.com/pkg

要更新或下载包至特定的版本：

go get example.com/[email protected]

要移除对模块的依赖并降级依赖于它的模块：

go get example.com/mod@none

详情参阅https://golang.org/ref/mod#go-get。

“go install”命令可以用来构建和安装包。当版本被指定时，“go install”运行在模块感知模式并忽略当前目录中的go.mod文件。例如：

go install example.com/[email protected]
go install example.com/pkg@latest

详情参阅“go help install”或https://golang.org/ref/mod#go-install。

除了构建标志（在“go help build”中列出），“go get”接受以下的标志：

• -d：不构建和安装包。get将只更新go.mod并下载构建包所需的源代码。
• -t：同时添加命令行中指定的包构建测试所需的模块。
• -u：同时更新命令行中指定的包的依赖模块，令依赖模块使用较新的次版本的发布版本或补丁版本的发布版本，前提是这些版本可用。
• -u=patch：（不是-u patch）同样更新依赖模块，但不同之处在于默认选择补丁版本的发布版本。

当-t和-u一起使用时，将也会更新构建测试所需的模块的依赖模块。

使用get来构建和安装包被反对使用。在将来的发布版本中，-d标志会默认启用，且“go get”将只用来调整当前模块的依赖。要从当前模块通过依赖来安装包，使用“go install”。要忽略当前模块来安装包，在每个参数后面带有如“@latest”的@version后缀来使用“go install”。

关于模块的更多信息，参阅https://golang.org/ref/mod。

关于指定包的更多信息，参阅“go help packages”。

上文介绍了get使用模块来管理源代码和依赖的行为。如果相反，go命令运行在GOPATH模式下，get的标志和行为的细节也会改变，如同“go help get”的内容也会不同。参阅“go help gopath-get”。

参阅：go build、go install、go clean、go mod。

go help——查看帮助信息

go help
go help <command>
go help <topic>

命令（command）为：

• bug：启动bug报告。
• build：编译包及其依赖包。
• clean：删除对象文件和缓存文件。
• doc：查看包或符号的文档。
• env：打印环境变量。
• fix：使用新的API更新包代码。
• fmt：gofmt（重新格式化）包代码。
• generate：通过执行源代码生成Go文件。
• get：添加依赖包至当前模块并安装之。
• help：查看帮助信息。
• install：编译并安装模块及其依赖。
• list：列出包和模块。
• mod：模块维护。
• run：编译并运行Go程序。
• test：测试包。
• tool：运行指定的go tool。
• version：打印Go版本。
• vet：报告包中有可能的错误。

关于命令的更多信息，参阅“go help <command>”。

额外的帮助主题（topic）为：

• buildconstraint：构建约束。
• buildmode：构建模式。
• c：Go和C之间的调用。
• cache：构建和测试缓存。
• environment：环境变量。
• filetype：文件类型。
• go.mod：go.mod文件。
• gopath：GOPATH环境变量。
• gopath-get：遗留的GOPATH的go get。
• goproxy：模块代理协议。
• importpath：import路径语法。
• module-auth：使用go.sum的模块校验。
• module-get：模块感知的go get。
• modules：模块，模块版本，及更多。
• packages：包列表和模式。
• private：下载非公共代码的配置。
• testflag：测试标志。
• testfunc：测试函数。
• vcs：用GOVCS控制版本控制。

关于主题的更多信息，参阅“go help <topic>”。

go install——编译并安装模块及其依赖

go install [build flags] [packages]

编译并安装导入路径指定的包。

可执行文件安装在GOBIN环境变量指定的目录中，默认为$GOPATH/bin或如果GOPATH环境变量没有设置时为$HOME/go/bin。$GOROOT中的可执行文件安装在$GOROOT/bin或$GOTOOLDIR，而不是$GOBIN。

如果参数有版本后缀（如@latest或@v1.0.0），“go install”在模块感知模式下构建包，忽略当前目录或任何父目录中的go.mod文件，如果有的话。这对安装可执行文件而不影响主模块的依赖很有用。为了消除关于构建中要使用哪个模块版本的歧义，参数必需满足以下约束：

• 参数必需为包路径或包模式（带有“...”通配符）。不能是标准包（如fmt），元模式（std、cmd、all），相对或绝对文件路径。
• 所有的参数带有相同的版本后缀。不同的查询是不允许的，即使它们指向相同的版本。
• 所有的参数必需指向相同模块相同版本中的包。
• 不能有模块被认作“main”模块。如果包含命令行中指定名字的包的模块有go.mod文件，其不能包含可能导致其被不一样地解析为主模块的指令（replace和exclude）。模块不能依赖于自身的一个更高的版本。
• 包路径参数必需指向main包。模式参数只会匹配main包。

如果参数没有版本后缀，“go install”可能运行在模块感知模式或GOPATH模式，取决于GO111MODULE环境变量和go.mod文件的存在。详情参阅“go help modules”。如果模块感知模式启用，“go install”运行在主模块的上下文中。

当模块感知模式禁用，其它包被安装在目录$GOPATH/pkg/$GOOS_$GOARCH中。当模块感知模式启用，其它包被构建和缓存但不会被安装。

标志：

• -i：同时安装指定名字的包的依赖。-i标志被反对使用。已编译的包会被自动缓存。

关于构建标志的更多信息，参阅“go help build”。关于指定包的更多信息，参阅“go help packages”。

参阅：go build、go get、go clean。

go list——列出包和模块

go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

列出指定名字的包，一行一个。最常用的标志是-f和-json，用以控制每个包的输出打印格式。其他标志，文档于下文，控制更多特定的细节。

默认输出显示包的导入路径：

bytes
encoding/json
github.com/gorilla/mux
golang.org/x/net/html

标志（-f或-m外的其他标志的说明需参阅-f或-m）：

• -complied：将CompiledGoFiles设置为提交给编译器的Go源文件。通常，这意味着其会重复GoFiles列出的文件，然后也会添加通过处理CgoFiles和SwigFiles生成的Go代码。Imports列表包含来自GoFiles和CompiledGoFiles所有导入的并集。

• -deps：不只是遍历指定名字的包，也会遍历它们的依赖。list以深度优先后序遍历的方式遍历它们，因此一个包会在它的所有依赖之后列出。未在命令行中显式列出的包将有一个设置为true的DepOnly字段。

• -e：改变对错误包的处理方式，那些错误包或者不存在或者内容残缺。默认情况下，list命令为每个错误包打印一条错误信息至标准错误输出中，然后在普通的打印中忽略这些错误包。使用-e标志，list命令将不会打印错误信息至标准错误输出中，而是以普通打印的方式处理错误包。错误包将有非空的ImportPath和非nil的Error字段；其他信息可能会也可能不会缺失（置为零值）。

• -export：将Export字段设置为包含指定包最新导出信息的文件名。

• -f：指定list使用的替换格式，使用template包的语法。默认的输出等同于-f \'{{.ImportPath}}\'。传递给模板的结构体为：

  type Package struct {
  	Dir           string   // 包含包源代码的目录
  	ImportPath    string   // 目录中包的导入路径
  	ImportComment string   // 包说明中导入注释的路径
  	Name          string   // 包名
  	Doc           string   // 包文档字符串
  	Target        string   // 安装路径
  	Shlib         string   // 包含本包的共享库（只在设置-linkshared时使用）
  	Goroot        bool     // 本包是否在GOROOT中
  	Standard      bool     // 本包是否是Go标准库之一
  	Stale         bool     // “go install”会否为本包进行一些处理
  	StaleReason   string   // 当Stale==true时的解析原因
  	Root          string   // 包含本包的GOROOT或GOPATH目录
  	ConflictDir   string   // 本目录在$GOPATH中的同名目录
  	BinaryOnly    bool     // 是否仅为二进制包（不再支持）
  	ForTest       string   // 包只在该指定名字包的测试下使用
  	Export        string   // 包含导出数据的文件（当使用-export时）
  	BuildID       string   // 编译的包的构建ID（当使用-export时）
  	Module        *Module  // 包包含的模块的信息，如果有的话（可以为nil）
  	Match         []string // 匹配本包的命令行模式
  	DepOnly       bool     // 如为true，则包只是一个依赖，未在命令行中显式列出
  	
  	// 源文件
  	GoFiles           []string // .go源文件（不包括CgoFiles、TestGoFiles、XTestGoFiles中的文件）
  	CgoFiles          []string // import "C"的.go源文件
  	CompiledGoFiles   []string // 提交给编译器的.go文件（当使用-compiled时）
  	IgnoredGoFiles    []string // 由于构建限制被忽略的.go源文件
  	IgnoredOtherFiles []string // 由于构建约束被忽略的非.go源文件
  	CFiles            []string // .c源文件
  	CXXFiles          []string // .cc/.cxx/.cpp源文件
  	MFiles            []string // .m源文件
  	HFiles            []string // .h/.hh/.hpp/.hxx源文件
  	FFiles            []string // .f/.F/.for/.f90的Fortran源文件
  	SFiles            []string // .s源文件
  	SwigFiles         []string // .swig文件
  	SwigCXXFiles      []string // .swigcxx文件
  	SysoFiles         []string // 添加到归档的.syso对象文件
  	TestGoFiles       []string // 包中的_test.go文件
  	XTestGoFiles      []string // 包外的_test.go文件
  	
  	// 嵌入文件
  	EmbedPatterns      []string // //go:embed模式
  	EmbedFiles         []string // 被EmbedPatterns匹配的文件
  	TestEmbedPatterns  []string // TestGoFiles中的//go:embed模式
  	TestEmbedFiles     []string // 被TestEmbedPatterns匹配的文件
  	XTestEmbedPatterns []string // XTestGoFiles中的//go:embed模式
  	XTestEmbedFiles    []string // 被XTestEmbedPatterns匹配的文件
  	
  	// Cgo指令
  	CgoCFLAGS    []string // cgo：给C编译器的标志
  	CgoCPPFLAGS  []string // cgo：给C预编译器的标志
  	CgoCXXFLAGS  []string // cgo：给C++编译器的标志
  	CgoFFLAGS    []string // cgo：给Fortran编译器的标志
  	CgoLDFLAGS   []string // cgo：给链接器的标志
  	CgoPkgConfig []string // cgo：pkg-config名字
  	
  	// 依赖信息
  	Imports      []string          // 本包使用的导入路径
  	ImportMap    map[string]string // 原始导入路径到ImportPath的映射（标识入口信息被省略）
  	Deps         []string          // 所有（递归的）导入依赖
  	TestImports  []string          // TestGoFiles使用的导入依赖
  	XTestImports []string          // XTestGoFiles使用的导入依赖
  	
  	// 错误信息
  	Incomplete bool            // 本包或依赖包是否有错误
  	Error      *PackageError   // 加载本包的错误
  	DepsErrors []*PackageError // 加载依赖包的错误
  }
  

  vendor目录中的包报告的ImportPath包括vendor目录自身的路径（例如，“d/vendor/p”而不是“p”），以便ImportPath唯一地标识一个给定包的副本。Imports、Deps、TestImports、和XTestImports列表同样包含这种扩展的导入路径。更多关于使用vendor的信息参阅golang.org/s/go15vendor。

  错误信息，如果有的话，为：

  type PackageError struct {
  	ImportStack   []string // 从命令行指定的包名到此的最短路径
  	Pos           string   // 错误的位置（如果有的话为，文件名:行号:列号）
  	Err           string   // 错误自身
  }
  

  模块信息为一个Module结构体，其定义在下文的-m讨论中。

  模板函数“join”调用strings.Join。

  模板函数“context”返回构建的上下文，定义如下：

  type Context struct {
  	GOARCH        string   // 目标体系结构
  	GOOS          string   // 目标操作系统
  	GOROOT        string   // GOROOT
  	GOPATH        string   // GOPATH
  	CgoEnabled    bool     // cgo是否可用
  	UseAllFiles   bool     // 是否使用所有文件，从而忽略使用+build指定行和文件名
  	Compiler      string   // 在计算目标路径时假定的编译器
  	BuildTags     []string // 构建约束，用以匹配+build指定的行
  	ToolTags      []string // 工具链特定的构建约束
  	ReleaseTags   []string // 与当前发布版本兼容的发布版本
  	InstallSuffix string   // 安装目录名字中使用的后缀
  }
  

  关于这些字段含义的更多信息，参阅go/build包的Context类型的文档。

  Dir、Target、Shlib、Root、ConflictDir和Export中的文件路径均为绝对路径。

  默认情况下，GoFiles、CgoFiles等列表中的名字为Dir目录中的文件（亦即，相对于Dir的路径，而不是绝对路径）。当使用-compiled和-test标志时添加的生成文件为指向生成的Go源代码的缓存副本的绝对路径。即使它们为Go源文件，路径可能不是以“.go”结尾。

• -find：找出指定名字的包但不解析它们的依赖：Imports和Deps列表将会为空。

• -json：包数据以JSON格式打印，而不是使用template包的格式。

• -m：列出模块而不是包。

  当列出模块时，-f标志仍然指定一个应用于Go结构体的格式模板，但现在为一个Module结构体：

  type Module struct {
  	Path      string       // 模块路径
  	Version   string       // 模块版本
  	Versions  []string     // 可获得的模块版本（当使用-versions时）
  	Replace   *Module      // 被此模块替代
  	Time      *time.Time   // 版本创建的时间
  	Update    *Module      // 可获得的更新，如果有的话（当使用-u时）
  	Main      bool         // 是否为主模块？
  	Indirect  bool         // 该模块是否只为主模块的间接依赖？
  	Dir       string       // 该模块保存文件的目录，如果有的话
  	GoMod     string       // 该模块go.mod文件的路径，如果有的话
  	GoVersion string       // 模块中使用的go版本
  	Retracted string       // 撤回信息，如果有的话（当使用-retracted或-u时）
  	Error     *ModuleError // 加载模块时的错误
  }
  
  type ModuleError struct {
  	Err string // 错误自身
  }
  

  如果模块在模块缓存中或如果-modfile标志被使用，GoMod指向的文件可能在模块目录之外。

  默认的输出是打印模块路径，然后是关于版本和替代的信息，如果有的话。例如，“go list -m all”可能打印：

  my/main/module
  golang.org/x/text v0.3.0 => /tmp/text
  rsc.io/pdf v0.1.1
  

  Module结构体有一个String方法，用以格式化输出的这一行，因此默认格式等同于-f \'{{.String}}\'。

  注意，当模块被替代，其Replace字段描述替代的模块，其Dir字段设置为替代模块的源代码的目录，如果有的话。（也就是说，如果Replace不为nil，那么Dir设置为Replace.Dir，无法访问被替代的源代码。）

  list -m的参数会被解析为模块的列表，而不是包的列表。主模块是包含当前目录的模块。活跃的（active）模块为主模块及其依赖。不带参数，list -m显示主模块。带参数，list -m显示参数指定的模块。任何活跃的模块都可以通过其模块路径指定。特殊的模式“all”指定所有活跃的模块，首先是主模块，然后是使用模块路径排序的依赖。包含“...”的模式指定其模块路径匹配该模式的活跃模块。path@version形式的查询指定该查询的结果，不限于活跃的模块。关于模块查询的更多信息，参阅“go help modules”。

  模板函数“module”使用单个字符串参数，必须为模块路径或查询，并以Module结构体的形式返回指定的模块。如果发生错误，结果将是带有非nil的Error字段的Module结构体。

• -retracted：报告关于被撤回的模块版本的信息。当-retracted与-f或-json一起使用，Retracted字段将被设置为一个字符串用以解释为什么版本被撤回。该字符串从模块的go.mod文件中的retract指令的注释中提取。当-retracted和-versions一起使用时，被撤回的版本和未被撤回的版本一起列出。-retracted标志可与或者不与-m一起使用。

• -test：不只是报告指定名字的包，也报告它们的测试二进制文件（对带有测试的包），从而将测试二进制文件是怎样构建的准确地传递给源代码分析工具。测试二进制文件的报告的导入路径为包的导入路径添加“.test”后缀，如“math/rand.test”。当构建测试时，有时候需要重新构建测试特定的某些依赖（最常见的是被测试的包本身）。为特定的测试二进制文件重新编译的包的报告的导入路径，会添加一个空格和以括号括起的测试二进制文件的名字，如“math/rand [math/rand.test]”或“regexp [sort.test]”。ForTest也会设置为正在被测试的包名（在此前的例子中为“math/rand”或“sort”）。

• -u：添加关于可用升级的信息。当给定模块的最后版本比当前模块较新时，-u设置Module的Update字段为关于较新模块的信息。如果当前版本被撤回，-u也会设置Module的Retracted字段。通过在当前版本后面格式化以括号括起的较新版本，Module的String方法表示一个可获得的升级。如果版本被撤回，其后跟字符串“(retracted)”。例如，“go list -m -u all”可能打印：

  my/main/module
  golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
  rsc.io/pdf v0.1.1 (retracted) [v0.1.2]
  

  （对工具来说，“go list -m -u -json all”可能更便于解析。）

• -versions：设置Module的Versions字段为该模块的所有已知版本的列表，根据语义版本进行排序，从最早至最后。该标志也会改变默认的输出格式来显示模块路径，其后接着以空格分隔的版本列表。

关于构建标志的更多信息，参阅“go help build”。

关于指定包的更多信息，参阅“go help packages”。

关于模块的更多信息，参阅https://golang.org/ref/mod。

go mod——模块维护

go mod <command> [arguments]

command可为以下命令：

• download：下载模块至本地缓存中。
• edit：通过工具或脚本编辑go.mod。
• graph：打印模块依赖图。
• init：在当前目录初始化新模块。
• tidy：添加缺少的模块并删除未使用的模块。
• vendor：生成依赖的vendor副本。
• verify：验证依赖有预期的内容。
• why：解释为什么需要该包或模块。

go mod提供对模块操作的访问。

注意对模块的支持内置于所有go命令，不只是“go mod”。例如，依赖的日常添加、删除、升级、降级应该使用“go get”来完成。关于模块功能的概述，参阅“go help modules”。

关于命令的更多信息，参阅“go help mod ”。

go mod download——下载模块至本地缓存中

go mod download [-x] [-json] [modules]

download下载指定名字的模块，可为选择主模块依赖的模块匹配模式，或path@version形式的模块查询。不带参数，download应用于主模块的所有依赖。

go命令将在常规执行期间根据需要自动下载模块。“go mod download”命令主要用于预填充本地缓存或计算Go模块代理的结果。

默认情况下，download不向标准输出写入内容。其可能打印进度信息和错误至标准错误输出。

标志：

• -json：打印一系列JSON对象至标准输出，描述每个下载的模块（或失败），相当于该Go结构体：

  type Module struct {
  	Path     string // 模块路径
  	Version  string // 模块版本
  	Error    string // 加载模块时的错误
  	Info     string // 缓存的.info文件绝对路径
  	GoMod    string // 缓存的.mod文件绝对路径
  	Zip      string // 缓存的.zip文件绝对路径
  	Dir      string // 缓存的源文件根目录绝对路径
  	Sum      string // 路径、版本的校验和（如go.sum中所示）
  	GoModSum string // go.mod的校验和（如go.sum中所示）
  }
  

• -x：打印实际需执行的命令，并运行。

关于“go mod download”的更多信息，参阅https://golang.org/ref/mod#go-mod-download。

关于版本查询的更多信息，参阅https://golang.org/ref/mod#version-queries。

go mod edit——通过工具或脚本编辑go.mod

go mod edit [editing flags] [-fmt|-print|-json] [go.mod]

edit提供一个编辑go.mod的命令行接口，主要提供给工具或脚本使用。它只读取go.mod；不查找涉及模块的信息。默认情况下，edit读写主模块的go.mod文件，但也可以在标志后指定不同的目标文件。

标志：

• -dropexclude=path@version：删除给定模块路径和版本的排除。

• -dropreplace=old[@v]：删除给定模块路径和版本的替代。如果@v省略，删除该模块不带版本的替代。

• -droprequire=path：删除给定的模块路径依赖的模块。该标志主要提供给工具用以理解模块图。用户应该使用“go get path@none”，可令其它go.mod根据需要调整来满足其它模块施加的限制。

• -dropretract=version：删除对给定版本的撤回。version可能是类似“v1.2.3”的单个版本或类似“[v1.1.0,v1.1.9]”的闭区间。

• -exclude=path@version：添加给定模块路径和版本的排除。注意如果排除已经存在-exclude=path@version是无操作的。

• -fmt：重新格式化go.mod文件，不作其他改变。使用或重写go.mod文件的任何其他修改也意味着这种重新格式化。需要该标志的唯一情形是没有指定其它标志，如“go mod edit -fmt”。

• -go=version：设置期望的Go语言版本。

• -json：以JSON格式打印最终的go.mod，而不是将其写回go.mod。JSON输出对应于这些Go类型：

  type Module struct {
  	Path    string
  	Version string
  }
  
  type GoMod struct {
  	Module  ModPath
  	Go      string
  	Require []Require
  	Exclude []Module
  	Replace []Replace
  	Retract []Retract
  }
  
  type ModPath struct {
  	Path       string
  	Deprecated string
  }
  
  type Require struct {
  	Path string
  	Version string
  	Indirect bool
  }
  
  type Replace struct {
  	Old Module
  	New Module
  }
  
  type Retract struct {
  	Low       string
  	High      string
  	Rationale string
  }
  

  表示单个版本（不是一个区间）的Retract条目将有设置为相同值的“Low”和“High”字段。

• -module：修改模块路径（go.mod文件的模块行）。

• -print：以其文本格式打印最终的go.mod，而不是将其写回go.mod。

• -replace=old[@v]=new[@v]：添加给定模块路径和版本对的替代。如果old@v中的@v省略，则左侧不带版本的替代将被添加，应用于old模块路径的所有版本。如果new@v中的@v省略，新路径应为本地模块根目录，而不是模块路径。注意-replace覆盖old[@v]任何冗余的替代，因此省略@v将删除对特定版本的现有替代。

• -require=path@version：添加给定的模块路径和版本依赖的模块。注意-require覆盖该路径任何已存在的依赖的模块。该标志主要提供给工具用以理解模块图。用户应该使用“go get path@version”，其可令其它go.mod根据需要调整来满足其它模块施加的限制。

• -retract=version：添加对给定版本的撤回。version可能是类似“v1.2.3”的单个版本或类似“[v1.1.0,v1.1.9]”的闭区间。注意如果撤回已经存在-retract=version是无操作的。

-require、-droprequire、-exclude、-dropexclude、-replace、-dropreplace、-retract、-dropretract编辑标志可以重复，根据给定的顺序应用修改。

注意这只描述go.mod文件自身，不描述其他间接引用的模块。对于构建可使用的的模块的完整集合，使用“go list -m -json all”。

关于“go mod edit”的更多信息参阅https://golang.org/ref/mod#go-mod-edit。

go mod graph——打印模块依赖图

go mod graph [-go=version]

以文本形式打印模块依赖图（已应用替代）。输出的每行有两个空格分隔的字段：模块和其依赖中的一个。每个模块都被标记为path@version形式的字符串，除了主模块，因其没有@version后缀。

标志：

• -go：令其报告如同被指定的Go版本加载的模块图，而不是被在go.mod文件中的“go”指令标示的版本。

关于“go mod graph”的更多信息参阅https://golang.org/ref/mod#go-mod-graph。

go mod init——在当前目录初始化新模块

go mod init [module-path]

初始化并写入一个新的go.mod文件至当前目录中，实际上是创建一个以当前目录为根的新模块。文件go.mod必须不存在。

接受一个可选参数，即新模块的模块路径。如果模块路径参数省略，将使用.go文件中的import注释、vendoring工具配置文件（类似Gopkg.lock）和当前目录（如果在GOPATH中）尝试推断模块路径。

如果vendoring工具配置文件存在，将尝试从其导入模块依赖。

关于“go mod init”的更多信息参阅https://golang.org/ref/mod#go-mod-init。

go mod tidy——添加缺少的模块并删除未使用的模块

go mod tidy [-e] [-v] [-go=version] [-compat=version]

确保go.mod与模块中的源代码一致。它添加构建当前模块的包和依赖所必须的任何缺少的模块，删除不提供任何有价值的包的未使用的模块。它也会添加任何缺少的条目至go.mod并删除任何不需要的条目。

标志：

• -compat：保留被指明的主Go发布版本的“go”命令所需的任何额外的校验和，用以成功加载模块图，并且如果“go”命令的该版本会从不同的模块版本加载任何导入的包，则令tidy出错。默认情况下，tidy如同-compat标志被设置为被go.mod文件中的“go”指令指示的版本之前的版本一样运作。
• -e：即使有加载包时遇到的错误仍尝试继续。
• -go：更新go.mod文件中的“go”指令为给定的版本，其可能改变go.mod文件中哪些模块依赖被保留为显式的要求。（Go版本1.17及更高版本保留更多的要求以为了支持延迟模块加载。）
• -v：打印被删除的模块的信息至标准错误输出。

关于“go mod tidy”的更多信息参阅https://golang.org/ref/mod#go-mod-tidy。

go mod vendor——生成依赖的vendor副本

go mod vendor [-e] [-v]

重置主模块的vendor目录，使其包含构建和测试所有主模块的包所需要的所有包。不包括vendor中的包的测试代码。

• -e：即使有加载包时遇到的错误仍尝试继续。
• -v：打印vendor的模块和包的名字至标准错误输出。

关于“go mod vendor”的更多信息参阅https://golang.org/ref/mod#go-mod-vendor。

go mod verify——验证依赖有预期的内容

go mod verify

检查存储在本地下载源代码缓存中的当前模块的依赖，是否自从下载之后未被修改。如果所有模块都未被修改，打印“all modules verified”。否则报告哪个模块已经被修改并令“go mod”以非0状态退出。

关于“go mod verify”的更多信息参阅https://golang.org/ref/mod#go-mod-verify。

go mod why——解释为什么需要该包或模块

go mod why [-m] [-vendor] packages...

标志：

• -m：默认情况下，why在导入图中展示从主模块到每个列出的包的最短路径。如果给出-m标志，why将参数视为一个模块的列表并找出每个模块中的所有包的路径。
• -vendor：默认情况下，why查询与“go list all”匹配的包图，包括对可达包的测试相关的包。-vendor标志令why将依赖包的测试相关的包排除在外。

输出是一系列的小节，和命令行中每个包或模块的名字一一对应，以空行分隔。每个小节以注释行“# package”或“# module”开头，给出目标包或模块。随后的行通过导入图给出路径，一个包一行。如果包或模块没有被主模块引用，该小节将显示单独一个带圆括号的提示信息来表明该事实。

例如：

$ go mod why golang.org/x/text/language golang.org/x/text/encoding
# golang.org/x/text/language
rsc.io/quote
rsc.io/sampler
golang.org/x/text/language

# golang.org/x/text/encoding
(main module does not need package golang.org/x/text/encoding)
$

关于“go mod why”的更多信息参阅https://golang.org/ref/mod#go-mod-why。

go run——编译并运行Go程序

go run [build flags] [-exec xprog] package [arguments...]

编译并运行指定名字的main Go包。通常包是作为一个单独的目录中的.go源文件列表指定的，但也可以是导入路径、文件系统路径、或匹配单独的已知包的模式，例如“go run .”或“go run my/cmd”。

如果package参数有版本后缀（如@latest或@v1.0.0），“go run”以模块感知模式构建程序，忽略在当前目录或任何父目录的go.mod文件，如果有的话。这在运行程序而不影响主模块的依赖时有用。

如果package参数没有版本后缀，“go run”可能以模块感知模式或GOPATH模式运行，取决于GO111MODULE环境变量和go.mod文件的存在。详细信息参阅“go help modules”。如果模块感知模式启用，“go run”运行在主模块的上下文中。

标志：

• -exec：默认情况下，“go run”直接运行编译的二进制文件：“a.out arguments...”。如果给定-exec标志，“go run”使用xprog调用二进制文件：“xprog a.out arguments...”。

  如果-exec标志未给定，GOOS或GOARCH与系统默认值不同，一个名字为go_$GOOS_$GOARCH_exec的程序可在当前查找目录下找到，“go run”使用该程序调用二进制文件，如“go_nacl_386_exec a.out arguments...”。当模拟器或其他执行方法可用时，这允许交叉编译的程序执行。

run的退出状态不是编译的二进制文件的退出状态。

关于构建标志的更多信息，参阅“go help build”。关于指定包的更多信息，参阅“go help packages”。

参阅：go build。

go test——测试包

go test [build/test flags] [packages] [build/test flags & test binary flags]

“go test”自动测试以导入路径命名的包。它以如下格式打印测试结果概要：

ok   archive/tar   0.011s
FAIL archive/zip   0.022s
ok   compress/gzip 0.033s
...

每个失败的包后跟随详细的输出。

“go test”将与名字匹配文件模式“*test.go”的任何文件一起，重新编译每个包。这些附加的文件可以包含test函数、benchmark函数、example函数。更多信息参阅“go help testfunc”。每个列出的包都会令到执行单独的测试二进制文件。以“”（包括“_test.go”）或“.”开头的文件会被忽略。

带后缀“_test”声明的包的测试文件将被编译为单独的包，然后与main包的测试二进制文件链接并运行。

go tool将忽略名字为“testdata”的目录，令其可以持有被测试所需的辅助数据。

作为构建测试二进制文件的一部分，go test在包及其测试源文件上运行go vet来发现显而易见的问题。如果go vet发现任何问题，go test报告它们且不运行测试二进制文件。只使用默认的go vet检查的高可信的子集。该子集是：“atomic”、“bool”、“buildtags”、“nilfunc”和“printf”。你可以通过“go doc cmd/vet”查看这些及其它vet测试的文档。要禁止运行go vet，使用-vet=off标志（参阅 testflag主题——测试标志 小节）。

所有的测试输出和概要行都打印至go命令的标准输出，即使test打印它们至它自己的标准错误输出。（go命令的标准错误输出被保留为打印构建测试的错误。）

go test以两种不同的模式运行：

第一种，称为本地目录模式，发生在当go test不使用包参数调用时（例如，“go test”或“go test -v