{T}

VSCode插件实战：私密分享和公开发布

当你精心打造了一款强大的 VSCode 插件后，如何让其他人也能使用到你的成果呢？是直接将代码发给同事，还是发布到公开的应用商店，让全球开发者都能一键安装？本文将为你详细解析这两种插件分享方式，助你轻松走完 “从开发到分享” 的最后一公里。

管理依赖：从本地开发切换到 NPM 包

在进行插件分享或发布之前，一个关键的预备步骤是规范化你的项目依赖。在开发阶段，我们可能通过 npm link 来本地调试一个依赖组件（例如，我们项目中的 md-wx 组件）。这种方式非常适合并行开发和快速测试。

然而，在分享或发布插件前，你需要确保所有的依赖都指向其在 NPM 仓库中的稳定版本，而不是本地的链接。这能保证其他用户在安装你的插件时，能够获得一个完整、可复现的运行环境。

第一步：移除本地链接 (npm unlink)

首先，进入到你的子项目目录（在我们的案例中是 webview），然后运行 unlink 命令来移除之前的本地链接。

bash
# 进入 webview 目录
cd src/webview

# 移除 md-wx 的链接
npm unlink md-wx

第二步：从 NPM 仓库安装

移除链接后，直接从 NPM 仓库安装该组件的发布版本。

bash
npm i md-wx

第三步：清理临时类型文件

在使用 npm link 进行本地开发时，为了解决 TypeScript 的类型识别问题，我们可能手动创建了一个类型声明文件（例如 src/webview/src/types/md-wx.d.ts）。

既然现在已经安装了官方的 NPM 包（它自带了类型声明），这个临时的文件就不再需要了，甚至可能与包内建的类型冲突。因此，我们应该果断地将它删除，保持项目整洁。

完成以上步骤后，你的插件就正式地依赖于一个公共的、版本化的组件，为后续的分享和发布做好了准备。

私密分享：当你的插件还不想“抛头露面”

在插件开发的初期，或者当插件仅为特定团队服务时，我们通常不希望直接公开发布，我们可以将插件打包为 .vsix 文件，直接分享给团队成员使用。

在我们发布到 VS Code 插件市场之前，建议先通过本地的 .vsix 文件进行测试验证。

打包为 .vsix 文件：最简单的分享方式

VS Code (以及 Trae) 支持通过 .vsix 格式的打包文件来安装插件。这是一种非常便捷的离线分发方式。

第一步：安装 vsce

vsce (Visual Studio Code Extensions) 是官方提供的用于打包、发布和管理 VS Code 插件的命令行工具。

bash
npm install --global vsce

第二步：打包插件

在你的插件项目根目录下，运行以下命令：

bash
vsce package

如果一切顺利，你会在根目录下看到一个名为 <your-extension-name>-<version>.vsix 的文件。这个文件就是你的插件安装包。

第三步：分享与安装

你只需要将这个 .vsix 文件发送给你的同事或朋友。他们可以在 Trae 中通过以下步骤轻松安装：

  1. 打开“扩展”视图 (Extensions)。
  2. 点击视图右上角的 ... 更多操作菜单。
  3. 选择 “Install from VSIX...” (从 VSIX 安装...)。
  4. 在弹出的文件选择器中，找到并选中你分享的 .vsix 文件即可。

这种方式非常适合快速测试和内部使用。

AI 协助解决打包问题

在实际操作中，执行 vsce package 命令有时并不会一帆风顺。例如，我们可能会遇到缺少仓库信息或 LICENSE 文件的错误。这时，我们可以借助 AI 的力量快速定位并解决问题。

我们将终端输出的错误日志直接交给 AI：

AI 迅速分析了问题，并采取了以下步骤来解决：

  1. 修复 package.json：AI 发现 package.json 中缺少了必要的 repository 字段，并为其添加了正确的仓库地址。
  2. 创建 LICENSE 文件：根据错误提示，AI 创建了一个标准的 MIT 协议的 LICENSE 文件。
  3. 优化打包体积：初次打包成功后，AI 发现打包体积过大（约 37MB），包含了大量无需打包的文件。于是，AI 主动创建了一个 .vscodeignore 文件，将 node_modules、编译输出目录等内容排除在打包范围之外。

整个修复和优化过程清晰明了：

经过 AI 的一番操作，打包问题不仅得到了解决，打包后的 .vsix 文件体积也从 37.88MB 大幅减少到 473.82KB，文件数量从 9050 个减少到 13 个。

修复 sharp 模压缩块问题

本地安装插件后，点击预览按钮时，系统提示 “command 'md-wx-vscode.showPreview' not found” 错误。

起初，我们尝试围绕此错误信息进行多次修复，但均未成功。后来意识到，该错误可能是由于命令未成功注册，而注册失败的根源在于插件安装过程中就已发生错误。为了验证这一猜想，我们打开开发者工具查看日志，并在重新安装插件时，发现了如下报错信息：

针对 Cannot find module 'sharp' 的报错，AI 也尝试了多次修复，但问题依然存在。根本原因在于 sharp 模块依赖于原生代码，并非纯 JavaScript 实现，这导致在打包过程中需要处理复杂的跨平台适配问题。为了绕开这个障碍，我们决定更换技术方案，采用 HTML5 Canvas API 来实现图片压缩。由于 Canvas API 是浏览器环境的标准接口，因此需要将压缩逻辑放在 Webview 中执行。

如果您也遇到了类似的问题，可以参考以下提示词来解决。我们使用该提示词，一次性就成功修复了问题。

提示词：

code
执行命令 vsce package 打包后，选择从 VSIX 安装插件，之后点击预览报错 “command 'md-wx-vscode.showPreview' not found”

在 “运行和调试” 模式下是没有这个问题的。但这个报错不是问题的根本原因，后来发现在安装插件时有个报错  “Cannot find module 'sharp'” 项目中有个图片压缩功能，使用的 sharp 模块，基于这个报错进行了多次修复仍未成功。

请使用方案：“HTML5 Canvas API在webview中进行图片压缩”  注意，你现在主要是优化图片压缩问题，不要改出来其它问题

修复完成后，建议进行完整的自测，以确保所有功能正常。

为 VS Code 插件设置 Logo 非常简单，只需要一张 PNG 格式的图片。准备好图片（例如 icon.png）并将其放置在项目根目录，然后在 package.json 文件中添加 icon 字段并指定图片路径即可。

json
{
  "icon": "icon.png"
}

配置完成后，插件在 VS Code 市场和扩展视图中就会显示你设置的 Logo。

效果如下图所示：

公开发布：让世界看到你的作品

当你的插件已经足够成熟和稳定，就可以考虑将它发布到 VS Code Marketplace。这能极大地提升插件的可见度和影响力。

发布前的准备工作

在发布之前，你需要准备好以下几样东西：

  1. 创建发布者 (Publisher)：发布者是展示在 Marketplace 上的身份标识。

  2. 个人访问令牌 (PAT)：为了让 vsce 工具能够代表你在应用商店上进行操作，你需要生成一个 Personal Access Token。

    • 进入你的 Azure DevOps 组织。第一次注册需要创建一个组织

    • 之后进入界面 https://dev.azure.com/aizjj/ 在右上角的用户设置中，选择 "Personal access tokens"。

    • 创建一个新的 Token，确保 "Organization" 设置为 "All accessible organizations"，并将 "Scopes" 设置为 "Marketplace (Manage)"。

    • 重要提示：创建后请立即复制并妥善保管这个 Token，因为页面关闭后你将无法再次看到它。

完善 package.json：打造插件的“身份证”

package.json 文件定义了插件的所有元数据，这些信息将直接展示在应用商店中。请确保以下字段填写正确且信息丰富：

  • publisher: 你的发布者 ID。必须与你在 Marketplace 上创建的发布者 ID 完全一致。
  • name: 插件的唯一 ID。
  • displayName: 展示在应用商店和插件列表中的名称，力求清晰易懂。
  • description: 插件的简短描述。
  • version: 版本号。每次更新插件时，都需要增加此版本号（遵循 SemVer 规范）。
  • repository: 你的 GitHub 仓库地址，方便用户反馈问题和贡献代码。
  • categories: 为你的插件选择合适的分类，如 [Programming Languages, Linters, Snippets]。

编写高质量的 README.md：插件的“说明书”

README.md 是用户了解你插件功能的最主要窗口，它的内容将直接呈现在应用商店的详情页。一个优秀的 README.md 应该包含：

  • 清晰的功能介绍：插件是做什么的，解决了什么问题。
  • 生动的截图或 GIF：用图片直观地展示插件的核心功能和使用效果。
  • 详细的使用指南：如何配置、有哪些命令、快捷键是什么。
  • 更新日志 (Changelog)：让用户了解每个版本的变化。

发布与更新

准备工作就绪后，就可以开始发布了。

第一步：登录

登录到发布者账号。

bash
vsce login <publisher-name>

此时会提示你输入之前保存的 Personal Access Token。 <publisher-name> 就是你的发布者 ID。

第二步：发布

最后，激动人心的时刻到了！运行发布命令：

bash
vsce publish

vsce 会自动打包并将你的插件上传到 Marketplace。发布成功后，几分钟内全球的 Trae 和 VS Code 用户就能搜索到你的插件了。

查看发布结果

发布成功后，你可以通过以下几种方式来验证和查看你的插件：

  1. 在 Marketplace 管理页面查看： 访问你的 VS Code Marketplace 发布者管理页面，可以看到你名下已发布的所有插件列表。

  2. 在 VS Code 中搜索： 打开 VS Code，进入扩展视图，搜索你的插件名称（例如 “markdown wechat”），就可以找到并安装它。

  3. 通过网页链接访问： 你的插件会有一个专属的公共页面。你可以通过链接 https://marketplace.visualstudio.com/items?itemName=<publisher-name>.<extension-name> 直接访问。例如：https://marketplace.visualstudio.com/items?itemName=aizjj.md-wx-vscode

更新你的插件

当你想发布新版本时，流程非常简单：

  1. 在 package.json 中，将 version 字段升级到一个更高的版本（例如从 1.0.0 到 1.0.1）。
  2. 再次运行 vsce publish 命令。

Marketplace 会自动为你的插件创建新版本

开发历程回顾

遵循我们制定的文档和规则，我们与 AI 协作，逐步完成了整个插件的开发。以下是该项目完整的 Git 提交历史和 AI 会话记录，真实地展示了整个开发过程。

Git 提交记录

从提交记录中我们可以看到，每一次提交都对应着任务拆分中的一个具体步骤。这种原子化的提交习惯，使得代码的演进历史清晰可追溯。

AI 会话记录

整个开发过程中的每一步，我们都通过与 AI 对话来完成。会话记录展示了我们如何向 AI 下达指令，以及 AI 如何根据指令完成编码、调试和重构等任务。

总结

在本章中，我们完整地走过了一个 VS Code 插件从开发、调试到最终发布的全过程。我们首先学习了如何通过打包为 .vsix 文件进行本地测试和私密分享，这对于开发初期和内部协作至关重要。接着，我们解决了一个实际开发中可能遇到的棘手问题——原生模块 sharp 的打包失败，并采用 HTML5 Canvas API 的方案成功绕过。

在插件功能完善后，我们为它配置了专业的 Logo，并详细介绍了如何将插件公开发布到 VS Code Marketplace。这个过程涵盖了创建发布者、生成个人访问令牌（PAT）、完善 package.json 和 README.md 元数据，以及使用 vsce 工具执行发布和更新命令的每一个关键步骤。最后，我们还学习了如何在发布后多渠道验证插件的上线情况。

通过本章的实战演练，你不仅掌握了 VS Code 插件开发的完整生命周期，也积累了解决复杂问题的经验。希望你能够运用这些知识，将自己的创意和工具分享给全球的开发者，为社区贡献自己的一份力量。祝你的插件开发之旅顺利！