插件元数据与 SEO

用户在一个插件页面停留的决策时间只有几秒。决定这几秒成败的，是 package.json 里的元数据字段与 README 内容——它们既决定用户在搜索列表里看不看得到你，也决定看到了点不点进来。

完整元数据字段

一份发布级的 package.json 元数据部分：

json

{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "一键格式化代码并实时预览，支持 20 种语言",
  "version": "1.0.0",
  "publisher": "mypublisher",
  "author": "Zhang San <zhangsan@example.com>",
  "license": "MIT",
  "icon": "images/icon.png",
  "galleryBanner": {
    "color": "#1e1e2e",
    "theme": "dark"
  },
  "homepage": "https://github.com/zhangsan/my-extension",
  "repository": {
    "type": "git",
    "url": "https://github.com/zhangsan/my-extension"
  },
  "bugs": {
    "url": "https://github.com/zhangsan/my-extension/issues"
  },
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": ["Formatters", "Linters"],
  "keywords": ["format", "prettier", "beautify", "formatter"],
  "badges": [
    {
      "url": "https://img.shields.io/badge/license-MIT-green.svg",
      "href": "https://github.com/zhangsan/my-extension/blob/main/LICENSE",
      "description": "MIT License"
    }
  ],
  "extensionDependencies": ["vscode.git"],
  "extensionPack": ["mypublisher.my-theme"]
}

身份类字段

字段	作用	是否必填
`name`	插件标识，与 `publisher` 组成全名	必须
`displayName`	搜索列表与插件页显示的标题	必须
`description`	一句话说明，同时是搜索索引内容	必须
`publisher`	发布者 ID，对应 Marketplace 的 Publisher	必须
`author`	作者信息，可含联系方式	建议
`version`	语义化版本号	必须

displayName 与 name 可以不同：name 是程序标识保持稳定，displayName 面向用户展示。改名 name 相当于发布一个全新插件，而 displayName 随时可以调整。

展示类字段

icon 是插件在搜索列表中的缩略图，要求：

PNG 格式，推荐 128x128 像素
小于 256KB
不含透明像素会被 Marketplace 放大糊掉的情况，尺寸建议按官方 128x128 制作

galleryBanner 控制插件页顶部的横幅配色：

json

{
  "galleryBanner": {
    "color": "#1e1e2e",
    "theme": "dark"
  }
}

字段	含义
`color`	横幅背景色，十六进制
`theme`	内容主题，`dark` 或 `light`，决定文字颜色

badges 在插件页顶部展示徽章，常见的徽章类型：

json

{
  "badges": [
    {
      "url": "https://img.shields.io/badge/version-1.0.0-blue.svg",
      "href": "https://marketplace.visualstudio.com/items?itemName=mypublisher.my-extension",
      "description": "当前版本"
    },
    {
      "url": "https://img.shields.io/badge/PRs-welcome-brightgreen.svg",
      "href": "https://github.com/zhangsan/my-extension",
      "description": "欢迎提交 PR"
    }
  ]
}

注意 badges 的图片 URL 必须指向 HTTPS 资源，否则 Marketplace 拒绝展示。

关联类字段

extensionDependencies 声明运行时依赖的其他扩展，安装本插件时会自动安装：

json

{
  "extensionDependencies": ["vscode.git"]
}

extensionPack 声明捆绑的扩展集合，适用于"全家桶"插件：

json

{
  "extensionPack": ["mypublisher.my-theme", "mypublisher.my-icons"]
}

两者区别：

字段	语义	适用场景
`extensionDependencies`	强依赖，缺了功能不可用	需要调用其他扩展 API
`extensionPack`	软捆绑，一起安装但各自独立	主题包、工具集

兼容性字段

engines.vscode 声明插件要求的最低 VS Code 版本：

json

{
  "engines": {
    "vscode": "^1.85.0"
  }
}

版本号必须与 @types/vscode 保持一致。用了新 API 就把 engines.vscode 提到对应版本，否则老版本用户装完发现功能失效，体验很差。

README 与 Marketplace 展示优化

README 是插件页的主体内容，Marketplace 直接渲染它。一份高转化的 README 按如下结构组织。

首屏说明

第一屏（不需要滚动就看到的内容）决定用户去留：

markdown

# My Extension

一键格式化并实时预览代码，支持 20 种语言。

## 特性

- 保存即格式化，零配置开箱即用
- 实时预览格式化结果
- 支持 20 种语言与 40 种代码风格

首屏应包含：插件名称、一句话价值主张、2-3 条核心特性。避免把安装说明和许可证放在最前面——那是用户决定安装之后才关心的事。

GIF 演示

功能型插件用 GIF 演示效果，胜过千言万语：

markdown

## 演示

![format demo](images/demo.gif)

GIF 制作要点：

控制在 2-5 秒循环，单帧短
展示"操作前 → 操作后"的对比
文件大小控制在 1-2MB 内，Marketplace 页面加载更快
录制时使用浅色与深色两套主题各录一段

安装说明

markdown

## 安装

从 VS Code 扩展面板搜索 `My Extension` 一键安装。

或从命令行安装：

    code --install-extension mypublisher.my-extension

也可以手动安装 `.vsix` 文件：扩展面板 → 更多操作 → Install from VSIX...

使用说明与配置

markdown

## 使用

1. 打开任意支持的文件
2. 按 `Shift+Alt+F` 格式化
3. 点击状态栏的预览按钮查看结果

## 配置项

| 配置 | 说明 | 默认值 |
|------|------|--------|
| `myext.formatOnSave` | 保存时自动格式化 | `true` |
| `myext.indentSize` | 缩进宽度 | `2` |

徽章与链接区

markdown

## 链接

- 文档：https://github.com/zhangsan/my-extension/wiki
- 问题反馈：https://github.com/zhangsan/my-extension/issues
- 许可证：MIT

README 编写禁忌

禁忌	原因
只写"xxx 扩展"一句话	信息量不足以促成安装
首屏放长篇安装教程	用户没有耐心看完
图片外链国内无法访问	展示失败，观感差
宣传语过于夸张	与实不符，引发差评
README 缺失	Marketplace 直接拒绝发布

keywords 与 categories 对搜索排名的影响

Marketplace 搜索排名主要受三个因素影响：

关键词匹配：name、displayName、description、keywords、categories 中的文本与搜索词匹配
社区信号：安装量、评分、下载量
元数据完整度：README、图标、许可证齐全的插件排名靠前

keywords 关键词

keywords 是补充描述覆盖不到的场景词，例如插件名是 "Format Helper"，用户可能搜 "beautify"：

json

{
  "keywords": ["format", "beautify", "pretty", "indent", "style"]
}

关键词选择技巧：

用用户会搜的词，而不是技术术语：用户搜 "json 格式化" 不搜 "json serialization"
覆盖同义表达：lint、linter、check 同时收录
6-10 个为宜，过多显得堆砌

categories 分类

categories 决定插件出现在哪个分类页。可选值由 Marketplace 维护，常见的有：

分类	适用插件
`Linters`	代码检查类
`Formatters`	格式化类
`Themes`	颜色主题
`Snippets`	代码片段
`Debuggers`	调试器
`Language Packs`	语言包
`Other`	无法归类的功能

categories 与 keywords 的文本都会进入搜索索引。类别选错会让插件埋没在错误的分区里。

完整的 SEO 写法对比

json

// 差：信息量不足
{
  "name": "helper",
  "displayName": "Helper",
  "description": "a helper extension",
  "categories": ["Other"]
}

json

// 好：标题含核心词，描述写清价值
{
  "name": "json-format-helper",
  "displayName": "JSON Format Helper",
  "description": "格式化与校验 JSON 文件，支持折叠预览与错误定位",
  "categories": ["Formatters"],
  "keywords": ["json", "format", "validate", "prettify", "minify"]
}

持续优化

发布后通过以下渠道收集数据优化元数据：

text

Marketplace 扩展页 → Overview → 查看安装量趋势与搜索来源

安装量低：检查 keywords 是否覆盖用户真实搜索词
转化率低：重写 README 首屏与演示 GIF
差评集中在某功能：在 description 中如实说明边界

元数据是插件的门面工程：搜索靠 keywords 与 categories 找到用户，展示靠 README 与图标留住用户，关联字段决定它与生态的协同方式。

插件元数据与 SEO ​

完整元数据字段 ​

身份类字段 ​

展示类字段 ​

关联类字段 ​

兼容性字段 ​

README 与 Marketplace 展示优化 ​

首屏说明 ​

GIF 演示 ​

安装说明 ​

使用说明与配置 ​

徽章与链接区 ​

README 编写禁忌 ​

keywords 与 categories 对搜索排名的影响 ​

keywords 关键词 ​

categories 分类 ​

完整的 SEO 写法对比 ​

持续优化 ​

插件元数据与 SEO

完整元数据字段

身份类字段

展示类字段

关联类字段

兼容性字段

README 与 Marketplace 展示优化

首屏说明

GIF 演示

安装说明

使用说明与配置

徽章与链接区

README 编写禁忌

keywords 与 categories 对搜索排名的影响

keywords 关键词

categories 分类

完整的 SEO 写法对比

持续优化