git:20260415.0a988da to git:20261015.c21ad69

- description: "VSCode 扩展 (.vsix) 发布知识库与自动化指南。当用户需要发布 VSCode 插件、配置 vsce 自动化发布、解决 VSCode Marketplace PAT 问题、创建 Personal Access Token 时触发。关键词：vsix publish、发布 VSCode 插件、vsce publish、VSCode Marketplace、Open VSX、PAT token。"

- ---

-

- <role>

- 你是 VSCode 扩展发布顾问，帮助用户完成 VSCode 插件的发布流程，从手动发布到自动化发布一站式指导。

- </role>

-

- <purpose>

- 作为 VSIX 发布的知识库，提供两种发布方式的完整指引：手动发布和自动化发布（CI/CD），覆盖 VSCode Marketplace 和 Open VSX Registry。

- </purpose>

-

- <trigger>

- ```text

- vsix publish

- 发布 VSCode 插件

- vsce publish

- VSCode Marketplace

- 发布 vsix

- 发布 VSCode 扩展

- publish vscode extension

- Open VSX

- ovsx publish

- 发布插件到市场

- ```

- </trigger>

-

- ---

-

- # VSIX 发布指南

-

- ## 快速判断

-

- 先确认用户当前状态：

-

- ```bash

- # 检查 vsce 是否已安装

- npx vsce --version 2>&1

-

- # 检查项目是否为 VSCode 扩展

- cat package.json | grep -E '"name"|"version"|"publisher"|"engines"'

-

- # 检查是否已有 Personal Access Token 配置

- cat ~/.vsce 2>/dev/null

- ```

-

- ### PAT 获取策略

-

- 发布需要 `VSCE_PAT`（VSCode Marketplace）和 `OVSX_PAT`（Open VSX），按以下优先级获取：

-

- 1. **读取 CLAUDE.md 配置变量**（推荐，一次配置永久使用）

-

- 检查全局 CLAUDE.md 中的 Skills 配置变量表：

- - `VSCE_PAT`：VSCode Marketplace 发布令牌（Azure DevOps PAT）

- - `OVSX_PAT`：Open VSX Registry 发布令牌

-

- 如已配置，直接使用，无需再次登录。

-

- 2. **CLAUDE.md 未配置 → 引导用户输入**

-

- 使用 AskUserQuestion 询问：

- > "检测到未配置 VSCE_PAT / OVSX_PAT。是否现在配置到全局 CLAUDE.md？配置后后续发布无需重复输入。"

-

- 引导流程：

- - **VSCE_PAT**：前往 [Azure DevOps](https://dev.azure.com) → 头像 → Personal access tokens → New Token

- - Organization: All accessible organizations

- - Scopes: Marketplace → **Manage**

- - **OVSX_PAT**：前往 [open-vsx.org](https://open-vsx.org) → 登录 → Settings → Access Tokens → Create Token

-

- 获取后写入 CLAUDE.md Skills 配置变量表。

-

- 3. **用户拒绝写入 CLAUDE.md → 临时使用**

-

- 通过 `vsce login <publisher>` 存入 `~/.vsce`，仅当次会话有效。

-

- 根据结果引导用户进入对应流程：

- - **未安装 vsce** → `npm install -g @vscode/vsce`

- - **未配置 PAT** → 引导上述 PAT 获取流程

- - **已配置 PAT** → 直接执行 [发布命令](#发布命令)

- - **想配置 CI/CD** → 引导 [自动化发布配置](#自动化发布配置推荐)

-

- ---

-

- ## Reference

-

- ### [手动发布](reference/manual-publish.md)

-

- 适合偶尔发布、首次发布的用户。通过 `vsce` CLI 手动打包并发布到 VSCode Marketplace。

-

- ### [自动化发布配置](reference/auto-publish.md)（推荐）

-

- 适合需要流水线发布的用户。通过 GitHub Actions + PAT 实现自动发布，支持 VSCode Marketplace 和 Open VSX Registry。

-

- ---

-

- ## 发布命令

-

- ### 使用 CLAUDE.md 中的 PAT 发布（推荐）

-

- 当 CLAUDE.md 已配置 `VSCE_PAT` 和 `OVSX_PAT` 时，直接通过环境变量发布：

-

- ```bash

- # 发布到 VSCode Marketplace

- VSCE_PAT="<从 CLAUDE.md 读取>" npx vsce publish

-

- # 发布到 Open VSX Registry

- OVSX_PAT="<从 CLAUDE.md 读取>" npx ovsx publish --no-dependencies

-

- # 同时发布到两个平台

- VSCE_PAT="<从 CLAUDE.md 读取>" npx vsce publish && OVSX_PAT="<从 CLAUDE.md 读取>" npx ovsx publish --no-dependencies

- ```

-

- > **注意**：通过环境变量传递 PAT 时，不需要先执行 `vsce login`，vsce 会优先使用环境变量。

-

- ### 手动一键发布（已通过 vsce login 登录）

-

- ```bash

- # 完整流程：验证 → 打包 → 发布

- npx vsce package && npx vsce publish

- ```

-

- ### 分步执行

-

- ```bash

- # 1. 验证扩展

- npx vsce package --allow-missing-repository # 先试打包，检查是否有问题

-

- # 2. 本地测试 vsix

- code --install-extension *.vsix

-

- # 3. 升版本号（在 package.json 中手动修改，或使用 vsce）

- npx vsce publish patch # 1.0.0 → 1.0.1，自动 git commit + tag + publish

- npx vsce publish minor # 1.0.0 → 1.1.0

- npx vsce publish major # 1.0.0 → 2.0.0

-

- # 4. 仅打包（不发布）

- npx vsce package

-

- # 5. 发布已有 vsix

- npx vsce publish --packagePath my-extension-1.0.0.vsix

- ```

-

- ### 多平台发布

-

- ```bash

- # 同时发布到 VSCode Marketplace 和 Open VSX Registry

- npx vsce publish && npx ovsx publish --no-dependencies

- ```

-

- > **注意**：Open VSX 需要 `--no-dependencies`，否则会尝试安装 devDependencies 导致失败。

-

- ### 关键配置检查

-

- 发布前必须确认 `package.json` 中包含：

-

- ```json

- {

- "name": "extension-name",

- "displayName": "扩展显示名",

- "version": "1.0.0",

- "publisher": "你的Publisher ID",

- "engines": {

- "vscode": "^1.80.0"

- },

- "categories": ["Other"],

- "repository": {

- "type": "git",

- "url": "https://github.com/user/repo.git"

- },

- "vsce": {

- "dependencies": false

- },

- "ovsx": {

- "dependencies": false

- }

- }

- ```

-

- > **重要**：

- > - `publisher` 字段必须与 VSCode Marketplace 注册的 Publisher ID 一致，否则发布会失败

- > - `vsce.dependencies: false` 排除 devDependencies，减小 vsix 包体积

- > - `ovsx.dependencies: false` 同理，Open VSX 也需要

-

- #### VSCode Marketplace 支持的 categories

-

- `categories` 字段决定扩展在 Marketplace 中的分类，必须使用以下官方值：

-

- | 分类 | 说明 |

- |------|------|

- | `Programming Languages` | 编程语言支持 |

- | `Snippets` | 代码片段 |

- | `Themes` | 主题 |

- | `Debuggers` | 调试器 |

- | `Formatters` | 格式化工具 |

- | `Linters` | 代码检查 |

- | `SCM Providers` | 源代码管理 |

- | `Other` | 其他（默认） |

- | `Extension Packs` | 扩展包 |

- | `Language Packs` | 语言包 |

- | `Data Science` | 数据科学 |

- | `Machine Learning` | 机器学习 |

- | `Visualization` | 可视化 |

- | `Notebooks` | 笔记本 |

- | `Education` | 教育 |

- | `Testing` | 测试 |

-

- > 可同时设置多个分类：`"categories": ["Programming Languages", "Snippets"]`

-

- ### .vscodeignore（必须配置）

-

- 控制哪些文件不进入 vsix 包，避免打包源码和开发文件：

-

- ```

- .vscode/**

- .vscode-test/**

- out/**

- node_modules/**

- src/**

- .gitignore

- webpack.config.js

- vsc-extension-quickstart.md

- **/tsconfig.json

- **/.eslintrc.json

- **/*.map

- **/*.ts

- **/.vscode-test.*

- ```

-

- > **原则**：只保留运行时需要的文件（编译产物 `dist/`、`package.json`、`README.md`、`CHANGELOG.md`、icon 等）。

-

- ### vscode:prepublish 脚本

-

- `vsce publish` 会自动执行 `vscode:prepublish` 脚本，确保发布前自动构建：

-

- ```json

- {

- "scripts": {

- "vscode:prepublish": "pnpm run package",

- "build": "webpack --mode production --devtool hidden-source-map",

- "package:vsix": "vsce package",

- "publish:vsce": "vsce publish",

- "publish:ovsx": "ovsx publish --no-dependencies",

- "publish:all": "pnpm run publish:vsce && pnpm run publish:ovsx",

- "deploy": "pnpm run build && pnpm run publish:all"

- }

- }

- ```

-

- > **注意**：`ovsx publish` 需要 `--no-dependencies` 标志，因为 Open VSX 不会自动跳过 devDependencies。

-

- ### 包管理器支持

-

- | 包管理器 | 安装 vsce | 打包命令 |

- |----------|----------|----------|

- | **npm** | `npm install -g @vscode/vsce` | `npx vsce package` |

- | **pnpm** | `pnpm add -g @vscode/vsce` | `pnpm run package:vsix` |

- | **yarn** | `yarn global add @vscode/vsce` | `yarn vsce package` |

-

- ## 常见错误

-

- | 错误 | 原因 | 解决 |

- |------|------|------|

- | `Missing publisher name` | package.json 缺少 publisher 字段 | 添加 `"publisher": "你的ID"` |

- | `Publisher not found` | Publisher ID 未在 Marketplace 注册 | 前往 [marketplace.visualstudio.com](https://marketplace.visualstudio.com/) 注册 |

- | `Unauthorized` | PAT 无效或过期 | 重新生成 Personal Access Token |

- | `Extension already exists` | 版本号已发布 | 升版本号后重试 |

- | `Missing repository` | package.json 缺少 repository 字段 | 添加 repository 配置，或使用 `--allow-missing-repository` |

- | `Invalid icon` | icon 路径错误或格式不支持 | 检查 icon 路径，使用 PNG 格式 |

- | `ENOENT: no such file` | .vsix 文件路径错误 | 使用 `--packagePath` 指定正确路径 |

- | `vsce command not found` | 未安装 vsce | `npm install -g @vscode/vsce` |

- | `Pat token scope error` | PAT 权限不足 | 确保勾选 **Marketplace > Manage** 权限 |

-

- ---

- ## 交互式引导

- 当用户不确定如何操作时，使用 AskUserQuestion 引导：

- ### 情况 1：用户首次发布 VSCode 扩展

- 1. 确认项目有 `package.json` 且包含 `name`、`version`、`publisher`、`engines.vscode`

- 2. 引导注册 Publisher（如未注册）

- 3. 引导创建 Personal Access Token

- 4. 使用 `vsce login <publisher>` 登录

- 5. 执行 `vsce publish`

- ### 情况 2：用户遇到 PAT/认证问题

- 1. 解释原因：VSCode Marketplace 使用 Azure DevOps PAT 进行认证

- 2. 引导用户前往 Azure DevOps 创建新 PAT

- 3. 使用 `vsce login <publisher>` 重新登录

- 4. 验证后执行发布

- ### 情况 3：用户想配置 CI/CD 自动发布

- 1. 引导创建 PAT（需勾选 Marketplace > Manage 权限）

- 2. 将 PAT 存入 GitHub Secrets (`VSCE_PAT` / `OVSX_PAT`)

- 3. 创建 `.github/workflows/vsix-publish.yml`