vscode-extension-publisher

VS Code Extension Publisher

指导用户完成 VS Code 扩展的设置、打包和发布，将其发布到 Visual Studio Marketplace，包括 PAT/发布者设置、发布前验证和 CI/CD 自动化。

编辑前同步仓库（必需）

在现有仓库中创建、更新或删除文件之前，请先将当前分支与远程仓库同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，请先暂存更改，再同步，然后恢复更改：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少 origin、无法拉取，或 rebase/暂存操作发生冲突，请停止并在继续前询问用户。

说明

步骤 1：运行发布前检查

在进行任何操作之前，先验证环境和项目。

运行随附的发布前检查脚本：

bash scripts/preflight-check.sh

该脚本会检查：

• 是否已安装 Node.js 和 npm
• 是否已全局安装 @vscode/vsce（如果缺少则进行安装）
• package.json 是否存在且包含必需字段
• 是否没有 SVG 图标（市场限制）

如果脚本不可用，请手动验证：

1. 已安装 Node.js： node --version（需要 v18+）
2. 已安装 npm： npm --version
3. 已安装 vsce： vsce --version — 如果缺少，请运行 npm install -g @vscode/vsce
4. 扩展根目录中是否存在 package.json

步骤 2：验证 package.json

发布时必须包含以下字段：

字段	说明	示例
name	扩展标识符（小写，不含空格）	"my-extension"
displayName	便于用户识别的名称	"My Extension"
description	简短说明	"Adds cool features"
version	Semver 版本	"1.0.0"
publisher	发布者 ID	"my-publisher"
engines.vscode	最低 VS Code 版本	"^1.80.0"
categories	市场分类	["Other"]

建议添加以下字段，以提升在市场中的展示效果：

字段	说明
icon	PNG 图标路径（最小 128x128px，不能使用 SVG）
repository	GitHub 仓库 URL
license	许可证标识符（例如，"MIT"）
keywords	搜索关键词（最多 30 个）
galleryBanner.color	市场横幅的十六进制颜色
galleryBanner.theme	"dark" 或 "light"

如果缺少任何必需字段，请帮助用户将其添加到 package.json。

步骤 3：设置 Azure DevOps PAT（如需要）

如果用户以前从未发布过，请指导他们创建 PAT：

1. 前往 https://dev.azure.com — 登录（或创建免费账户）
2. 点击 User Settings（齿轮图标）> Personal Access Tokens
3. 点击 + New Token，并设置以下选项：
   • Name： vsce-publish（或任何描述性名称）
   • Organization： 选择 All accessible organizations
   • Expiration： 设置合理的有效期（最长 1 年）
   • Scopes： 点击 Custom defined > Marketplace > 勾选 Manage
4. 点击 Create 并立即复制令牌（之后将无法再次查看）

重要： PAT 必须具备以下设置：

• Organization：All accessible organizations（不能是特定组织）
• Scope：Marketplace > Manage

步骤 4：创建或验证发布者（如需要）

如果用户还没有发布者身份：

1. 前往 https://marketplace.visualstudio.com/manage
2. 使用创建 PAT 时所用的同一个 Microsoft 账户登录
3. 点击 Create publisher
4. 填写：
   • ID： 唯一标识符（之后无法更改！）
   • Name： 在市场中显示的名称
5. 运行以下命令进行验证：vsce login <publisher-id>
   • 按提示输入 PAT

确保 package.json 中的 publisher 字段与发布者 ID 完全一致。

步骤 5：打包扩展

发布前，先创建 .vsix 包进行测试：

vsce package

此操作会生成类似 my-extension-0.0.1.vsix 的文件。

发布前在本地测试：

code --install-extension my-extension-0.0.1.vsix

如果打包时出错：

• 缺少 README.md： 在项目根目录中创建 README.md
• SVG 图标： 替换为 PNG 文件（最小 128x128px）
• 缺少许可证： 添加 LICENSE 文件，或在 package.json 中设置 "license"

步骤 6：发布到 Marketplace

测试结果满意后，发布：

vsce publish

版本升级选项：

vsce publish patch    # 1.0.0 → 1.0.1
vsce publish minor    # 1.0.0 → 1.1.0
vsce publish major    # 1.0.0 → 2.0.0
vsce publish 1.2.3    # Set exact version

在 git 仓库中，vsce publish 会自动创建版本提交和标签。

**发布后：**扩展程序会在约 5 分钟内出现在 Marketplace 上。请在以下地址验证： https://marketplace.visualstudio.com/items?itemName=<publisher>.<extension-name>

步骤 7：设置 GitHub Actions CI/CD（可选）

如果用户希望自动发布，请生成 GitHub Actions 工作流。

将模板从 assets/github-actions-publish.yml 复制到项目中：

mkdir -p .github/workflows
cp assets/github-actions-publish.yml .github/workflows/publish.yml

然后指导用户：

1. 将 PAT 添加为名为 VSCE_PAT 的 GitHub 密钥：
   • 前往仓库的 Settings > Secrets and variables > Actions
   • 点击 New repository secret
   • 名称：VSCE_PAT，值：Azure DevOps PAT
2. 当 git 标签与 v* 匹配时（例如 v1.0.0），触发发布
3. 要发布版本：git tag v1.0.0 && git push origin v1.0.0

有关 CI/CD 自定义选项，请参阅 references/publishing-guide.md。

步骤完成报告

完成每个主要步骤后，按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据步骤实际验证的内容调整检查项名称。通过使用 √，失败使用 ×，并使用 — 添加简短说明。“Criteria”行概述已满足的验收标准数量。“Result”行给出总体结论。

预检阶段检查项： Node.js available、vsce installed、package.json valid

身份验证设置阶段检查项： PAT configured、Publisher verified

打包阶段检查项： Extension packaged、Size reasonable、Manifest correct

发布阶段检查项： Upload success、Marketplace live、CI/CD configured

示例

示例 1：首次发布

用户说：“我想将 VS Code 扩展发布到 Marketplace。”

操作：

1. 运行预检，验证环境
2. 验证 package.json — 填写所有缺失的必填字段
3. 引导用户在 Azure DevOps 上创建 PAT
4. 在 Marketplace 上创建发布者身份
5. 使用 vsce login 登录
6. 使用 vsce package 打包并在本地测试
7. 使用 vsce publish 发布

结果：扩展已在 VS Code Marketplace 上线。

示例 2：升级版本并发布更新

用户说：“发布我的扩展的新次要版本。”

操作：

1. 运行预检
2. 验证 package.json 是否有效
3. 运行 vsce publish minor

结果：版本已升级并发布（例如，1.0.0 → 1.1.0）。

示例 3：设置 CI/CD 以自动发布

用户说：“创建 GitHub Actions 工作流来自动发布我的扩展。”

操作：

1. 将 assets/github-actions-publish.yml 复制到 .github/workflows/publish.yml
2. 引导用户将 VSCE_PAT 密钥添加到 GitHub 仓库
3. 说明标签工作流：git tag v1.0.0 && git push origin v1.0.0

结果：扩展会在版本标签触发时自动发布。

错误处理

401 未授权 / 403 禁止访问

**原因：**PAT 无效、已过期或权限范围不正确。 解决方案：

1. 在 https://dev.azure.com 重新生成 PAT，并设置：
   • 组织：“All accessible organizations”
   • 权限范围：Marketplace > Manage
2. 重新登录：vsce login <publisher-id>

“扩展已存在”

**原因：**此扩展名称归其他发布者所有。 **解决方案：**将 package.json 中的 name 字段改为唯一名称。displayName 可以使用任意名称。

SVG 图标错误

**原因：**出于安全原因，Marketplace 禁止使用 SVG 图标。 **解决方案：**将图标转换为 PNG 格式（至少 128x128 像素），并更新 package.json 中的 icon 字段。

package.json 中缺少字段

**原因：**缺少必填字段。 **解决方案：**运行预检脚本，找出缺失字段，然后将其添加到 package.json。

“标签超过 30 个”

原因：keywords 数组中的条目过多。 **解决方案：**将 keywords 减少到不超过 30 个条目。

vsce package 因 prepublish 错误而失败

原因： package.json 中的 vscode:prepublish 脚本执行失败。 解决方案： 手动运行 prepublish 脚本以查看错误：

npm run vscode:prepublish

重试前，请先修复底层构建问题。