工作區信任擴充功能指南
什麼是工作區信任？
工作區信任是一項功能，旨在解決使用者在 VS Code 中開啟工作區時，因非預期程式碼執行而產生的安全性風險。例如，假設語言擴充功能為了提供功能，可能會執行來自目前載入工作區的程式碼。在這種情況下，使用者應該信任工作區的內容不是惡意的。「工作區信任」將此決策集中在 VS Code 內，並支援受限模式，以防止自動程式碼執行，讓擴充功能作者不必自行處理此基礎架構。VS Code 提供靜態宣告和 API 支援，以便快速導入擴充功能，而無需跨擴充功能複製程式碼。
導入
靜態宣告
在您的擴充功能的 package.json 中，VS Code 支援以下新的 capabilities 屬性 untrustedWorkspaces
capabilities:
untrustedWorkspaces:
{ supported: true } |
{ supported: false, description: string } |
{ supported: 'limited', description: string, restrictedConfigurations?: string[] }
對於 supported 屬性，接受以下值
true- 此擴充功能在受限模式下完全支援，因為它不需要工作區信任即可執行任何功能。它將會像以前一樣啟用。false- 此擴充功能在受限模式下不受支援，因為沒有工作區信任就無法運作。在授予工作區信任之前，它將保持停用狀態。'limited'- 擴充功能的某些功能在受限模式下受到支援。在授予工作區信任之前，應停用信任敏感功能。擴充功能可以使用 VS Code API 來隱藏或停用這些功能。工作區設定可以使用restrictedConfigurations屬性自動依信任閘控。
對於 description 屬性，必須提供信任需求的描述，以幫助使用者瞭解哪些功能將被停用，或在授予或拒絕工作區信任之前應審查哪些內容。如果 supported 設定為 true，則此屬性會被忽略。
description 屬性的值應新增至 package.nls.json，然後在 package.json 檔案中參考，以支援本地化。
restrictedConfigurations 屬性接受組態設定 ID 的陣列。對於列出的設定，當在不受信任工作區的受限模式下時，擴充功能將不會獲得工作區定義的值。
如何支援受限模式？
為了幫助擴充功能作者瞭解工作區信任的範圍以及哪些類型功能在受限模式下是安全的，以下列出一些問題供您考量。
我的擴充功能是否有主要進入點？
如果擴充功能沒有 main 進入點（例如佈景主題和語言語法），則擴充功能不需要工作區信任。對於此類擴充功能，擴充功能作者無需採取任何動作，因為無論工作區是否受信任，它們都將繼續獨立運作。
我的擴充功能是否依賴已開啟工作區中的檔案來提供功能？
這可能意味著可以由工作區設定的設定，或工作區中的實際程式碼。如果擴充功能從未使用工作區的任何內容，則可能不需要信任。否則，請查看其他問題。
我的擴充功能是否將工作區的任何內容視為程式碼？
最常見的例子是使用專案的工作區相依性，例如儲存在本機工作區中的 Node.js 模組。惡意工作區可能會簽入模組的受損版本。因此，這對使用者和擴充功能來說都是安全風險。此外，擴充功能可能依賴 JavaScript 或其他組態檔來控制擴充功能或其他模組的行為。還有許多其他範例，例如執行開啟的程式碼檔案以判斷其輸出以進行錯誤報告。
我的擴充功能是否使用可於工作區中定義、決定程式碼執行的設定？
您的擴充功能可能會使用設定值作為擴充功能執行的 CLI 旗標。如果這些設定被惡意工作區覆寫，則它們可能會被用作針對您擴充功能的攻擊媒介。另一方面，如果設定的值僅用於偵測特定條件，則可能不是安全風險，並且不需要工作區信任。例如，擴充功能可能會檢查慣用 Shell 設定的值是 bash 還是 pwsh，以判斷要顯示哪些文件。下方的組態（設定）章節提供了有關設定的指南，以幫助您為擴充功能找到最佳組態。
這不是可能需要工作區信任的案例的完整列表。當我們審查更多擴充功能時，我們將更新此列表。在考慮工作區信任時，請使用此列表來思考您的擴充功能可能正在執行的類似行為。
如果我不對擴充功能進行變更會怎樣？
如上所述，未在其 package.json 中貢獻任何內容的擴充功能將被視為不支援工作區信任。當工作區處於受限模式時，它將被停用，並且使用者將收到通知，指出由於工作區信任，某些擴充功能無法運作。此措施是對使用者而言最注重安全性的方法。即使這是預設行為，但設定適當的值以表明作為擴充功能作者，您已努力保護使用者和您的擴充功能免受惡意工作區內容的侵害，仍然是最佳做法。
工作區信任 API
如上所述，使用 API 的第一步是將靜態宣告新增至您的 package.json。最簡單的導入方法是對 supported 屬性使用 false 值。再次強調，即使您什麼都不做，這也是預設行為，但這是一個很好的訊號，可以向使用者表明您已做出慎重的選擇。在這種情況下，您的擴充功能無需執行任何其他操作。在授予信任之前，它不會被啟動，然後您的擴充功能將知道它是在使用者同意的情況下執行的。但是，如果您的擴充功能僅需部分功能信任，則這可能不是最佳選擇。
對於希望依工作區信任閘控其功能的擴充功能，它們應對 supported 屬性使用 'limited' 值，而 VS Code 提供以下 API
export namespace workspace {
/**
* When true, the user has explicitly trusted the contents of the workspace.
*/
export const isTrusted: boolean;
/**
* Event that fires when the current workspace has been trusted.
*/
export const onDidGrantWorkspaceTrust: Event<void>;
}
使用 isTrusted 屬性來判斷目前的工作區是否受信任，並使用 onDidGrantWorkspaceTrust 事件來監聽何時授予工作區信任。您可以使用此 API 來封鎖特定的程式碼路徑，並在工作區受信任後執行任何必要的註冊。
VS Code 也公開了一個上下文金鑰 isWorkspaceTrusted，用於如下所述的 when 子句中。
貢獻點
命令、檢視或其他 UI
當使用者尚未信任工作區時，他們將在受限模式下運作，其功能有限，僅限於瀏覽程式碼。您在受限模式下停用的任何功能都應對使用者隱藏。這可以透過when 子句上下文和上下文金鑰 isWorkspaceTrusted 來完成。即使命令未在 UI 中呈現，仍然可以呼叫命令，因此您應根據擴充功能程式碼中上述 API 封鎖執行或不註冊命令。
組態（設定）
首先，您應該檢查您的設定，以判斷它們是否需要將信任納入考量。如上所述，工作區可能會為您的擴充功能使用的設定定義一個值，該值對使用而言是惡意的。如果您識別出易受攻擊的設定，則應對 supported 屬性使用 'limited'，並在 restrictedConfigurations 陣列中列出設定 ID。
當您將設定 ID 新增至 restrictedConfigurations 陣列時，VS Code 將僅在受限模式下傳回使用者定義的設定值。然後，您的擴充功能無需進行任何額外的程式碼變更即可處理設定。授予信任後，除了工作區信任事件之外，還會觸發組態變更事件。
偵錯擴充功能
VS Code 將防止在受限模式下進行偵錯。因此，偵錯擴充功能通常不需要要求信任，並且應為 supported 屬性選取 true。但是，如果您的擴充功能提供不屬於內建偵錯流程的其他功能、命令或設定，則應使用 'limited' 並遵循上述指南。
工作提供器
與偵錯類似，VS Code 會防止在受限模式下執行工作。如果您的擴充功能提供不屬於內建工作流程的其他功能、命令或設定，則應使用 'limited' 並遵循上述指南。否則，您可以指定 supported: true。
測試工作區信任
請參閱工作區信任使用者指南，以瞭解有關啟用和組態工作區信任的詳細資訊。