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 來提供和增強其服務質量並分析流量。 瞭解更多。