發布 VS Code 擴展的流程：以顏色主題為例

引言：您的 VS Code 擴展在市場中的旅程

Visual Studio Code (VS Code) 的強大擴展性是其廣受歡迎的核心原因之一，它允許開發者通過添加語言支持、調試器和各種開發工具來定制和增強其集成開發環境（IDE）體驗。Visual Studio Marketplace (Visual Studio 應用商店) 作為這些擴展的中心樞紐，為用戶提供了發現、安裝和管理擴展的便捷途徑。

該市場是一個充滿活力且不斷發展的生態系統，目前托管著超過 60,000 個擴展，總安裝量已達到驚人的 33 億次。然而，深入分析數據會發現一個顯著的差異：雖然每個擴展的平均安裝量約為 55,000 次，但中位數卻僅為 500 次。這表明少數極其流行的擴展占據了絕大部分的安裝量，而許多擴展在獲得顯著關注方面面臨挑戰。

那么，為何要發布您的自定義顏色主題呢？將您的自定義顏色主題發布到 Marketplace，提供了一個獨特的機會，讓您能夠與全球的開發者社區分享您的審美視角和設計偏好。這不僅能讓您的工作惠及他人，提升他們的編碼體驗，更重要的是，通過為這個廣泛使用的平臺做出貢獻，它能極大地豐富您的開發者個人作品集，展示您的技能和對細節的關注。一個設計精良且廣受歡迎的主題，還能提升您在開發者社區中的知名度，從而可能帶來新的合作機會、自由職業項目，甚至是全職開發職位。

需要認識到，盡管 Marketplace 擁有龐大的體量，但平均安裝量與中位數安裝量之間的巨大差異表明，它更多地扮演著一個“發現平臺”的角色，而非僅僅是擴展的存儲庫。這意味著，僅僅上傳一個擴展是不夠的；為了讓您的擴展脫穎而出并獲得廣泛采用，必須在可見性、展示和用戶參與度方面投入戰略性的努力。

階段 1：基本工具和初始設置

本階段概述了準備和發布您的 VS Code 擴展所需的關鍵軟件先決條件和命令行工具。

Node.js 和 npm：基礎

要發布 VS Code 擴展，系統必須安裝 Node.js 及其包管理器 npm。它們構成了您將使用的工具的核心運行時環境 4。

確保您的 Node.js 版本符合發布工具的要求至關重要。具體來說，vsce 工具目前要求 Node.js 版本為 20.18.1 或更高。未能滿足此要求可能會導致出現 EBADENGINE 警告，如果未能提前預見，這可能會成為一個令人沮喪的障礙 4。這種明確的警告揭示了 Node.js 版本與

vsce 功能之間的直接因果關系：Node.js 版本不兼容將直接導致 vsce 無法正常工作，進而阻礙發布流程。因此，預先強調這一要求對于避免潛在的調試困擾至關重要。

`vsce`：Visual Studio Code 擴展管理器

vsce (Visual Studio Code Extensions) 是 Microsoft 官方提供的命令行工具，用于簡化 VS Code 擴展的整個生命周期管理，包括打包、發布和維護。它作為一個 npm 包發布。

要全局安裝 vsce，請打開您的終端或命令提示符并運行：npm install -g @vscode/vsce。

vsce 作為一個專用 CLI 工具的存在，極大地簡化了發布工作流程，抽象了復雜的 API 交互。這種集中式工具方法也使 Microsoft 能夠直接在發布入口強制執行某些安全限制（例如，禁止 SVG 圖標，要求圖像使用 HTTPS 協議）。這是一項關鍵的安全措施，旨在保護 Marketplace 及其用戶免受惡意擴展的侵害。

平臺特定注意事項（Linux）：在 Linux 系統上，vsce 利用 keytar 來安全地存儲憑據。這通常需要安裝名為 libsecret 的系統庫。根據您的 Linux 發行版，您可能需要運行類似 sudo apt-get install libsecret-1-dev (Debian/Ubuntu)、apk add libsecret (Alpine)、sudo yum install libsecret-devel (Red Hat-based 系統) 或 sudo pacman -S libsecret (Arch Linux) 的命令。如果您希望避免使用 keytar 或遇到問題，可以通過設置 VSCE_STORE=file 環境變量來配置 vsce 使用基于文件的憑據存儲，或者直接通過 VSCE_PAT 環境變量提供您的個人訪問令牌 (PAT)。

keytar 和 libsecret 在 Linux 上的提及，突顯了即使是看似跨平臺的 Node.js 工具，也可能存在底層原生依賴。這意味著開發者應準備好進行細微的環境調整，尤其是在不同操作系統之間工作時，并且知道環境變量可以作為有效的替代方案。

Yeoman 和 `generator-code`：搭建擴展骨架（簡要介紹）

盡管您的主要目標是發布一個現有的顏色主題，但值得注意的是，yo (Yeoman) 和 generator-code 是 VS Code 推薦的用于從頭開始搭建新擴展項目的標準工具。它們提供了一個結構化的模板，如果您將來決定創建其他類型的擴展，這將特別有用。

您可以全局安裝它們：npm install -g yo generator-code。通常，您會在終端中運行

yo code，并從選項中選擇“New Color Theme”來生成一個基本的顏色主題項目結構。

階段 2：建立您的發布者身份

發布擴展需要建立一個與您的 Microsoft 賬戶通過 Azure DevOps 關聯的發布者身份。這是認證和管理的關鍵一步。

創建 Azure DevOps 組織：Marketplace 服務的后端

Visual Studio Marketplace 依賴 Azure DevOps 服務來處理已發布擴展的認證、托管和整體管理。因此，發布擴展的先決條件是擁有一個 Azure DevOps 組織。

要創建組織，請訪問 https://dev.azure.com 并使用您的 Microsoft 賬戶或 GitHub 賬戶登錄，如果您還沒有組織，請按照提示設置新組織。您的 Azure DevOps 組織名稱不一定需要與您在 Marketplace 中想要的發布者名稱一致。

要求使用 Azure DevOps 組織進行 Marketplace 發布，表明 Microsoft 正在利用其現有的云基礎設施和身份管理系統。對于個人開發者而言，這可能是一個簡單的設置步驟。然而，對于企業內部的開發者來說，這可能會引入與企業 Azure AD 策略或受限 PAT 創建相關的復雜性，這些都可能阻礙發布流程。在這種情況下，建議檢查組織設置或考慮創建一個新的 Entra 租戶。

生成個人訪問令牌 (PAT)：您的認證密鑰

vsce 作為發布工具，需要個人訪問令牌 (PAT) 來與 Marketplace 進行認證。此令牌是一種安全憑據，授予 vsce 與您的發布者賬戶交互所需的權限 4。

生成 PAT 的詳細步驟：

從您的 Azure DevOps 組織主頁（例如：https://dev.azure.com/your-organization-name），找到并點擊右上角的個人資料圖片。
從下拉菜單中選擇“Personal access tokens”（個人訪問令牌）4。
在“Personal Access Tokens”頁面上，點擊“New Token”（新建令牌）按鈕 4。
在“Create a new personal access token”模態框中，為您的令牌提供一個描述性的名稱（例如：“VSCode Extension Publisher PAT”）4。
在組織設置中，選擇“All accessible organizations”（所有可訪問的組織）4。
（可選）設置令牌的到期時間。雖然是可選的，但設置一個到期時間（例如 90 天或 1 年）是限制令牌生命周期的推薦安全實踐 4。
對于范圍 (Scopes)，這一點至關重要：選擇“Custom defined”（自定義）。然后，點擊“Show all scopes”（顯示所有范圍）鏈接。在完整的范圍列表中，向下滾動到“Marketplace”部分，并僅選擇“Manage”范圍。這授予了發布和管理擴展所需的最低權限，避免了令牌權限過高 4。
點擊“Create”（創建）5。
立即復制顯示的個人訪問令牌。 此令牌只會顯示一次，如果您離開此頁面，將無法再次檢索。請務必將其安全地存儲起來 4。

要求為 PAT 選擇特定的“Marketplace: Manage”范圍 4，是遵循最小權限原則的關鍵安全實踐。這意味著令牌僅擁有發布所需的權限，而不會獲得對整個 Azure DevOps 組織的更廣泛訪問權限，從而在令牌泄露時最大限度地降低潛在影響。

下表詳細列出了用于 Marketplace 發布所需的 Azure DevOps PAT 范圍，旨在提供清晰、簡潔的指導，并強調安全最佳實踐。

類別	范圍	描述
Marketplace	Manage	允許在 Visual Studio Marketplace 中發布和管理擴展。

在 Visual Studio Marketplace 上注冊您的發布者

發布者是您在 Visual Studio Marketplace 中的唯一身份或品牌名稱。您所有已發布的擴展都將顯示在該發布者名下。每個擴展的 package.json 清單文件都必須包含此發布者的 ID 5。

請訪問(https://marketplace.visualstudio.com/manage) 5。如果您尚未關聯現有發布者，系統會提示您點擊“+ Create a publisher”（創建發布者）5。

您需要提供兩個強制性參數：

ID：這是您在 Marketplace 中發布者的唯一標識符。它將成為您擴展 URL 的一部分（例如：https://marketplace.visualstudio.com/items?itemName=your-publisher-id.your-extension-name）。此 ID 是永久性的，創建后無法更改，因此請務必謹慎選擇 5。
名稱：這是您發布者的唯一顯示名稱，將在 Marketplace 中與您的擴展一起公開顯示。這可以是您的個人開發者別名、公司名稱或品牌名稱 4。

創建發布者后，您可以使用 vsce 進行驗證。在終端中運行 vsce login <your publisher id>，然后根據提示粘貼您之前生成的個人訪問令牌。成功消息將確認驗證完成 5。

發布者 ID 是唯一的、不可更改的，并且會成為擴展公共 URL 的一部分 5。這意味著它不僅僅是一個賬戶名稱，而是一個永久性的品牌標識符。因此，開發者在選擇發布者 ID 時應仔細考慮，因為它將代表他們在 Marketplace 中的長期形象和聲譽。

階段 3：準備您的顏色主題擴展以供發布

理解您的 `package.json` 清單：擴展的核心

package.json 文件是您的 VS Code 擴展的核心清單文件。盡管它與標準 npm 模塊的 package.json 有相似之處，但它包含特定于 Visual Studio Marketplace 的屬性，這些屬性對于擴展的識別和顯示至關重要 6。

顏色主題的關鍵屬性：

name：此屬性定義了您的擴展的唯一標識符。發布時，此 name 將與您的 publisher ID 結合，形成一個全球唯一的標識符（例如：your-publisher-id.your-extension-name）15。
displayName：這是將在 Marketplace、VS Code 的擴展視圖和主題選擇器中突出顯示的易于理解的名稱 12。
description：一段簡短的文本，顯示在搜索結果和擴展詳情頁面的橫幅上 15。
publisher：您在上一階段創建的唯一發布者 ID。這會將您的擴展鏈接到您的開發者身份 5。
version：此屬性指示您擴展的當前版本，遵循語義化版本 (SemVer) 原則（例如：1.0.0）5。
engines.vscode：此關鍵屬性指定了您的擴展兼容的 VS Code 版本范圍。例如，^1.8.0 表示兼容 VS Code 1.8.0 及所有后續的小版本和補丁版本（例如 1.8.1、1.9.0，但不包括 2.0.0）。對于預發布擴展，最低 engines.vscode 版本要求為 >= 1.63.0。正確設置此項可確保您的擴展僅安裝在兼容的客戶端版本上，從而防止意外行為 5。
categories：對于顏色主題，此屬性應設置為 "Themes"。這有助于用戶在 Marketplace 中篩選和找到您的擴展 10。
keywords：一個相關的搜索詞數組（例如："dark", "light", "theme", "color", "syntax", "custom"），用戶可能會使用這些詞來查找您的擴展。包含精心選擇的關鍵詞可顯著提高可發現性 10。
icon：指定一個指向 PNG 圖像文件（最小 128x128 像素）的相對路徑，該文件將用作您擴展的圖標。此圖標顯示在搜索結果和擴展詳情頁面的標題中。出于安全考慮，SVG 圖像不允許作為圖標 5。
galleryBanner.color：您可以為擴展 Marketplace 頁面上的橫幅背景設置一個十六進制顏色值。這有助于品牌建設和更精美的外觀 5。
repository：強烈建議包含指向您的公共 GitHub 倉庫的鏈接（例如：https://github.com/your-username/your-theme-repo）。vsce 可以自動檢測此鏈接并調整 README.md 文件中的相對鏈接，從而簡化文檔管理 5。

contributes.themes：聲明您的顏色主題：

在 package.json 中，contributes 部分用于聲明您的擴展為 VS Code 提供的具體功能。對于顏色主題，您將在 themes 屬性下定義一個數組 10。

themes 數組中的每個對象都代表您的擴展貢獻的一個獨立顏色主題：

label：這是將在 VS Code 的“首選項：顏色主題”選擇器中向用戶顯示的精確文本 15。
uiTheme：此屬性指定您的顏色主題旨在補充的基本 UI 主題類型。它必須是 "vs"（用于淺色主題）、"vs-dark"（用于深色主題）或 "hc-black"（用于高對比度主題）之一 15。
path：這是從您的擴展根目錄到實際主題 JSON 文件的相對文件路徑（例如：./themes/my-awesome-dark-theme.json）15。

下表提供了 package.json 中顏色主題的關鍵屬性，旨在提供一個可操作的參考，確保所有關鍵元數據都得到正確配置。

屬性	描述	示例值
`name`	擴展的唯一標識符（與發布者 ID 一起使用）。	`my-awesome-theme`
`displayName`	在 Marketplace 和 VS Code 中顯示的用戶友好名稱。	`My Awesome Theme`
`description`	用于搜索結果和橫幅的簡短描述。	`A vibrant dark theme for VS Code.`
`publisher`	您唯一的 Marketplace 發布者 ID。	`your-dev-alias`
`version`	擴展的當前版本（語義化版本）。	`1.0.0`
`engines.vscode`	VS Code 兼容性范圍。	`^1.8.0` (穩定版), `>= 1.63.0` (預發布版)
`categories`	擴展類型。對于主題，始終為 `Themes`。	``
`keywords`	用于可發現性的搜索詞。	`["dark", "theme", "syntax", "coding", "color"]`
`icon`	擴展 PNG 圖標的相對路徑（最小 128x128 像素）。	`images/icon.png`
`galleryBanner.color`	Marketplace 頁面橫幅背景的十六進制顏色。	`#1A2B3C`
`repository`	公共 Git 倉庫的 URL。	`https://github.com/your-user/your-theme-repo`
`contributes.themes`	對象數組，每個對象定義此擴展貢獻的一個主題。	見下方示例
`contributes.themes.label`	在 VS Code 主題選擇器中顯示的名稱。	`My Awesome Dark`
`contributes.themes.uiTheme`	基本 UI 主題類型 (`vs`, `vs-dark`, `hc-black`)。	`vs-dark`
`contributes.themes.path`	主題 JSON 文件的相對路徑。	`./themes/my-awesome-dark.json`

構造您的主題文件：`color-theme.json` 詳解

您的顏色主題的實際定義位于一個 JSON 文件中，通常以 .color-theme.json 為后綴（例如：my-awesome-dark.color-theme.json）。這種命名約定很有益處，因為 VS Code 在編輯此類文件時會提供語法提示和自動完成功能。此文件的路徑必須與 package.json 中 contributes.themes 部分的 path 屬性精確匹配 15。

主題 JSON 文件的核心結構：

name：此屬性指定主題在 VS Code 主題選擇器中顯示的名稱。這可以與您的 package.json 中的 displayName 或 name 不同，允許單個擴展包貢獻多個不同的主題 15。
type：此字符串屬性定義了主題的通用視覺類型，必須是 "dark" 或 "light"。即使您在 package.json 中將 uiTheme 指定為 "hc-black"（高對比度），此處的 type 仍需明確為 "dark" 或 "light" 15。
colors：這是一個關鍵對象，定義了 VS Code 界面的“應用程序”樣式。這些樣式控制著代碼編輯器文本區域之外的各種 UI 元素的顏色，例如側邊欄、文件樹、標簽頁、活動欄、面板、彈出窗口，甚至編輯器本身的一些方面，如選擇背景和邊框。顏色以鍵值對的形式定義，通常使用點表示法來表示分層元素（例如："activityBar.background": "#231934"）15。
- VS Code 提供了廣泛的 API 參考，詳細列出了數百個可自定義的應用程序顏色令牌，從而實現了對幾乎所有 UI 元素的精細控制 18。
tokenColors：此屬性是一個對象數組，定義了“語法”樣式。這些樣式應用于代碼文件中的特定語法范圍，控制著關鍵字、字符串、注釋、變量和其他代碼元素的顏色和字體樣式。這是您定義語法高亮的地方 15。
- tokenColors 的結構通常類似于設計令牌，允許您定義和重用顏色別名。這種方法，特別是與 Style Dictionary 等工具結合使用時，可以通過將主題分解為模塊化的 JSON 或 JavaScript 文件來幫助管理復雜主題，并促進顏色一致性 15。

增強 Marketplace 存在感：必要的文檔和資產

除了技術清單之外，強大的 Marketplace 存在感對于吸引用戶、建立信任和提高可發現性至關重要 5。

README.md 文件：此文件的內容將直接呈現在您的擴展的 Marketplace 頁面上，作為其主要“店面”。它應提供清晰的概述、功能、安裝說明（如果超出標準安裝流程）和使用示例 5。
- 如果您的 package.json 包含指向公共 GitHub 倉庫的 repository 屬性，vsce 將自動檢測并調整 README.md 中的相對鏈接（例如，圖像鏈接），默認指向 main 分支。您可以在打包或發布時使用 --githubBranch 標志覆蓋此行為，并使用 --baseContentUrl 和 --baseImagesUrl 標志指定內容和圖像的基礎 URL，以進行更精細的控制 5。
- 安全注意事項：README.md（和 CHANGELOG.md）中引用的所有圖像 URL 都必須是 https 協議。此外，這些文件中的圖像不能是 SVG 格式，除非它們來自受信任的徽章提供商。這是 Marketplace 強制執行的一項安全措施 5。
LICENSE 文件：在擴展的根目錄中包含一個 LICENSE 文件。此文件清晰地說明了他人使用、修改和分發您的主題的條款，從而保護您和您的用戶 5。
CHANGELOG.md 文件：維護一個 CHANGELOG.md 文件，用于記錄您擴展的版本歷史、新功能、錯誤修復和改進。這有助于用戶了解每個版本的新內容和變化 5。
SUPPORT.md 文件：提供一個 SUPPORT.md 文件，其中包含用戶如何獲得幫助、報告問題或貢獻的信息。這可以包括指向問題跟蹤器（例如 GitHub Issues）或社區論壇的鏈接 5。
圖標：如 package.json 部分所述，一個視覺吸引人的 PNG 圖標（最小 128x128 像素）對于您擴展在搜索結果和詳情頁面的視覺識別至關重要 5。
橫幅背景顏色：在 package.json 中設置 galleryBanner.color 允許您自定義 Marketplace 頁面上橫幅的背景顏色，進一步增強您的品牌形象 5。

下表列出了增強 Marketplace 存在感的關鍵文件，旨在突出這些文件對擴展專業外觀和用戶信任度的重要貢獻。

文件名	用途	位置
`README.md`	擴展 Marketplace 頁面的主要內容；提供概述、功能和用法。支持相對鏈接（如果設置了 `repository`，`vsce` 會自動調整）。圖像必須是 HTTPS 且非 SVG（除非受信任）。	根目錄
`LICENSE`	指定擴展的許可條款，明確使用、修改和分發權利。	根目錄
`CHANGELOG.md`	記錄版本歷史、新功能、錯誤修復和改進。幫助用戶跟蹤更新和理解變化。圖像必須是 HTTPS 且非 SVG（除非受信任）。	根目錄
`SUPPORT.md`	提供用戶如何獲取支持、報告問題或貢獻擴展的信息（例如，指向問題跟蹤器、論壇的鏈接）。	根目錄
`icon.png`	擴展的視覺標識。在 `package.json` 中指定的 PNG 文件（最小 128x128 像素）。對于可發現性和品牌建設至關重要。必須不是 SVG。	相對路徑（例如 `images/`）

優化您的包：`.vscodeignore` 文件和預發布腳本

.vscodeignore 文件：此文件在控制 .vsix 包中包含哪些文件和文件夾方面起著至關重要的作用。正確配置它有助于減小最終包的大小，改善用戶的安裝和加載時間，最重要的是，防止意外包含敏感數據或不必要的開發文件 5。
- 始終包含：某些基本文件即使您在 .vscodeignore 中明確列出，也始終會包含在包中。這些文件包括 README.md、package.json、LICENSE、任何資產（如圖像）以及 out 目錄（應包含您編譯的 JavaScript 文件，但不包括測試文件）7。
- 隱含忽略：某些文件會自動被忽略，無需在 .vscodeignore 中列出，例如 .vsix 文件（輸出包本身）、package-lock.json 和 .vscode 目錄 7。
- 明確忽略：您必須明確列出所有您希望排除的其他文件或文件夾，特別是可能包含敏感信息或對已部署擴展不必要的點文件（例如 .github、.env）7。
- 對于 TypeScript 項目，請確保您的 src 目錄和所有 TypeScript 文件（**/*.ts）都被排除，因為只有編譯后的 JavaScript 輸出才應存在于 out 目錄中 7。
vsce 強調配置 .vscodeignore 5，同時研究發現數千個擴展意外地打包了源代碼和敏感信息（如 AWS 密鑰、GitHub 憑據、PAT 等）8。這揭示了一個重大的安全漏洞。這意味著開發者必須細致地配置

.vscodeignore，以防止敏感數據被公開暴露，將其視為一項基本安全控制，而不僅僅是包大小優化。
預發布腳本：您可以在 package.json 的 scripts 部分中定義一個 vscode:prepublish 腳本。此腳本將在每次打包擴展時自動執行（例如，運行 vsce package 或 vsce publish 時）。這對于自動化構建步驟（如 TypeScript 編譯）特別有用 5。
- 示例："scripts": { "vscode:prepublish": "tsc" } 或 "scripts": { "vscode:prepublish": "npm run compile" }。這確保您的擴展代碼在打包發布之前始終是最新的并已編譯。

vscode:prepublish 腳本 5 是確保已發布擴展完整性和一致性的最佳實踐。它自動化了構建過程，保證

.vsix 包始終包含最新的編譯代碼。如果開發者忘記編譯 TypeScript 或運行構建步驟，已發布的擴展可能包含過時或損壞的代碼，導致用戶體驗不佳。通過 vscode:prepublish 自動化此步驟，可確保 .vsix 始終處于可部署、正確的狀態，直接影響擴展的質量和可靠性。

階段 4：打包和發布您的擴展

使用 `vsce package` 打包您的擴展：創建 `.vsix` 文件

在將擴展發布到 Marketplace 之前，通常建議先將其打包成一個 .vsix 文件。此文件是一個獨立的、可安裝的包，封裝了您擴展的所有代碼和資產 4。

要創建 .vsix 文件，請在終端中導航到您的擴展的根文件夾 4。

執行命令：vsce package。此命令將在您的根目錄中生成一個 .vsix 文件（例如：my-extension-0.0.1.vsix，其名稱來源于您 package.json 中的 name 和 version）4。您可以使用

--out <path> 標志指定 .vsix 文件的不同輸出目錄（例如：vsce package --out build/）7。

本地測試和分發：生成的 .vsix 文件對于在公共發布前進行本地測試非常寶貴。您可以在自己的 VS Code 實例中安裝它，以驗證其功能和外觀 4：

從 VS Code 擴展視圖：打開擴展視圖 (Ctrl+Shift+X)，點擊“視圖和更多操作…” (三點 ...)，然后選擇“從 VSIX 安裝…”。
從命令行：運行 code --install-extension my-extension-0.0.1.vsix (適用于標準 VS Code) 或 code-insiders --install-extension my-extension-0.0.1.vsix (適用于 VS Code Insiders 版本)。這還允許在不發布到 Marketplace 的情況下進行私有分發。

發布到 Visual Studio Marketplace：自動化與手動方法

vsce publish：命令行方法：
- 這是最常用、高效且推薦的直接發布擴展到 Marketplace 的方法 4。
- 確保您在終端中位于擴展的根文件夾。
- 運行命令：vsce publish。如果您之前沒有使用 vsce login <publisher id> 登錄，它將提示您輸入個人訪問令牌 (PAT) 4。
- 或者，您也可以直接提供 PAT 作為可選參數：vsce publish -p <your_personal_access_token> 6。
- Git 集成：如果您在 Git 倉庫中執行 vsce publish，該命令將自動使用 npm-version 創建一個版本提交和相應的 Git 標簽。默認的提交消息將是擴展的版本，但您可以使用 -m 標志進行自定義（例如：vsce publish -m "Release v%s"，其中 %s 會被版本號替換）5。
擴展版本控制：major、minor、patch 和特定版本：
- vsce 提供了便捷的選項，可在發布過程中自動遞增擴展的版本號，遵循語義化版本 (SemVer) 原則 4。
- vsce publish patch：此命令遞增您的擴展的補丁版本（例如，1.0.0 變為 1.0.1）。這適用于錯誤修復和次要的向后兼容更改 4。
- vsce publish minor：此命令遞增小版本（例如，1.0.0 變為 1.1.0）。將其用于向后兼容的新功能 4。
- vsce publish major：此命令遞增大版本（例如，1.0.0 變為 2.0.0）。這通常用于包含重大更改的發布 4。
- 您也可以明確指定一個完整的 SemVer 版本號：vsce publish 2.0.1 5。
- 發布預發布擴展：要發布預發布版本（例如 alpha、beta 或發布候選版本），請在 vsce publish 命令后附加 --pre-release 標志（例如：vsce publish --pre-release）5。
  - 預發布的重要版本控制：VS Code 的 Marketplace 僅支持 major.minor.patch 版本控制；傳統的 SemVer 預發布標簽（例如 1.0.0-beta）不受支持。這意味著您的預發布版本仍必須遵循 X.Y.Z 格式 5。
  - 用戶更新的關鍵策略：為了防止預發布渠道的用戶自動更新到穩定版本（如果管理不當，這可能是較舊的版本號），強烈建議預發布版本使用 major.ODD_NUMBER.patch 方案，而穩定版本使用 major.EVEN_NUMBER.patch（例如，0.2.* 用于穩定版，0.3.* 用于預發布版）。或者，始終確保您的預發布版本號在數值上高于最新的穩定版本，以保持清晰的更新路徑 5。
  - 預發布擴展要求 package.json 中的 engines.vscode 屬性設置為 >= 1.63.0 或更高 5。

下表詳細說明了使用 vsce publish 命令進行版本管理的各種選項，旨在清晰地展示發布過程中管理版本的方式。

命令	描述	示例（假設當前版本為 `1.0.0`）
`vsce publish`	發布 `package.json` 中當前定義的版本。	`1.0.0`
`vsce publish patch`	遞增補丁版本。適用于錯誤修復和次要向后兼容更改。	`1.0.1`
`vsce publish minor`	遞增小版本。適用于向后兼容的新功能。	`1.1.0`
`vsce publish major`	遞增大版本。通常用于包含重大更改的發布。	`2.0.0`
`vsce publish <version>`	發布指定的語義化版本號。	`vsce publish 1.2.3`
`vsce publish --pre-release`	發布為預發布版本。需要特殊的版本管理策略（例如奇數小版本號）。	`0.3.0` (如果穩定版是 `0.2.x`)

預發布版本控制的詳細說明（例如，奇數小版本號與偶數小版本號 5）揭示了開發者如何管理擴展版本與用戶更新體驗之間的直接因果關系。不正確的策略可能導致預發布用戶意外地被更新到穩定版本，從而造成混淆或功能中斷。

手動通過 Marketplace 門戶上傳：
- 您也可以直接將 .vsix 文件上傳到 Visual Studio Marketplace 發布者管理頁面 5。
- 訪問 https://marketplace.visualstudio.com/manage，選擇您的發布者，然后點擊“New extension”（新建擴展）-> “Azure DevOps”（或“Visual Studio”，適用于 VS IDE 擴展），然后上傳 .vsix 文件 13。
發布期間的安全注意事項：
- vsce 不會發布包含用戶提供的 SVG 圖像作為圖標或徽章的擴展（除非來自受信任的徽章提供商）5。
- README.md 和 CHANGELOG.md 中圖像的 URL 必須使用 https 協議 5。
- Marketplace 會對新的和更新的擴展包執行病毒掃描 13。
- 請務必注意，避免在 .vsix 文件中意外打包敏感信息（例如 API 密鑰、憑據）。請務必認真使用 .vscodeignore 8。

對 SVG 圖像的限制、對 HTTPS 圖像 URL 的要求 5 以及 Marketplace 的病毒掃描 13 表明 Microsoft 充當著安全守門人的角色。盡管這并非萬無一失（如惡意擴展的存在所示 3），但這些措施旨在保護更廣泛的用戶群。這意味著開發者必須遵守這些規則才能成功發布。

階段 5：發布后管理和最佳實踐

更新您已發布的擴展：保持最新

要更新擴展，請在 package.json 中遞增 version（或使用 vsce publish major/minor/patch 命令）5。
然后，在擴展的根目錄中運行 vsce publish 4。
或者，您也可以通過 Marketplace 發布者管理頁面手動上傳新的 .vsix 文件，選擇擴展旁邊的“編輯”選項 17。
除非用戶已禁用自動更新或已固定到特定版本，否則他們將收到自動更新 1。

取消發布您的擴展：何時以及如何操作

如果您不再希望擴展可用，可以將其取消發布。取消發布會保留統計數據，而刪除則會清除它們 5。
使用 vsce：運行 vsce unpublish <publisher id>.<extension name>。系統將提示您確認 5。
手動通過 Marketplace 門戶：訪問 https://marketplace.visualstudio.com/manage，找到您的擴展，然后選擇“更多操作”>“刪除”（或“取消發布”）。您必須輸入擴展名稱以確認刪除 5。

監控您的擴展性能：下載量和評論

Visual Studio Marketplace 發布者管理頁面提供對“獲取趨勢”、“總獲取量”以及“評分與評論”的訪問權限 5。
要查看報告，請在管理頁面上點擊擴展或選擇“更多操作”>“報告”5。
第三方工具或瀏覽器擴展（例如 Chrome 的“VS Marketplace Metrics”）也可以提供安裝量的快速概覽 23。
VS Code 本身會收集遙測數據（例如使用數據、錯誤遙測）以改進產品，但擴展特定的遙測通常由作者添加 24。

更新、取消發布和監控統計數據 5 的部分明確表明，發布并非擴展生命周期的終點，而是起點。這意味著開發者需要持續投入，維護、改進和支持他們的擴展。

長期成功和可見性的最佳實踐

定期更新：保持您的主題新鮮，并與新的 VS Code 版本兼容 4。
回應反饋：通過評論和支持渠道與用戶互動。
保持質量：確保您的主題性能良好且無錯誤。
推廣您的擴展：在社交媒體、博客或開發者社區中分享它。
考慮已驗證發布者狀態：盡管這并非全面的安全保證，但添加 DNS 驗證域名可以獲得一個“閃亮的藍色徽章”8，這可能會增加感知到的可信度 5。
- 驗證流程：訪問 Marketplace 發布者管理頁面，選擇您的發布者，進入“詳細信息”選項卡，輸入符合條件的域名，保存，然后驗證。按照 DNS TXT 記錄說明操作。審核可能需要最多 5 個工作日 5。
- 符合條件的域名：必須可管理（DNS TXT 記錄），不能是子域名（例如，不是 github.io），必須使用 HTTPS 協議，并且必須能以 HTTP 200 狀態響應 HEAD 請求 5。
雖然“已驗證發布者”徽章被宣傳為積極的標志 8，但同一片段也揭示了它可以通過簡單的 DNS 記錄輕松獲得，并且盡管有此徽章，仍存在許多惡意擴展。這表明徽章更多地是關于域名所有權，而非 Microsoft 進行的全面安全審計。
UX 指南：遵循 VS Code 的用戶體驗 (UX) 指南，以實現無縫集成和原生體驗 25。這包括理解容器（活動欄、側邊欄、編輯器、面板、狀態欄）和項目（視圖、工具欄、狀態欄項目）以及常見 UI 元素（命令面板、快速選擇、通知、Webview、上下文菜單、引導流程、設置）。

UX 指南的提及 25 表明，除了功能之外，擴展與 VS Code 原生 UI 的視覺和功能集成程度是衡量質量的關鍵指標。這意味著開發者應投入時間使他們的主題感覺“原生”和直觀，這有助于在競爭激烈的市場中脫穎而出。

結論與建議

發布 VS Code 顏色主題到 Visual Studio Marketplace 是一項多步驟的流程，它超越了簡單的代碼上傳。它要求開發者不僅要精通技術實現，還要理解 Marketplace 的生態系統、安全協議以及用戶期望。

首先，正確設置開發環境和認證憑據是基石。Node.js 版本兼容性以及 Azure DevOps PAT 的精確范圍配置是避免早期發布障礙的關鍵。其次，package.json 文件是擴展的“身份證”，其元數據（如 displayName、categories、keywords 和 icon）直接影響擴展在 Marketplace 中的可發現性和吸引力。特別是對于顏色主題，contributes.themes 部分的正確配置至關重要。

此外，發布不僅僅是技術操作，更是一項產品發布。高質量的 README.md、CHANGELOG.md 和 LICENSE 文件是建立用戶信任和專業形象的基礎。同時，嚴格管理 .vscodeignore 文件以防止敏感信息泄露，是保障擴展安全性的重要防線。版本控制策略，尤其是預發布版本的管理，直接影響用戶更新體驗，需要深思熟慮。

最后，發布后的持續管理和推廣同樣重要。通過監控 Marketplace 提供的下載量和評論數據，開發者可以獲得寶貴的用戶反饋，指導后續的更新和改進。雖然“已驗證發布者”徽章可以提升感知可信度，但開發者應理解其背后的驗證機制，并持續專注于提供高質量、安全的擴展。遵循 VS Code 的 UX 指南，確保主題與 IDE 的原生界面無縫融合，將進一步提升用戶滿意度。

總而言之，成功發布并維護一個 VS Code 顏色主題，需要技術能力、對細節的關注、安全意識以及對用戶體驗的深刻理解。通過遵循這些指導原則，開發者可以確保他們的主題不僅能夠順利發布，還能在充滿活力的 VS Code 生態系統中獲得認可和持續發展。