vscode-extension-publisher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VS Code Extension Publisher

VS Code扩展发布指南

Guides users through setting up, packaging, and publishing VS Code extensions to the Visual Studio Marketplace, including PAT/publisher setup, pre-flight validation, and CI/CD automation.

引导用户完成VS Code扩展的配置、打包和发布到Visual Studio Marketplace的全流程，包括PAT/发布者账号配置、预检验证以及CI/CD自动化。

Repo Sync Before Edits (mandatory)

编辑前同步仓库（必填）

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

bash

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

If the working tree is not clean, stash first, sync, then restore:

bash

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

is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

在现有仓库中创建/更新/删除文件前，需将当前分支与远程仓库同步：

bash

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

如果工作区未清理，先暂存修改，同步后再恢复：

bash

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

远程仓库、无法拉取，或在变基/暂存时出现冲突，请停止操作并询问用户后再继续。

Instructions

操作步骤

Step 1: Run Pre-flight Checks

步骤1：运行预检检查

Before anything else, validate the environment and project.

Run the bundled preflight script:

bash

bash scripts/preflight-check.sh

This checks:

Node.js and npm are installed
```
@vscode/vsce
```
is installed globally (installs it if missing)
```
package.json
```
exists and has required fields
No SVG icons (marketplace restriction)

If the script is not available, manually verify:

Node.js installed:
```
node --version
```
(requires v18+)
npm installed:
```
npm --version
```

vsce installed:

vsce --version

— if missing, run

npm install -g @vscode/vsce

package.json exists in the extension root directory

在开始任何操作前，先验证环境和项目。

运行内置的预检脚本：

bash

bash scripts/preflight-check.sh

该脚本会检查：

是否已安装Node.js和npm
是否已全局安装
```
@vscode/vsce
```
（如果缺失则自动安装）
```
package.json
```
是否存在且包含必填字段
是否存在SVG图标（市场限制）

如果脚本不可用，手动验证以下内容：

Node.js已安装：运行
```
node --version
```
（要求v18+）
npm已安装：运行
```
npm --version
```
vsce已安装：运行
```
vsce --version
```
—— 如果缺失，执行
```
npm install -g @vscode/vsce
```
package.json存在于扩展根目录

Step 2: Validate package.json

步骤2：验证package.json

The following fields are required for publishing:

Field	Description	Example
`name`	Extension identifier (lowercase, no spaces)	`"my-extension"`
`displayName`	Human-readable name	`"My Extension"`
`description`	Short description	`"Adds cool features"`
`version`	Semver version	`"1.0.0"`
`publisher`	Your publisher ID	`"my-publisher"`
`engines.vscode`	Minimum VS Code version	`"^1.80.0"`
`categories`	Marketplace categories	`["Other"]`

Recommended fields for better marketplace presence:

Field	Description
`icon`	Path to PNG icon (min 128x128px, no SVG)
`repository`	GitHub repo URL
`license`	License identifier (e.g., `"MIT"` )
`keywords`	Search keywords (max 30)
`galleryBanner.color`	Hex color for marketplace banner
`galleryBanner.theme`	`"dark"` or `"light"`

If any required field is missing, help the user add it to

package.json

以下字段是发布必填项：

字段	描述	示例
`name`	扩展标识符（小写，无空格）	`"my-extension"`
`displayName`	人类可读的名称	`"My Extension"`
`description`	简短描述	`"Adds cool features"`
`version`	语义化版本号	`"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

中。

Step 3: Setup Azure DevOps PAT (if needed)

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

If the user has never published before, guide them through PAT creation:

Go to https://dev.azure.com — sign in (or create a free account)
Click User Settings (gear icon) > Personal Access Tokens
Click + New Token with these settings:
- Name:
```
vsce-publish
```
  (or any descriptive name)
- Organization: Select All accessible organizations
- Expiration: Set a reasonable duration (max 1 year)
- Scopes: Click Custom defined > Marketplace > check Manage
Click Create and copy the token immediately (it won't be shown again)

Important: The PAT must have:

Organization: "All accessible organizations" (not a specific org)
Scope: Marketplace > Manage

如果用户从未发布过扩展，引导他们创建PAT：

访问https://dev.azure.com —— 登录（或创建免费账号）
点击用户设置（齿轮图标）> Personal Access Tokens
点击**+ New Token**，配置以下设置：
- 名称：
```
vsce-publish
```
  （或其他描述性名称）
- 组织：选择All accessible organizations
- 有效期：设置合理时长（最长1年）
- 权限范围：点击Custom defined > Marketplace > 勾选Manage
点击Create并立即复制令牌（令牌只会显示一次）

重要提示：PAT必须满足：

组织："All accessible organizations"（不是特定组织）
权限范围：Marketplace > Manage

Step 4: Create or Verify Publisher (if needed)

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

If the user doesn't have a publisher identity:

Go to https://marketplace.visualstudio.com/manage
Sign in with the same Microsoft account used for the PAT
Click Create publisher
Fill in:
- ID: Unique identifier (cannot be changed later!)
- Name: Display name shown on marketplace
Verify by running:
```
vsce login <publisher-id>
```
- Enter the PAT when prompted

Make sure the

publisher

field in

package.json

matches the publisher ID exactly.

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

访问https://marketplace.visualstudio.com/manage
使用创建PAT时的同一Microsoft账号登录
点击Create publisher
填写信息：
- ID：唯一标识符（创建后无法修改！）
- 名称：在市场上显示的名称
通过运行以下命令验证：
```
vsce login <publisher-id>
```
- 提示时输入PAT

确保

package.json

中的

publisher

字段与发布者ID完全一致。

Step 5: Package the Extension

步骤5：打包扩展

Create a

.vsix

package for testing before publishing:

bash

vsce package

This generates a file like

my-extension-0.0.1.vsix

Test locally before publishing:

bash

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

If there are packaging errors:

Missing README.md: Create a README.md in the project root
SVG icon: Replace with a PNG file (min 128x128px)
Missing license: Add a LICENSE file or set
```
"license"
```
in package.json

在发布前创建

.vsix

包用于测试：

bash

vsce package

这会生成类似

my-extension-0.0.1.vsix

的文件。

发布前本地测试：

bash

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

如果打包出错：

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

Step 6: Publish to Marketplace

步骤6：发布到市场

Once testing is satisfactory, publish:

bash

vsce publish

Version bump options:

bash

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

In git repos,

vsce publish

automatically creates a version commit and tag.

After publishing: The extension appears on the marketplace within ~5 minutes. Verify at:

https://marketplace.visualstudio.com/items?itemName=<publisher>.<extension-name>

测试通过后，执行发布：

bash

vsce publish

版本升级选项：

bash

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    # 设置精确版本

在git仓库中，

vsce publish

会自动创建版本提交和标签。

发布后：扩展会在约5分钟内出现在市场上。通过以下链接验证：

https://marketplace.visualstudio.com/items?itemName=<publisher>.<extension-name>

Step 7: Setup GitHub Actions CI/CD (Optional)

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

If the user wants automated publishing, generate a GitHub Actions workflow.

Copy the template from

assets/github-actions-publish.yml

to the project:

bash

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

Then guide the user to:

Add the PAT as a GitHub secret named
```
VSCE_PAT
```
:
- Go to repo Settings > Secrets and variables > Actions
- Click New repository secret
- Name:
```
VSCE_PAT
```
  , Value: the Azure DevOps PAT
Publishing triggers on git tags matching
```
v*
```
(e.g.,
```
v1.0.0
```
)

To release:

git tag v1.0.0 && git push origin v1.0.0

See

references/publishing-guide.md

for CI/CD customization options.

如果用户需要自动化发布，生成GitHub Actions工作流。

将模板从

assets/github-actions-publish.yml

复制到项目中：

bash

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

然后引导用户完成以下操作：

将PAT添加为名为
```
VSCE_PAT
```
的GitHub密钥：
- 进入仓库Settings > Secrets and variables > Actions
- 点击New repository secret
- 名称：
```
VSCE_PAT
```
  ，值：Azure DevOps PAT
当git标签匹配
```
v*
```
（例如
```
v1.0.0
```
）时触发发布

发布方式：

git tag v1.0.0 && git push origin v1.0.0

查看

references/publishing-guide.md

获取CI/CD自定义选项。

Step Completion Reports

步骤完成报告

After completing each major step, output a status report in this format:

◆ [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

Adapt the check names to match what the step actually validates. Use

√

for pass,

×

for fail, and

—

to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

Pre-flight phase checks:

Node.js available

vsce installed

package.json valid

Auth Setup phase checks:

PAT configured

Publisher verified

Package phase checks:

Extension packaged

Size reasonable

Manifest correct

Publish phase checks:

Upload success

Marketplace live

CI/CD configured

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

◆ [步骤名称] ([第N步/共M步] — [上下文])
··································································
  [检查项1]:          √ 通过
  [检查项2]:          √ 通过（如有相关说明可补充）
  [检查项3]:          × 失败 — [原因]
  [检查项4]:          √ 通过
  符合标准:         √ N/M 已满足
  ____________________________
  结果:             通过 | 失败 | 部分通过

根据步骤实际验证的内容调整检查项名称。用

√

表示通过，

×

表示失败，

—

用于添加简短上下文。“符合标准”行总结已满足的验收标准数量。“结果”行给出整体结论。

预检阶段检查项：

Node.js可用

vsce已安装

package.json有效

认证配置阶段检查项：

PAT已配置

发布者已验证

打包阶段检查项：

扩展已打包

大小合理

清单正确

发布阶段检查项：

上传成功

已上线市场

CI/CD已配置

Examples

示例

Example 1: First-Time Publishing

示例1：首次发布

User says: "I want to publish my VS Code extension to the marketplace"

Actions:

Run preflight checks to verify environment
Validate package.json — fill in any missing required fields
Walk through PAT creation on Azure DevOps
Create publisher identity on marketplace
Login with
```
vsce login
```
Package with
```
vsce package
```
and test locally
Publish with
```
vsce publish
```

Result: Extension live on VS Code Marketplace.

用户需求："我想把我的VS Code扩展发布到市场"

操作步骤：

运行预检检查验证环境
验证package.json —— 补充任何缺失的必填字段
引导用户在Azure DevOps上创建PAT
在市场上创建发布者身份
运行
```
vsce login
```
登录
用
```
vsce package
```
打包并本地测试
用
```
vsce publish
```
发布

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

Example 2: Publish Update with Version Bump

示例2：升级版本并发布

User says: "publish a new minor version of my extension"

Actions:

Run preflight checks
Verify package.json is valid
Run
```
vsce publish minor
```

Result: Version bumped and published (e.g., 1.0.0 → 1.1.0).

用户需求："发布我的扩展的新版本（小版本升级）"

操作步骤：

运行预检检查
验证package.json有效
运行
```
vsce publish minor
```

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

Example 3: Setup CI/CD for Auto-Publishing

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

User says: "create a GitHub Actions workflow to auto-publish my extension"

Actions:

Copy

assets/github-actions-publish.yml

.github/workflows/publish.yml

Guide user to add
```
VSCE_PAT
```
secret to GitHub repo

Explain tagging workflow:

git tag v1.0.0 && git push origin v1.0.0

Result: Extensions auto-publish on version tags.

用户需求："创建GitHub Actions工作流来自动发布我的扩展"

操作步骤：

将

assets/github-actions-publish.yml

复制到

.github/workflows/publish.yml

引导用户将
```
VSCE_PAT
```
密钥添加到GitHub仓库

说明标签工作流：

git tag v1.0.0 && git push origin v1.0.0

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

Error Handling

错误处理

401 Unauthorized / 403 Forbidden

Cause: PAT is invalid, expired, or has wrong scope. Solution:

Regenerate PAT at https://dev.azure.com with:
- Organization: "All accessible organizations"
- Scope: Marketplace > Manage
Re-login:
```
vsce login <publisher-id>
```

原因：PAT无效、过期或权限范围错误。 解决方案：

在https://dev.azure.com重新生成PAT，确保：
- 组织："All accessible organizations"
- 权限范围：Marketplace > Manage
重新登录：
```
vsce login <publisher-id>
```

"Extension already exists"

Cause: Another publisher owns this extension name. Solution: Change the

name

field in

package.json

to something unique. The

displayName

can still be anything.

原因：该扩展名称已被其他发布者占用。 解决方案：修改

package.json

中的

name

字段为唯一值。

displayName

仍可使用任意名称。

SVG Icon Error

SVG图标错误

Cause: Marketplace prohibits SVG icons for security reasons. Solution: Convert the icon to PNG format (minimum 128x128 pixels) and update the

icon

field in

package.json

原因：市场出于安全原因禁止使用SVG图标。 解决方案：将图标转换为PNG格式（最小128x128像素），并更新

package.json

中的

icon

字段。

Missing Fields in package.json

package.json缺少字段

Cause: Required fields are absent. Solution: Run the preflight script to identify missing fields, then add them to

package.json

原因：必填字段缺失。 解决方案：运行预检脚本识别缺失字段，然后添加到

package.json

中。

"Exceeded 30 tags"

Cause: Too many items in the

keywords

array. Solution: Reduce

keywords

to 30 or fewer entries.

原因：

keywords

数组中的条目过多。 解决方案：将

keywords

减少到30个或更少。

vsce package fails with prepublish error

vsce package执行时出现prepublish错误

Cause: The

vscode:prepublish

script in package.json failed. Solution: Run the prepublish script manually to see the error:

bash

npm run vscode:prepublish

Fix the underlying build issue before retrying.

原因：package.json中的

vscode:prepublish

脚本执行失败。 解决方案：手动运行prepublish脚本查看错误：

bash

npm run vscode:prepublish

修复底层构建问题后再重试。