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 下找到。

go.dev 使用 Google 的 cookie 来提供和增强其服务质量并分析流量。 了解更多。