編輯

發佈擴充功能

Name: Visual Studio Code
Author: Microsoft

一旦您製作出高品質的擴充功能，就可以將其發佈到 VS Code 擴充功能市集，讓其他人可以找到、下載和使用您的擴充功能。或者，您可以將擴充功能封裝成可安裝的 VSIX 格式，並與其他使用者分享。

本主題涵蓋

使用 vsce，管理 VS Code 擴充功能的 CLI 工具
封裝、發佈和取消發佈擴充功能
註冊發行者，發佈擴充功能所必需

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。

發佈擴充功能

注意

由於安全考量，vsce 將不會發佈包含使用者提供的 SVG 圖片的擴充功能。

發佈工具會檢查以下限制

package.json 中提供的圖示不得為 SVG。
package.json 中提供的徽章不得為 SVG，除非它們來自受信任的徽章提供者。
README.md 和 CHANGELOG.md 中的圖片 URL 需要解析為 https URL。
README.md 和 CHANGELOG.md 中的圖片不得為 SVG，除非它們來自受信任的徽章提供者。

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

vsce 只能使用個人存取權杖發佈擴充功能。您需要建立至少一個權杖才能發佈擴充功能。

取得個人存取權杖

首先，請按照文件建立您自己的組織在 Azure DevOps 中。在以下範例中，組織的名稱為 vscode，您應視情況使用您的新組織名稱。請注意，組織的名稱不一定要與您的發行者名稱相同。

從您組織的首頁 (例如：https://dev.azure.com/vscode)，開啟您個人資料圖片旁的「使用者設定」下拉式選單，然後選取個人存取權杖
在個人存取權杖頁面上，選取新增權杖
在「建立新的個人存取權杖」模式視窗中，為權杖選取以下詳細資料
- 名稱：您想要為權杖設定的任何名稱
- 組織：所有可存取的組織
- 到期日 (選用)：設定權杖的所需到期日
- 範圍：自訂定義
  - 按一下範圍區段下方的顯示所有範圍連結
  - 在範圍清單中，捲動至市集並選取管理範圍
按一下建立。

您將看到您新建立的個人存取權杖。複製它到安全的位置，您將需要它來建立發行者。

建立發行者

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

若要建立發行者

前往Visual Studio 市集發行者管理頁面。
使用您在上一節中用來建立個人存取權杖的相同 Microsoft 帳戶登入。
按一下左側窗格中的建立發行者。
在新頁面中，指定新發行者的必要參數 - 識別碼和名稱 (分別為 ID 和名稱欄位)
- ID：您的發行者在市集中的唯一識別碼，將用於您的擴充功能 URL 中。建立後 ID 無法變更。
- 名稱：您的發行者的唯一名稱，將與您的擴充功能一起顯示在市集中。這可以是您的公司或品牌名稱。
以下是 Docker 擴充功能的發行者識別碼和名稱範例
選擇性地填寫其餘欄位。
按一下建立

使用 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>'.

驗證完成後，您就可以發佈擴充功能了。

發佈擴充功能

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

自動，使用 vsce publish 命令
```
vsce publish
```
如果您尚未透過上述 vsce login 命令提供您的個人存取權杖，vsce 將會要求您提供。
手動，使用 vsce package 將擴充功能封裝成可安裝的 VSIX 格式，然後將其上傳到Visual Studio 市集發行者管理頁面

檢閱擴充功能安裝與評分

Visual Studio 市集發行者管理頁面讓您可以存取每個擴充功能隨時間的取得趨勢，以及總取得次數和評分與評論。若要查看報告，請按一下擴充功能或選擇更多動作 > 報告。

Marketplace extension report

自動遞增擴充功能版本

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

vsce publish minor

或

vsce publish 1.1.0

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

注意

如果您在 git 儲存庫中執行 vsce publish，它也會透過 npm-version 建立版本 commit 和標籤。預設的 commit 訊息將是擴充功能的版本，但您可以使用 -m 旗標提供自訂 commit 訊息。(目前的版本可以從 commit 訊息中使用 %s 參考)。

取消發佈擴充功能

您可以從Visual Studio 市集發行者管理頁面取消發佈擴充功能，方法是按一下更多動作 > 取消發佈

Unpublish the extension via the Marketplace management page

取消發佈後，擴充功能的「可用性」狀態會變更為 已取消發佈，並且將不再可從市集和 Visual Studio Code 下載

Unpublished extension

注意

當您取消發佈擴充功能時，市集會保留擴充功能統計資料。

移除擴充功能

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

自動，使用 vsce 的 unpublish 命令

vsce unpublish <publisher id>.<extension name>

手動，從Visual Studio 市集發行者管理頁面按一下更多動作 > 移除

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

注意

當您移除擴充功能時，市集也會移除所有擴充功能統計資料。您可能會想要取消發佈您的擴充功能，而不是移除它。

棄用擴充功能

您可以只棄用擴充功能，或棄用而改用另一個擴充功能或設定。棄用的擴充功能將在 UI 中以變暗的刪除線文字呈現

Rust extension shown as deprecated in extension search

每個棄用的擴充功能在其擴充功能磚的右下角都有一個黃色警告圖示 (請參閱上面的螢幕截圖)。當您將滑鼠游標停留在擴充功能磚上時，您可以在此圖示旁邊看到棄用詳細資訊，無論是

擴充功能已棄用，沒有任何替代方案
擴充功能已棄用，改用另一個擴充功能
擴充功能已棄用，改用設定

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

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

注意

目前，擴充功能在市集中不會呈現為已棄用。此功能將在稍後推出。

封裝擴充功能

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

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

封裝表示建立一個包含您的擴充功能的 .vsix 檔案。然後可以在 VS Code 中安裝此檔案。某些擴充功能會發佈 .vsix 檔案作為其 GitHub 發行版本的一部分。

若要封裝擴充功能，請在您的擴充功能根資料夾中執行以下命令

vsce package

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

對於使用者，若要在 VS Code 中安裝 .vsix 檔案

從 VS Code 中的「擴充功能」檢視
1. 前往「擴充功能」檢視。
2. 選取檢視和更多動作...
3. 選取從 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 的用戶端安裝。此機制適用於穩定版和 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 屬性，設定圖示為包含在您的擴充功能中的 128x128 像素 PNG 檔案的相對路徑。

請參閱市集呈現秘訣以取得更多資訊。

驗證發行者

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

先決條件

若要成為已驗證的發行者，發行者必須在 VS 市集中擁有一個或多個擴充功能至少 6 個月，並且網域的註冊時間也必須至少 6 個月。在申請驗證之前，請等到符合這些條件。

Verified publisher indicators in VS Code

若要驗證發行者

前往Visual Studio 市集發行者管理頁面。
在左側窗格中，選取或建立您想要驗證的發行者。
在主窗格中，選取詳細資料索引標籤。
在詳細資料索引標籤的已驗證網域區段下，輸入合格網域。

注意：在您開始輸入後，請注意詳細資料索引標籤標題旁邊的星號 (*)。就像在 VS Code 中一樣，這表示您有未儲存的變更。基於相同原因，驗證按鈕仍處於停用狀態。
選取儲存，然後選取驗證。

將會出現一個對話視窗，提供有關將 TXT 記錄新增至您的網域 DNS 組態的指示。
按照指示將 TXT 記錄新增至您的網域 DNS 組態。
在對話視窗中選取驗證，以驗證 TXT 記錄是否已成功新增。

一旦您的 TXT 記錄經過驗證，市集團隊將會審查您的請求，並在 5 個工作天內告知您結果。驗證包括但不限於：網域、網站和擴充功能追蹤記錄的先決條件、內容資格、合法性、信任和正面聲譽。

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

Verified publisher manage

注意事項:

對發行者顯示名稱的任何變更都將撤銷已驗證徽章。

發行者未來發生的任何使用條款或上述提及的驗證違規行為都將撤銷已驗證徽章。

合格網域

合格網域符合以下條件

您必須能夠管理 DNS 組態設定並新增 TXT 記錄。
它不是子網域 ({subdomain}.github.io、{subdomain}.contoso.com 或類似網域)。
它必須使用 HTTPS 通訊協定。
它必須能夠以 HTTP 200 狀態回應 HEAD 請求。

擴充功能定價標籤

您可以選擇在您的擴充功能市集頁面上顯示定價標籤，以指示它是 Free 或 Free Trial。

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

{
  "pricing": "Free"
}

允許的值為：Free 和 Trial (區分大小寫)。當未指定 pricing 屬性時，預設值為 Free。

注意

請確保在發佈您的擴充功能時使用 vsce 版本 >= 2.10.0，以便定價標籤能夠運作。

您可以選擇加入贊助，讓您的使用者可以支持您的工作。

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

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

注意

請確保在發佈您的擴充功能時使用 vsce 版本 >= 2.9.1，以便贊助能夠運作。

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

Sponsor link in extension details page

我們希望這能讓使用者資助他們所依賴的擴充功能，以改善擴充功能的效能、可靠性和穩定性。

使用 .vscodeignore

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

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

您應該忽略所有在執行階段不需要的檔案。例如，如果您的擴充功能是以 TypeScript 撰寫的，您應該忽略所有 **/*.ts 檔案，就像上面的範例一樣。

注意

devDependencies 中列出的開發相依性將會自動忽略，因此您不需要明確新增它們。

發佈前步驟

您可以在您的資訊清單檔案中新增發佈前步驟，每次封裝擴充功能時都會呼叫此步驟。例如，您可能想要在此階段調用 TypeScript 編譯器

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

預先發佈擴充功能

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

GitHub PR extension pre-release version in the extensions view

若要發佈預先發佈版本，請將 --pre-release 旗標傳遞給 vsce package 或 vsce publish 命令

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 團隊，以啟用自動解除安裝過時的獨立擴充功能並安裝主要擴充功能的預先發佈版本。

平台特定擴充功能

您可以針對 VS Code 運行的每個平台 (Windows、Linux、macOS) 發佈您的擴充功能 VSIX 套件。我們將此類擴充功能稱為 平台特定 擴充功能。

從版本 1.61.0 開始，VS Code 會尋找與目前平台相符的擴充功能套件。

如果您的擴充功能具有平台特定的程式庫或相依性，平台特定擴充功能非常有用，因此您可以控制平台套件中包含的確切二進位檔案。常見的用例是使用 原生節點模組。

平台特定擴充功能以包含平台特定內容的單獨套件發佈。您可以透過傳遞 --target 旗標來指定目標平台。如果您未傳遞此旗標，則該套件將用作所有沒有平台特定套件的平台的後備方案。

目前可用的平台為：win32-x64、win32-arm64、linux-x64、linux-arm64、linux-armhf、alpine-x64、alpine-arm64、darwin-x64、darwin-arm64 和 web。

如果您希望平台特定擴充功能也支援在瀏覽器中作為網頁擴充功能運行，則在發佈時必須以 web 平台為目標。web 平台尊重 package.json 中的 browser 進入點。若要停用 web 中不支援的擴充功能功能，我們建議在 package.json 中使用 when 子句，而不是為網頁平台運送單獨的 package.json 或移除 VSIX 中在 web 中無法運作的部分。

發佈

從版本 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

持續整合

管理多個平台特定的 VSIX 可能會變得難以負荷，因此我們建議使用持續整合 (CI) 工具自動化您的擴充功能建置流程。例如，您可以使用 GitHub Actions 來建置您的擴充功能。我們的平台特定擴充功能範例可以用作學習的起點：其 workflow 啟用了使用平台特定擴充功能支援來跨所有支援的 VS Code 目標分發原生節點模組作為相依性的常見情境。

後續步驟

擴充功能市集 - 深入了解 VS Code 的公用擴充功能市集。
測試擴充功能 - 將測試新增至您的擴充功能專案，以確保高品質。
捆綁擴充功能 - 透過使用 webpack 捆綁您的擴充功能檔案來改善載入時間。

常見問題

當我嘗試發佈我的擴充功能時，收到「您超過允許的標籤數量 10 個」錯誤？

Visual Studio 市集不允許擴充功能套件在 package.json 中擁有超過 10 個 keywords。將關鍵字/標籤數量保持在 10 個以下，以避免此錯誤。

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

建立 PAT (個人存取權杖) 時，一個容易犯的錯誤是在組織欄位下拉式選單中選取特定組織，而不是 所有可存取的組織。另一個可能的錯誤是不正確的範圍 - 您應將授權範圍設定為 Marketplace (管理)，發佈才能運作。

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

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

為什麼 vsce 不保留檔案屬性？

請注意，當從 Windows 建置和發佈您的擴充功能時，擴充功能套件中包含的所有檔案都將缺少 POSIX 檔案屬性，即執行位。某些 node_modules 相依性依賴這些屬性才能正常運作。從 Linux 和 macOS 發佈則如預期般運作。

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

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

當我嘗試發佈我的擴充功能時，收到「錯誤：擴充功能 'name' 已存在於市集中」錯誤？

市集要求每個擴充功能的擴充功能名稱都是唯一的。如果市集中已存在具有相同名稱的擴充功能，您將會收到以下錯誤

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

相同的規則適用於擴充功能的顯示名稱。

支援哪些套件管理器？

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

我需要 VS 市集帳戶方面的協助或發佈擴充功能的支援？

您可以前往管理發行者和擴充功能登入，然後點擊右上角的「Contact Microsoft」連結，即可聯絡 VS Marketplace 支援團隊。

04/03/2025

發佈擴充功能

vsce

安裝

用法

發佈擴充功能

取得個人存取權杖

建立發行者

發佈擴充功能

檢閱擴充功能安裝與評分

自動遞增擴充功能版本

取消發佈擴充功能

移除擴充功能

棄用擴充功能

封裝擴充功能

您的擴充功能資料夾

Visual Studio Code 相容性

進階用法

市集整合

驗證發行者

先決條件

合格網域

擴充功能定價標籤

擴充功能贊助者

使用 .vscodeignore

發佈前步驟

預先發佈擴充功能

平台特定擴充功能

發佈

持續整合

後續步驟

常見問題

當我嘗試發佈我的擴充功能時，收到「您超過允許的標籤數量 10 個」錯誤？

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

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

為什麼 vsce 不保留檔案屬性？

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

當我嘗試發佈我的擴充功能時，收到「錯誤：擴充功能 'name' 已存在於市集中」錯誤？

支援哪些套件管理器？

我需要 VS 市集帳戶方面的協助或發佈擴充功能的支援？

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