Gopls:设置

本文档描述了 gopls 的配置设置。

Gopls 设置由一个 JSON 对象定义,其有效字段在下面进行描述。这些字段特定于 gopls,通用的 LSP 客户端对此一无所知。

不同的客户端在其用户界面中以各种方式呈现配置设置。例如,有些客户端要求用户编辑原始 JSON 对象,而另一些客户端则使用编辑器配置语言中的数据结构;还有一些客户端(如 VS Code)拥有图形化配置系统。请务必查阅您所用客户端的文档,了解如何表达配置设置。某些客户端还允许为每个工作区文件夹单独配置设置。

任何实验性或用于调试目的的设置都会被标记出来。

构建

buildFlags []string

buildFlags 是调用构建系统时传递给构建系统的标志集。它应用于查询,例如 `go list`,后者在发现文件时使用。最常见的用法是设置 `-tags`。

默认值:`[]`。

env map[string]string

env 将环境变量添加到 `gopls` 运行的外部命令中,其中最重要的是 `go list`。

默认值:`{}`。

directoryFilters []string

directoryFilters 可用于排除工作区中不需要的目录。默认情况下,所有目录都包含在内。过滤器是操作符,`+` 表示包含,`-` 表示排除,后面跟相对于工作区文件夹的路径前缀。它们按顺序评估,最后应用的过滤器决定路径是否包含在内。路径前缀可以为空,因此初始的 `-` 会排除所有内容。

DirectoryFilters 还支持 `**` 操作符来匹配零个或多个目录。

示例

在当前深度排除 node_modules:`-node_modules`

在任何深度排除 node_modules:`-**/node_modules`

仅包含 project_a:`-`(排除所有),`+project_a`

仅包含 project_a,但不包含其中的 node_modules:`-`,`+project_a`,`-project_a/node_modules`

默认值:`["-**/node_modules"]`。

templateExtensions []string

templateExtensions 指定被视为模板文件的文件名的扩展名。(扩展名是文件名中最后一个点之后的部分。)

默认值:`[]`。

memoryMode string

此设置是实验性的,可能会被删除。

已废弃,无效果

默认值:`""`。

expandWorkspaceToModule bool

此设置是实验性的,可能会被删除。

expandWorkspaceToModule 决定了在使用模块的工作区中,哪些包被视为“工作区包”。

工作区包会影响工作区范围内的操作的范围。特别是,gopls 会在每次击键后诊断所有被视为工作区一部分的包。因此,通过将“ExpandWorkspaceToModule”设置为 false,并打开一个嵌套的工作区目录,您可以减少 gopls 为保持工作区最新所需的工作量。

默认值:`true`。

standaloneTags []string

standaloneTags 指定一组构建约束,这些约束标识构成可执行文件主包的单个 Go 源文件。

用于独立主文件的常见示例是使用指令 `//go:build ignore` 的约定,以表示不打算包含在任何包中的文件,例如因为它们直接由开发人员使用 `go run` 调用。

Gopls 仅当文件包名为“main”且具有“//go:build tag”或“// +build tag”的精确形式的构建指令时,才认为它是独立主文件,其中 tag 必须在通过此设置配置的标签列表中。特别地,如果构建约束比简单的标签更复杂(例如复合约束 `//go:build tag && go1.18`),则该文件不被视为独立主文件。

此设置仅在 gopls 使用 Go 1.16 或更高版本构建时受支持。

默认值:`["ignore"]`。

workspaceFiles []string

workspaceFiles 配置一组匹配当前工作区逻辑构建定义文件的 glob 模式。对此处指定的任何 glob 模式匹配的文件的任何磁盘更改都将触发工作区的重新加载。

只有在具有自定义 GOPACKAGESDRIVER 的环境中才需要自定义此设置。

默认值:`[]`。

格式化

local string

local 等同于 `goimports -local` 标志,该标志将以该字符串开头的导入放在第三方包之后。它应该是需要单独分组的导入路径的前缀。

它在整理导入(在 LSP Organize Imports 请求期间)或插入新导入(例如,在自动补全期间)时使用;LSP Formatting 请求仅对现有导入进行排序。

默认值:`""`。

gofumpt bool

gofumpt 指示是否应运行 gofumpt 格式化。

默认值:`false`。

UI

codelenses map[enum]bool

codelenses 覆盖 gopls 的 Code Lenses 源的启用/禁用状态。

示例用法

"gopls": {
...
  "codelenses": {
    "generate": false,  // Don't show the `go generate` lens.
  }
...
}

默认值:`{"generate":true,"regenerate_cgo":true,"run_govulncheck":false,"tidy":true,"upgrade_dependency":true,"vendor":true}`。

semanticTokens bool

此设置是实验性的,可能会被删除。

semanticTokens 控制 LSP 服务器是否将语义令牌发送给客户端。

默认值:`false`。

noSemanticString bool

此设置是实验性的,可能会被删除。

noSemanticString 关闭语义令牌“string”的发送。

已弃用:请改用 SemanticTokenTypes[“string”] = false。请参阅 golang/vscode-go#3632

默认值:`false`。

noSemanticNumber bool

此设置是实验性的,可能会被删除。

noSemanticNumber 关闭语义令牌“number”的发送。

已弃用:请改用 SemanticTokenTypes[“number”] = false。请参阅 golang/vscode-go#3632。

默认值:`false`。

semanticTokenTypes map[string]bool

此设置是实验性的,可能会被删除。

semanticTokenTypes 配置语义令牌类型。通过将每个值设置为 false 来禁用类型。默认情况下,所有类型都已启用。

默认值:`{}`。

semanticTokenModifiers map[string]bool

此设置是实验性的,可能会被删除。

semanticTokenModifiers 配置语义令牌修饰符。通过将每个值设置为 false 来禁用修饰符。默认情况下,所有修饰符都已启用。

默认值:`{}`。

自动补全

usePlaceholders bool

placeholders 在自动补全响应中启用函数参数或结构字段的占位符。

默认值:`false`。

completionBudget time.Duration

此设置仅用于调试目的。

completionBudget 是自动补全请求的软延迟目标。大多数请求在几毫秒内完成,但在某些情况下,深度自动补全可能需要更长时间。随着我们消耗预算,我们会动态减小搜索范围,以确保及时返回结果。零表示无限。

默认值:`"100ms"`。

matcher enum

这是一个高级设置,大多数 `gopls` 用户不应进行配置。

matcher 设置在计算自动补全候选时使用的算法。

必须是以下之一:

  • "CaseInsensitive"
  • "CaseSensitive"
  • "Fuzzy"

默认值:`"Fuzzy"`。

experimentalPostfixCompletions bool

此设置是实验性的,可能会被删除。

experimentalPostfixCompletions 启用人工方法片段,例如“someSlice.sort!”。

默认值:`true`。

completeFunctionCalls bool

completeFunctionCalls 启用函数调用补全。

在补全语句时,或当函数返回类型与正在补全的表达式的预期类型匹配时,自动补全可能会建议调用表达式(即可能包含括号)。

默认值:`true`。

诊断

analyses map[string]bool

analyses 指定用户希望启用或禁用的分析。一个映射,其中包含应启用/禁用的分析通道的名称。gopls 使用的分析器的完整列表可以在 analyzers.md 中找到。

示例用法

...
"analyses": {
  "unreachable": false, // Disable the unreachable analyzer.
  "unusedvariable": true  // Enable the unusedvariable analyzer.
}
...

默认值:`{}`。

staticcheck bool

此设置是实验性的,可能会被删除。

staticcheck 配置 staticcheck.io 的默认分析集。这些分析已记录在 Staticcheck 的网站 上。

“staticcheck”选项有三个值:

  • false:禁用所有 staticcheck 分析器
  • true:启用所有 staticcheck 分析器
  • unset:启用 gopls 维护者为运行时效率和分析精度选择的 staticcheck 分析器子集。

无论此设置如何,都可以使用 `analyses` 设置选择性地启用或禁用单个分析器。

默认值:`false`。

staticcheckProvided bool

此设置是实验性的,可能会被删除。

默认值:`false`。

annotations map[enum]bool

annotations 指定各种编译器优化细节,这些细节将在启用“Toggle compiler optimization details”(`gopls.gc_details`)命令为包启用时作为诊断报告。

(一些用户在性能分析工作中只关心一种注释。更重要的是,在大型包中,注释的数量有时会压垮用户界面并超出每个文件的诊断限制。)

TODO(adonovan): 将此字段重命名为 CompilerOptDetail。

每个枚举值必须是以下之一:

  • "bounds" 控制边界检查诊断。
  • "escape" 控制关于逃逸选择的诊断。
  • "inline" 控制关于内联选择的诊断。
  • "nil" 控制 nil 检查。

默认值:`{"bounds":true,"escape":true,"inline":true,"nil":true}`。

vulncheck enum

此设置是实验性的,可能会被删除。

vulncheck 启用漏洞扫描。

必须是以下之一:

  • "Imports":在 Imports 模式下,`gopls` 将报告受分析主模块直接和间接使用的包影响的漏洞。
  • "Off":禁用漏洞分析。

默认值:`"Off"`。

diagnosticsDelay time.Duration

这是一个高级设置,大多数 `gopls` 用户不应进行配置。

diagnosticsDelay 控制 gopls 在计算深度诊断之前等待最近一次文件修改后的时间。简单的诊断(解析和类型检查)始终立即对最近修改的包运行。

此选项必须设置为有效的持续时间字符串,例如 `“250ms”`。

默认值:`"1s"`。

diagnosticsTrigger enum

此设置是实验性的,可能会被删除。

diagnosticsTrigger 控制运行诊断的时间。

必须是以下之一:

  • "Edit":在文件编辑和保存时触发诊断。(默认)
  • "Save":仅在文件保存时触发诊断。初始工作区加载或配置更改等事件仍会触发诊断。

默认值:`"Edit"`。

analysisProgressReporting bool

analysisProgressReporting 控制 gopls 在构建其分析事实索引花费时间较长时是否发送进度通知。取消这些通知将取消索引任务,尽管它会在工作区的下一次更改后重新启动。

当第一次打开包并启用静态检查等重量级分析时,构建其所有依赖项的分析事实索引可能需要一些时间。索引缓存在文件系统中,因此后续分析应该更快。

默认值:`true`。

文档

hoverKind enum

hoverKind 控制悬停文本中显示的信息。SingleLine 仅供编辑器插件的作者使用。

必须是以下之一:

  • "FullDocumentation"
  • "NoDocumentation"
  • "SingleLine"
  • "Structured" 是一个错误的实验性设置,它返回 JSON 悬停格式。不应使用此设置,因为它将在 gopls 的未来版本中删除。
  • "SynopsisDocumentation"

默认值:`"FullDocumentation"`。

linkTarget string

linkTarget 是 Go 包文档链接的基本 URL,这些链接由 Hover 和 DocumentLinks 等 LSP 操作返回,并在每个 Diagnostic 的 CodeDescription 字段中返回。

它可以是以下之一:

  • "godoc.org"
  • "pkg.go.dev"

如果公司选择使用自己的 `godoc.org`,也可以使用其地址。

匹配 GOPRIVATE 环境变量的模块将不会在悬停中显示文档链接。

默认值:`"pkg.go.dev"`。

linksInHover enum

linksInHover 控制悬停 Markdown 中文档链接的存在。

必须是以下之一:

  • false:不显示链接
  • true:显示链接到 `linkTarget` 域
  • "gopls":显示链接到 gopls 的内部文档查看器

默认值:`true`。

内嵌提示

hints map[enum]bool

此设置是实验性的,可能会被删除。

hints 指定用户想要看到的内嵌提示。gopls 使用的提示的完整列表可以在 inlayHints.md 中找到。

默认值:`{}`。

importShortcut enum

importShortcut 指定导入语句是否应链接到文档或转到定义。

必须是以下之一:

  • "Both"
  • "Definition"
  • "Link"

默认值:`"Both"`。

symbolMatcher enum

这是一个高级设置,大多数 `gopls` 用户不应进行配置。

symbolMatcher 设置在查找工作区符号时使用的算法。

必须是以下之一:

  • "CaseInsensitive"
  • "CaseSensitive"
  • "FastFuzzy"
  • "Fuzzy"

默认值:`"FastFuzzy"`。

symbolStyle enum

这是一个高级设置,大多数 `gopls` 用户不应进行配置。

symbolStyle 控制符号在符号响应中的限定方式。

示例用法

"gopls": {
...
  "symbolStyle": "Dynamic",
...
}

必须是以下之一:

  • "Dynamic" 使用任何限定符可以为给定的符号查询产生最高得分的匹配。这里“限定符”是任何以“/”或“.”分隔的完整限定符号后缀。即,“to/pkg.Foo.Field”或仅“Foo.Field”。
  • "Full" 是完全限定的符号,即“path/to/pkg.Foo.Field”。
  • "Package" 是包限定的符号,即“pkg.Foo.Field”。

默认值:`"Dynamic"`。

symbolScope enum

symbolScope 控制在工作区/符号请求中搜索哪些包。当作用域为“workspace”时,gopls 仅搜索工作区包。当作用域为“all”时,gopls 搜索所有已加载的包,包括依赖项和标准库。

必须是以下之一:

  • "all" 匹配任何已加载包中的符号,包括依赖项。
  • "workspace" 仅匹配工作区包中的符号。

默认值:`"all"`。

verboseOutput bool

此设置仅用于调试目的。

verboseOutput 启用额外的调试日志记录。

默认值:`false`。


本文档的源代码可以在 golang.org/x/tools/gopls/doc 下找到。