發佈延伸模組

當您製作出高品質的擴充功能後，可以將其發佈到 VS Code 擴充功能市集 (Marketplace)，讓其他人可以搜尋、下載並使用您的擴充功能。或者，您也可以將擴充功能封裝成可安裝的 VSIX 格式，並與其他使用者分享。

本主題涵蓋

• 使用 vsce，這是用於管理 VS Code 擴充功能的 CLI 工具
• 封裝、發佈及取消發佈擴充功能
• 註冊發佈者 (publisher)，這是發佈擴充功能的必要步驟

vsce

vsce 是「Visual Studio Code Extensions」的縮寫，是一個用於封裝、發佈及管理 VS Code 擴充功能的命令列工具。

安裝

請確保您已安裝 Node.js。然後執行：

npm install -g @vscode/vsce

使用方式

您可以使用 vsce 輕鬆地封裝與發佈您的擴充功能。

$ cd myExtension
$ vsce package
# myExtension.vsix generated
$ vsce publish
# <publisher id>.myExtension published to VS Code Marketplace

vsce 還可以搜尋、檢索中繼資料以及取消發佈擴充功能。如需所有可用 vsce 命令的參考，請執行 vsce --help。

發佈擴充功能

發佈工具會檢查下列限制：

• 在 package.json 中提供的圖示不得為 SVG。
• 在 package.json 中提供的徽章 (badges) 不得為 SVG，除非它們來自受信任的徽章提供者。
• README.md 和 CHANGELOG.md 中的影像 URL 必須解析為 https URL。
• README.md 和 CHANGELOG.md 中的影像不得為 SVG，除非它們來自受信任的徽章提供者。

Visual Studio Code 使用 Azure DevOps 作為其市集服務。這意味著擴充功能的驗證、託管與管理都是透過 Azure DevOps 提供的。

vsce 僅能使用 個人存取權杖 (Personal Access Tokens) 發佈擴充功能。您需要至少建立一個權杖才能發佈擴充功能。

取得個人存取權杖

您可以透過 Azure DevOps 入口網站建立個人存取權杖。若要建立個人存取權杖：

1. 如果您尚未擁有 Azure DevOps 組織，請依照建立組織文章中的步驟進行。

2. 前往 Azure DevOps 入口網站，並選擇您的組織。

3. 開啟設定檔圖片旁邊的「使用者設定」下拉式選單，並選擇個人存取權杖 (Personal access tokens)。

   

4. 在個人存取權杖頁面上，選擇新增權杖 (New Token)。

   

5. 在建立新個人存取權杖的視窗中，為權杖選擇以下詳細資訊：

   • 名稱 (Name)：您為權杖設定的任何名稱。
   • 組織 (Organization)：所有可存取的組織 (All accessible organizations)。
   • 到期日 (Expiration，選填)：設定權杖所需的到期日期。
   • 範圍 (Scopes)：自定義範圍 (Custom defined)。
     • 點擊範圍區段下方的顯示所有範圍 (Show all scopes) 連結。
     • 在範圍列表中，捲動至市集 (Marketplace) 並選取管理 (Manage) 範圍。

   

6. 點擊建立 (Create)。

   您將會看到剛建立的個人存取權杖。請將其複製到安全的位置，後續建立發佈者時將會需要它。

建立發佈者

發佈者 (publisher) 是一個可以將擴充功能發佈到 Visual Studio Code 市集的身分。每個擴充功能都需要在其 package.json 檔案中包含一個 publisher 識別碼。

若要建立發佈者：

1. 前往 Visual Studio 市集發佈者管理頁面。

2. 使用您在上一節中建立個人存取權杖時所用的同一個 Microsoft 帳戶登入。

3. 點擊左側窗格中的建立發佈者 (Create publisher)。

4. 在新頁面中，為新發佈者指定必要參數：識別碼與名稱（分別為 ID 與 Name 欄位）。

   • ID：您在市集中發佈者的唯一識別碼，將用於您的擴充功能網址中。ID 一旦建立便無法變更。
   • Name：您發佈者的唯一名稱，將會與您的擴充功能一起顯示在市集中。這可以是您的公司或品牌名稱。

   下方是 Python 擴充功能的發佈者識別碼與名稱範例。

   

5. 您可以選擇性填寫其餘欄位。

6. 點擊建立 (Create)。

7. 使用 vsce 驗證剛建立的發佈者。在終端機中執行以下命令，並在提示時輸入上一步建立的個人存取權杖：

   vsce login <publisher id>
   
   https://marketplace.visualstudio.com/manage/publishers/
   Personal Access Token for publisher '<publisher id>': ****************************************************
   
   The Personal Access Token verification succeeded for the publisher '<publisher id>'.
   

驗證完成後，即可開始發佈擴充功能。

發佈擴充功能

您可以透過兩種方式發佈擴充功能：

1. 自動方式：使用 vsce publish 命令。

   vsce publish
   

   如果您尚未透過上述 vsce login 命令提供個人存取權杖，vsce 將會要求您輸入。

2. 手動方式：使用 vsce package 將擴充功能封裝成可安裝的 VSIX 格式，然後上傳至 Visual Studio 市集發佈者管理頁面。

   

查看擴充功能安裝與評分

Visual Studio 市集發佈者管理頁面可讓您存取每個擴充功能的「取得趨勢 (Acquisition Trend)」、總取得次數，以及「評分與評論 (Ratings & Reviews)」。若要查看報告，請點擊擴充功能或選擇更多動作 (More Actions) > 報告 (Reports)。

自動遞增擴充功能版本

發佈擴充功能時，您可以指定要遞增的 SemVer 相容數字或版本 (major、minor 或 patch)，以自動遞增其版本號。例如，要將擴充功能版本從 1.0.0 更新為 1.1.0，您應指定：

vsce publish minor

或

vsce publish 1.1.0

這兩個命令都會先修改擴充功能 package.json 中的 version 屬性，然後以更新後的版本進行發佈。

取消發佈擴充功能

您可以透過 Visual Studio 市集發佈者管理頁面點擊更多動作 (More Actions) > 取消發佈 (Unpublish)，從市集中取消發佈擴充功能。

一旦取消發佈，擴充功能的可用性狀態會變更為未發佈 (Unpublished)，且無法再從市集與 Visual Studio Code 下載。

移除擴充功能

您可以透過兩種方式移除擴充功能：

1. 自動方式：使用 vsce 配合 unpublish 命令。

   vsce unpublish <publisher id>.<extension name>
   

2. 手動方式：從 Visual Studio 市集發佈者管理頁面點擊更多動作 (More Actions) > 移除 (Remove)。

   

在這兩種情況下，系統都會提示您輸入擴充功能名稱以確認移除。請注意，移除動作是不可逆的。

棄用擴充功能

您可以單純棄用某個擴充功能，或將其棄用並建議轉向另一個擴充功能或設定。棄用的擴充功能在使用者介面中會以帶刪除線且變暗的文字顯示。

每個棄用的擴充功能在擴充功能圖示的右下角都有一個黃色警告圖示（請參見上方的螢幕截圖）。將游標懸停在該擴充功能圖示上，您可以在此圖示旁看到棄用細節，判斷是否為：

• 該擴充功能已棄用，無任何替代方案

  

• 該擴充功能已棄用，建議改用其他擴充功能

  

• 該擴充功能已棄用，建議改用特定設定

  

VS Code 不會自動遷移或解除安裝已安裝的棄用擴充功能。如果棄用的擴充功能有替代擴充功能或設定，VS Code 會顯示遷移 (Migrate) 按鈕，協助您快速切換到指定的替代方案。

若要將您的擴充功能標記為已棄用，請在 Deprecated extensions 討論串中留言。

封裝擴充功能

如果您想進行以下操作，可以選擇封裝您的擴充功能：

• 在您的 VS Code 執行個體上進行測試。
• 在不發佈到市集的情況下進行散發。
• 私下與他人分享。

封裝意指建立一個包含您擴充功能的 .vsix 檔案。此檔案隨後可安裝於 VS Code 中。有些擴充功能會將 .vsix 檔案作為其 GitHub 發佈的一部分。

若要封裝擴充功能，請在您的擴充功能根目錄中執行以下命令：

vsce package

此命令會在您的擴充功能根目錄中建立一個 .vsix 檔案。例如：my-extension-0.0.1.vsix。

使用者若要在 VS Code 中安裝 .vsix 檔案：

• 從 VS Code 中的「擴充功能」檢視：

  1. 前往「擴充功能」檢視。
  2. 選取檢視與更多動作... (Views and More Actions...)。
  3. 選取從 VSIX 安裝... (Install from VSIX...)。

• 從命令列：

  # if you use VS Code
  code --install-extension my-extension-0.0.1.vsix
  
  # if you use VS Code Insiders
  code-insiders --install-extension my-extension-0.0.1.vsix
  

您的擴充功能資料夾

若要載入擴充功能，您需要將檔案複製到您的 VS Code 擴充功能資料夾 .vscode/extensions。根據您的作業系統，此資料夾的位置如下：

• Windows: %USERPROFILE%\.vscode\extensions
• macOS: ~/.vscode/extensions
• Linux: ~/.vscode/extensions

Visual Studio Code 相容性

編寫擴充功能時，您必須指定您的擴充功能與哪些 VS Code 版本相容。若要執行此動作，請使用 package.json 內的 engines.vscode 屬性：

{
  "engines": {
    "vscode": "^1.8.0"
  }
}

• 數值 1.8.0（不含脫字號）表示您的擴充功能僅與 VS Code 1.8.0 相容。
• 數值 ^1.8.0 表示您的擴充功能與 VS Code 1.8.0 及其後續版本（包含 1.8.1、1.9.0 等）相容。

您可以使用 engines.vscode 屬性，確保擴充功能僅安裝在包含您所依賴 API 的用戶端上。此機制適用於「穩定版 (Stable)」與「Insiders 版」發行版本。

例如，假設 VS Code 最新的穩定版本為 1.8.0。在開發 1.9.0 版本期間，引入了一個新的 API 並透過 1.9.0-insider 版本在 Insider 發行版中提供。如果您想發佈一個受益於此 API 的擴充功能版本，您應指明版本依賴關係為 ^1.9.0。如此一來，您的新擴充功能版本將僅在 VS Code >=1.9.0 上提供（即使用目前的 Insiders 發行版使用者）。使用 VS Code 穩定版的使用者將僅在穩定版達到 1.9.0 版本時才會收到更新。

進階用法

市集整合

您可以自訂擴充功能在 Visual Studio 市集中的顯示方式。請參閱 Go 擴充功能作為範例。

以下是一些讓您的擴充功能在市集中呈現出色效果的建議：

• 在擴充功能根目錄加入 README.md 檔案，內容即為您想要顯示在市集擴充功能頁面上的內容。

  注意

  如果您在 package.json 中有一個指向公開 GitHub 儲存庫的 repository 屬性，vsce 會自動偵測並據此調整相對連結（預設使用 main 分支）。您可以在執行 vsce package 或 vsce publish 時使用 --githubBranch 旗標來覆寫此設定。您也可以使用 --baseContentUrl 和 --baseImagesUrl 旗標設定連結與影像的基礎 URL。

• 在擴充功能根目錄加入 LICENSE 檔案，包含關於擴充功能授權的資訊。

• 在擴充功能根目錄加入 CHANGELOG.md 檔案，包含關於擴充功能變更歷史的資訊。

• 在擴充功能根目錄加入 SUPPORT.md 檔案，包含關於如何取得擴充功能支援的資訊。

• 透過 package.json 中的 galleryBanner.color 屬性指定十六進位數值，以設定市集頁面的橫幅背景顏色。

• 透過 package.json 中的 icon 屬性，指定一個相對路徑到至少 128x128px 的 PNG 檔案，以設定圖示。

更多資訊請參閱市集呈現建議 (Marketplace Presentation Tips)。

驗證發佈者

您可以透過驗證與您的品牌或身分相關聯的合格網域所有權，成為已驗證的發佈者 (verified publisher)。一旦您的發佈者身分通過驗證，市集將會在您的擴充功能詳細資訊中新增一個已驗證的徽章。

先決條件

若要成為已驗證發佈者，必須在 VS 市集上擁有一個或多個擴充功能至少 6 個月，且網域註冊時間也必須滿 6 個月以上。請在符合這些條件後再申請驗證。

若要驗證發佈者：

1. 前往 Visual Studio 市集發佈者管理頁面。

2. 在左側窗格中，選取或建立一個您希望驗證的發佈者。

3. 在主窗格中，選取詳細資訊 (Details) 索引標籤。

   

4. 在詳細資訊索引標籤中，於已驗證網域 (Verified domain) 區段輸入一個合格網域。

   

   注意：請注意在開始輸入後，詳細資訊索引標籤標題旁邊會出現一個星號 (*)。就像在 VS Code 中一樣，這表示您有未儲存的變更。也因此，驗證 (Verify) 按鈕目前是停用的。

5. 選取儲存 (Save)，然後選擇驗證 (Verify)。

   

   會出現一個對話視窗，提供關於如何將 TXT 記錄新增至您網域 DNS 設定的說明。

   

6. 依照說明將 TXT 記錄新增至您網域的 DNS 設定。

7. 在對話視窗中選取驗證 (Verify)，以驗證 TXT 記錄是否已成功新增。

   

   一旦您的 TXT 記錄經過驗證，市集團隊將會審核您的請求，並在 5 個工作天內通知您結果。驗證內容包含但不限於：網域、網站與擴充功能對過往實績的要求、內容資格、合法性、信任度與正向聲譽。

如果驗證通過，您將會在 Visual Studio 市集發佈者管理頁面中的發佈者名稱旁看到對應的徽章。

備註:

• 任何對發佈者顯示名稱的變更都將撤銷已驗證的徽章。
• 未來若違反使用條款 (Terms of Use) 或上述任何驗證規範，都將導致已驗證徽章被撤銷。

合格網域

合格網域需符合下列準則：

• 您必須能夠管理 DNS 設定並新增 TXT 記錄。
• 不得為子網域（例如 {subdomain}.github.io、{subdomain}.contoso.com 等）。
• 必須使用 HTTPS 通訊協定。
• 必須能夠對 HEAD 請求回應 HTTP 200 狀態碼。

擴充功能定價標籤

您可以選擇在擴充功能的市集頁面上顯示定價標籤，標註它是 Free（免費）或 Free Trial（免費試用）。

若要顯示定價標籤，請將 pricing 屬性新增至您的 package.json。例如：

{
  "pricing": "Free"
}

允許的值為：Free 和 Trial（區分大小寫）。若未指定 pricing 屬性，預設值為 Free。

擴充功能贊助

您可以啟用贊助選項，讓使用者能以實際行動支持您的工作。

若要顯示贊助連結，請將 sponsor 屬性新增至您的 package.json。例如：

"sponsor": {
  "url": "https://github.com/sponsors/nvaccess"
}

贊助連結將會出現在您擴充功能在市集的頁面上，以及 VS Code 擴充功能詳細資訊的標頭中。

我們希望這能讓使用者為所依賴的擴充功能提供資金，進而改善擴充功能的效能、可靠性與穩定性。

使用 .vscodeignore

您可以建立一個 .vscodeignore 檔案，防止某些檔案被包含在擴充功能的封裝中。此檔案是 glob 模式的集合，一行一個模式。例如：

**/*.ts
**/tsconfig.json
!file.ts

您應該忽略所有執行階段不需要的檔案。例如，如果您的擴充功能是以 TypeScript 編寫的，則應忽略所有 **/*.ts 檔案，如上方範例所示。

發佈前步驟 (Pre-publish step)

您可以在資訊清單檔案中加入發佈前步驟，該步驟將在每次封裝擴充功能時被呼叫。例如，您可能想在此階段呼叫 TypeScript 編譯器：

{
  "name": "uuid",
  "version": "0.0.1",
  "publisher": "someone",
  "engines": {
    "vscode": "0.10.x"
  },
  "scripts": {
    "vscode:prepublish": "tsc"
  }
}

預發佈擴充功能 (Pre-release extensions)

使用者可以在 VS Code 或 VS Code Insiders 中安裝擴充功能的預發佈版本，以便在正式發佈前定期取得最新的擴充功能版本。

若要發佈預發佈版本，請在 vsce package 或 vsce publish 命令中加入 --pre-release 旗標：

vsce package --pre-release
vsce publish --pre-release

我們僅支援 major.minor.patch 格式的版本號，不支援 semver 的預發佈標籤。預發佈版本與一般發行版本之間必須不同。也就是說，如果 1.2.3 是以預發佈版本上傳的，那麼下一個正式發行版本必須使用不同的版本號上傳，例如 1.2.4。未來將會支援完整的 semver。

VS Code 會自動將擴充功能更新至可用的最高版本，因此即使使用者選擇了預發佈版本，若市集上有版本號更高的正式擴充功能，使用者仍會被更新至正式版本。因此，我們建議發行版本使用 major.EVEN_NUMBER.patch（偶數號），預發佈版本使用 major.ODD_NUMBER.patch（奇數號）。例如：0.2.* 作為發行版本，0.3.* 作為預發佈版本。

如果擴充功能作者不希望預發佈使用者被更新至正式版本，建議在發佈正式版本前，始終遞增並發佈新的預發佈版本，確保預發佈版本始終保持在較高版本。請注意，雖然預發佈使用者若有更高版本的正式發行版時會被更新，但他們仍可繼續自動更新至未來版本號高於正式版本的預發佈版本。

預發佈擴充功能在 VS Code 1.63.0 版本後才開始支援，因此所有預發佈擴充功能都應將 package.json 中的 engines.vscode 值設定為 >= 1.63.0。

平台專屬擴充功能

您可以針對 VS Code 執行的每個平台（Windows、Linux、macOS）發佈擴充功能的 VSIX 封裝。我們將這類擴充功能稱為平台專屬 (platform-specific)。

從 1.61.0 版本開始，VS Code 會搜尋符合目前平台的擴充功能封裝。

如果您的擴充功能具有平台專屬的程式庫或依賴項，平台專屬擴充功能非常實用，因為您可以控制平台封裝中包含的確切二進位檔。一個常見的使用情境是使用原生 Node 模組 (native node modules)。

平台專屬擴充功能會作為包含平台專屬內容的獨立封裝發佈。您可以透過傳遞 --target 旗標來指定目標平台。如果您未傳遞此旗標，該封裝將作為所有未提供平台專屬封裝之平台的備用方案 (fallback)。

目前支援的平台為：win32-x64、win32-arm64、linux-x64、linux-arm64、linux-armhf、alpine-x64、alpine-arm64、darwin-x64、darwin-arm64 與 web。

如果您希望平台專屬擴充功能也能在瀏覽器中以網頁擴充功能 (web extension) 形式執行，發佈時必須指定 web 為目標平台。web 平台會參考 package.json 中的 browser 進入點。若要停用在 web 中不支援的擴充功能功能，我們建議使用 package.json 中的 when 子句，而不是為網頁平台發送獨立的 package.json 或移除 VSIX 中無法在網頁中運作的部分。

發佈

從 1.99.0 版本開始，vsce 支援 --target 參數，讓您在封裝與發佈 VSIX 時可以指定目標平台。

以下是您可以如何為 win32-x64 與 win32-arm64 平台發佈 VSIX：

vsce publish --target win32-x64 win32-arm64

或者，您也可以在封裝時使用 --target 旗標來建立平台專屬的 VSIX。例如，若要封裝一個 win32-x64 平台的 VSIX，然後發佈它：

vsce package --target win32-x64
vsce publish --packagePath PATH_TO_WIN32X64_VSIX

持續整合 (CI)

管理多個平台專屬的 VSIX 可能會變得難以負荷，因此我們建議使用持續整合 (CI) 工具自動化您擴充功能的建置流程。例如，您可以使用 GitHub Actions 來建置您的擴充功能。我們的 平台專屬擴充功能範例可作為學習起點：其 工作流程 (workflow) 實現了常見情境，即利用平台專屬擴充功能支援，在所有受支援的 VS Code 目標上散發原生 Node 模組作為依賴項。

後續步驟

• 擴充功能市集 - 深入瞭解 VS Code 的公開擴充功能市集。
• 測試擴充功能 - 將測試加入您的擴充功能專案，以確保高品質。
• 捆綁擴充功能 - 透過 webpack 捆綁您的擴充功能檔案，以改善載入時間。

常見問題

當我嘗試發佈擴充功能時，收到「您超過了允許的 30 個標籤限制 (You exceeded the number of allowed tags of 30)」的錯誤？

Visual Studio 市集不允許擴充功能封裝在 package.json 中包含超過 30 個 keywords。請將關鍵字/標籤數量限制在 30 個以內，以避免此錯誤。

當我嘗試發佈擴充功能時，收到 403 Forbidden（或 401 Unauthorized）錯誤？

建立 PAT（個人存取權杖）時容易犯的一個錯誤，是在「組織 (Organizations)」欄位下拉式選單中選擇了特定組織，而非所有可存取的組織 (All accessible organizations)。另一個可能的錯誤是權限範圍不正確 — 您必須將授權範圍設定為 Marketplace (Manage)，發佈才能運作。

我無法透過 vsce 工具取消發佈我的擴充功能？

您可能更改了您的擴充功能 ID 或發佈者 ID。您也可以直接透過 Visual Studio 市集發佈者管理頁面管理您的擴充功能。例如，進行更新或取消發佈。

為什麼 vsce 沒有保留檔案屬性？

請注意，當您從 Windows 建置與發佈擴充功能時，封裝中的所有檔案都會缺少 POSIX 檔案屬性，即執行權限 (executable bit)。某些 node_modules 依賴項依賴這些屬性才能正常運作。從 Linux 與 macOS 發佈則可如預期般運作。

我可以從持續整合 (CI) 建置中發佈嗎？

可以。請參閱持續整合主題中的自動化發佈 (Automated publishing)章節，瞭解如何設定 Azure DevOps、GitHub Actions 與 GitLab CI 自動將您的擴充功能發佈到市集。

當我嘗試發佈擴充功能時，收到「ERROR The extension 'name' already exists in the Marketplace」錯誤？

市集要求擴充功能名稱對於每個擴充功能必須是唯一的。如果市集中已經存在同名的擴充功能，您將會收到以下錯誤：

ERROR The extension 'name' already exists in the Marketplace.

相同的規則也適用於擴充功能的顯示名稱 (display name)。

支援哪些套件管理員？

您可以使用 npm 或 yarn v1 來管理擴充功能的依賴項。

我需要關於 VS 市集帳戶的協助，或在發佈擴充功能時需要支援？

您可以透過登入 管理發佈者與擴充功能 (Manage Publishers & Extensions)，並點擊右上角的「連絡 Microsoft」連結，與 VS 市集支援團隊取得聯繫。