vscode-extension-publisher

VS Code 拡張機能の公開者

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 がない場合、pull を利用できない場合、またはリベース／スタッシュで競合が発生した場合は、作業を中止して続行する前にユーザーに確認してください。

手順

ステップ 1：公開前チェックを実行する

何よりも先に、環境とプロジェクトを検証してください。

同梱の公開前チェック用スクリプトを実行してください。

bash scripts/preflight-check.sh

このスクリプトでは、次の項目を確認します。

• Node.js と npm がインストールされている
• @vscode/vsce がグローバルにインストールされている（ない場合はインストール）
• package.json が存在し、必須フィールドが設定されている
• SVG アイコンがない（Marketplace の制限）

スクリプトを利用できない場合は、手動で確認してください。

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	Marketplace のカテゴリー	["Other"]

Marketplace での表示をより充実させるために、次のフィールドも推奨されます。

フィールド	説明
icon	PNG アイコンへのパス（最小 128x128px、SVG 不可）
repository	GitHub リポジトリの URL
license	ライセンス識別子（例："MIT"）
keywords	検索キーワード（最大 30 個）
galleryBanner.color	Marketplace バナーのカラーコード
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：公開者を作成または確認する（必要な場合）

ユーザーが公開者 ID を持っていない場合は、次の手順を案内してください。

1. https://marketplace.visualstudio.com/manage にアクセスします。
2. PAT に使用したものと同じ Microsoft アカウントでサインインします。
3. Create publisher をクリックします。
4. 次の項目を入力します。
   • ID： 一意の識別子（後から変更できません！）
   • Name： Marketplace に表示される名前
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" を設定します。

Step 6: マーケットプレイスに公開する

テストに問題がなければ、公開します。

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 分以内にマーケットプレイスに表示されます。次の URL で確認してください。 https://marketplace.visualstudio.com/items?itemName=<publisher>.<extension-name>

Step 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 をクリックします。
   • Name：VSCE_PAT、Value：Azure DevOps の PAT
2. v* に一致する Git タグ（例：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」の行には、全体的な判定を記載します。

Pre-flight フェーズのチェック項目： Node.js available、vsce installed、package.json valid

Auth Setup フェーズのチェック項目： PAT configured、Publisher verified

Package フェーズのチェック項目： Extension packaged、Size reasonable、Manifest correct

Publish フェーズのチェック項目： Upload success、Marketplace live、CI/CD configured

例

例 1：初回の公開

ユーザー：「VS Code 拡張機能をマーケットプレイスに公開したいです」

実行する操作：

1. 事前チェックを実行して環境を確認します。
2. package.json を検証し、必須項目が不足していれば入力します。
3. Azure DevOps での PAT 作成手順を案内します。
4. マーケットプレイスでパブリッシャー ID を作成します。
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. GitHub リポジトリに VSCE_PAT シークレットを追加するよう案内します。
3. タグ付けの手順を説明します：git tag v1.0.0 && git push origin v1.0.0

結果：バージョンタグを作成すると、拡張機能が自動公開されます。

エラー処理

401 Unauthorized / 403 Forbidden

原因： PAT が無効、期限切れ、またはスコープが正しくありません。 解決方法：

1. https://dev.azure.com で、次の設定を指定して PAT を再生成します。
   • Organization：「All accessible organizations」
   • Scope：Marketplace > Manage
2. vsce login <publisher-id> で再度ログインします。

「Extension already exists」

原因： 別のパブリッシャーがこの拡張機能名を所有しています。 解決方法： package.json の name フィールドを一意の名前に変更します。displayName は任意の値にできます。

SVG アイコンエラー

原因： セキュリティ上の理由から、マーケットプレイスでは SVG アイコンが禁止されています。 解決方法： アイコンを PNG 形式（最小 128x128 ピクセル）に変換し、package.json の icon フィールドを更新します。

package.json のフィールド不足

原因： 必須フィールドがありません。 解決方法： 事前チェック用スクリプトを実行して不足しているフィールドを特定し、package.json に追加します。

「Exceeded 30 tags」

原因： keywords 配列内の項目が多すぎます。 解決方法： keywords を 30 項目以下に減らします。

vsce package が prepublish エラーで失敗する

原因： package.json の vscode:prepublish スクリプトが失敗しました。 解決策： エラーを確認するため、prepublish スクリプトを手動で実行します。

npm run vscode:prepublish

再試行する前に、根本的なビルドの問題を修正してください。